Tautan Tindakan Lokasi

Kelola tombol tindakan Google untuk suatu lokasi (pemesanan, pengantaran, bawa pulang, reservasi, janji temu) melalui Listings API.

Tautan tindakan lokasi adalah tombol tindakan yang ditampilkan Google pada profil bisnis: Order online (Pesan online), Get delivery (Pesan antar), Reserve a table (Reservasi meja), Book an appointment (Buat janji temu), dan sebagainya. Listings API mengelolanya sebagai bagian dari lokasi, sehingga Anda mengaturnya melalui endpoint pembuatan dan pembaruan yang sudah Anda gunakan, dan membacanya kembali melalui setiap endpoint pembacaan lokasi.

Field `placeActionLinks`

Operasi pembuatan dan pembaruan sama-sama menerima array placeActionLinks pada input. Setiap elemen:

Field	Tipe	Wajib	Deskripsi
`placeActionType`	enum	ya	Salah satu tipe yang valid di bawah ini.
`uri`	string	ya	URL tujuan.
`isPreferred`	boolean	tidak	Menandai tautan ini sebagai tautan pilihan untuk tipenya. Maksimal satu tautan pilihan per tipe.
`action`	string	tidak	`add` (nilai default) atau `delete`. Hanya digunakan saat pembaruan.
`name`	string	tidak	Pengenal tautan, yang dikembalikan oleh endpoint pembacaan setelah tautan disinkronkan ke Google. Opsional saat penulisan; sertakan jika tersedia untuk menargetkan tautan tersimpan tertentu dengan paling akurat.

Nilai placeActionType yang valid:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

Cara tautan dicocokkan (untuk pengeditan / penghapusan): berdasarkan name jika ada, atau berdasarkan placeActionType + uri jika tidak ada. Sertakan name jika Anda memilikinya (dari hasil pembacaan) untuk pencocokan yang paling akurat. Tautan yang baru ditambahkan dan belum disinkronkan ke Google tidak memiliki name, sehingga dicocokkan berdasarkan placeActionType + uri.

Tindakan

Model penulisannya adalah append/upsert, bukan penggantian. Saat pembaruan, hanya tautan yang Anda rujuk yang terpengaruh; tautan yang tidak Anda sertakan dibiarkan tanpa perubahan.

Tindakan	Tujuan	Pencocokan
`add`	Tambahkan tautan baru, atau perbarui `uri` / `isPreferred` pada tautan tersimpan tersebut.	`name` jika ada, atau `placeActionType` + `uri` jika tidak ada
`delete`	Hapus tautan tersimpan dan masukkan penghapusannya dari Google ke antrean.	`name` jika ada, atau `placeActionType` + `uri` jika tidak ada

Untuk mengubah URL tautan, hapus tautan lama dan tambahkan tautan baru dalam permintaan yang sama (lihat Mengubah URL tautan).

Alur yang direkomendasikan

Ada dua cara yang didukung untuk mengisi tautan tindakan suatu lokasi dan menjaganya tetap sinkron dengan Google.

Alur 1: buat di Google terlebih dahulu, lalu hubungkan

Pemilik bisnis menyiapkan tautan tindakan lokasi langsung di Google Business Profile miliknya.
Lokasi Google Business Profile tersebut dihubungkan ke Listings API.
Saat dihubungkan, Listings API mengambil tautan aktif dari Google ke dalam kumpulan tautan yang dikelola untuk lokasi tersebut. Anda tidak perlu memasukkannya kembali melalui API.

Alur 2: buat di Listings API terlebih dahulu, lalu hubungkan

Buat lokasi di Listings API beserta tautan tindakan lokasinya (buat lokasi), atau tambahkan tautan tersebut nanti (perbarui lokasi).
Saat dihubungkan ke Google Business Profile, Listings API mengambil tautan aktif dan menggabungkannya dengan kumpulan tautan yang dikelola:
- tautan yang cocok tanpa ambiguitas masuk ke dalam kumpulan tautan yang dikelola;
- tautan apa pun di Google yang tidak dapat digabungkan secara otomatis (atau yang belum ada dalam kumpulan tautan yang dikelola) ditampilkan di bagian discoveredPlaceActionLinks untuk Anda tinjau.
Pada setiap pengiriman ke Google, Listings API memeriksa ulang tautan aktif. Setiap tautan baru yang ditemukan langsung di Google Business Profile dan tidak dikelola oleh Listings API ditambahkan ke discoveredPlaceActionLinks.

Tautan yang ditemukan

Tautan yang ditemukan adalah tautan tindakan tempat yang ada di profil Google bisnis tetapi tidak dikelola di Listings API. Tautan ini diambil melalui alur di atas (tautan tambahan yang ditemukan saat menghubungkan, atau tautan baru yang ditemukan pada pengiriman berikutnya) dan dikembalikan secara terpisah dari tautan yang Anda kelola, di bawah discoveredPlaceActionLinks (dengan struktur yang sama seperti placeActionLinks), oleh setiap endpoint baca: daftar, berdasarkan ID, berdasarkan kode toko, dan pencarian.

JSON

{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

Ambil alih pengelolaan tautan yang ditemukan

Untuk mulai mengelola tautan yang ditemukan, kirim tautan tersebut ke perbarui lokasi dengan action: "add", menggunakan panggilan yang sama seperti saat menambahkan tautan apa pun (diidentifikasi oleh placeActionType + uri). Tautan lain tidak diubah.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

Setelah itu, tautan tersebut muncul di bawah placeActionLinks dan dihapus dari discoveredPlaceActionLinks. Tautan yang ditemukan tetapi tidak Anda ambil alih pengelolaannya akan tetap tercantum (dan akan hilang dengan sendirinya jika kemudian tidak lagi ada di Google); tidak diperlukan tindakan apa pun.

Contoh

Setiap pembaruan mengembalikan kumpulan placeActionLinks lokasi yang lengkap dan terkini (yang mencerminkan perubahan tersebut). Tepat setelah operasi tulis, name dan submissionStatus pada tautan bernilai null; keduanya akan terisi setelah tautan disinkronkan ke Google.

Tambahkan tautan

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Ubah URL tautan

Perubahan URL dilakukan dengan menghapus tautan lama dan menambahkan tautan baru dalam permintaan yang sama. Jika tautan lama sudah disinkronkan ke Google, sertakan name miliknya pada delete agar pencocokan seakurat mungkin; jika belum, placeActionType + uri digunakan.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Untuk hanya mengubah isPreferred (dengan URL yang sama), kirim ulang tautan dengan action: "add" dan nilai baru.

Hapus tautan

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

Buat lokasi dengan tautan

Saat pembuatan, setiap tautan merupakan tautan baru, sehingga nilai default action adalah add.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

Catatan

Maksimal satu tautan pilihan per jenis.
submissionStatus pada tautan mencerminkan sinkronisasi terakhir ke Google (success, failed, dan seterusnya), dengan submissionMessage yang dapat dibaca manusia.
Google hanya menerapkan tautan tindakan tempat pada lokasi yang telah diverifikasi.