RTU utamanya ditujukan untuk info terbaru yang tidak dapat Anda perkirakan, seperti penutupan darurat, atau metadata yang berubah secara berkala (seperti PWT). Jika perubahan tidak perlu segera ditampilkan, Anda dapat menggunakan penyerapan feed batch. Update real-time diproses dalam waktu tidak lebih dari lima menit.
Penyiapan Google Cloud Platform
- Siapkan project GCP. Project GCP diperlukan untuk mengakses RTU API.
- Memberikan akses editor food-support@google.com
- Beri tahu Google POC Anda mengenai nomor project GCP.Project GCP Anda harus dikaitkan dengan akun Pusat Tindakan agar pembaruan real-time dapat berfungsi.
- Aktifkan Booking API Maps:
- Di GCP, buka APIs & Services > Library.
- Telusuri “Google Maps Booking API”.
- Temukan instance Sandbox (“Google Maps Booking API (Dev)”) dan klik Enable
- Temukan instance Produksi (“Google Maps Booking API”) lalu klik Aktifkan
- Buat akun layanan dengan peran editor untuk project GCP Anda. Untuk mengetahui detail selengkapnya, lihat Pembuatan akun layanan.
- Pastikan Anda mengupload feed batch ke lingkungan tempat Anda mengerjakan update real-time.
- Untuk autentikasi API, sebaiknya instal library Klien Google dalam bahasa pilihan Anda. Menggunakan “https://www.googleapis.com/auth/mapsbooking” sebagai cakupan OAuth. Contoh kode yang disertakan di bawah menggunakan library ini. Jika tidak, Anda harus menangani pertukaran token secara manual seperti yang dijelaskan dalam Menggunakan OAuth 2.0 untuk Mengakses Google API.
Pembuatan akun layanan
Anda memerlukan akun layanan untuk membuat permintaan HTTPS yang diautentikasi ke Google API, seperti API update real-time.
Untuk menyiapkan akun layanan, lakukan hal berikut:
- Mengakses konsol Google Cloud Platform.
- Akun Anda di Actions Center juga memiliki project Google Cloud yang terkait dengannya. Pilih project tersebut, jika belum dipilih.
- Klik Akun Layanan di menu kiri.
- Klik Create Service Account.
- Masukkan nama untuk akun layanan, lalu klik Create.
- Untuk Select a role, pilih Project > Editor.
- Klik Continue.
- Opsional: Tambahkan pengguna untuk memberi mereka akses ke akun layanan, lalu klik Selesai.
- Klik lainnya > Buat kunci untuk akun layanan yang baru saja Anda buat.
- Pilih JSON sebagai format dan klik Buat.
- Setelah pasangan kunci umum/pribadi baru dihasilkan, unduh ke komputer Anda.
Menggunakan API
API Update real-time mendukung dua jenis operasi: Update dan Delete. Penambahan entity baru melalui API update real-time tidak didukung. Update real-time dapat dikelompokkan jika Anda menyertakan beberapa update dalam satu permintaan API. Anda dapat mengelompokkan hingga 1.000 update dalam satu panggilan API. Sebaiknya gunakan pendekatan berbasis pemicu untuk mengirim update melalui RTU (yaitu saat perubahan data dalam sistem Anda memicu update real-time ke Google), bukan pendekatan berbasis frekuensi (yaitu setiap X menit untuk memindai sistem Anda untuk menemukan perubahan) jika memungkinkan.
API update real-time beroperasi di lingkungan sandbox dan lingkungan produksi. Lingkungan sandbox digunakan untuk menguji permintaan API dan lingkungan produksi untuk memperbarui konten yang terlihat oleh pengguna Pemesanan End-to-End.
- Sandbox -
partnerdev-mapsbooking.googleapis.com
- Produksi -
mapsbooking.googleapis.com
Endpoint
API update real-time mengekspos dua endpoint untuk menangani permintaan masuk untuk update inventaris:
- INFO TERBARU -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
- HAPUS -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Parameter PARTNER_ID dapat ditemukan di Pusat Tindakan pada halaman Akun dan pengguna, seperti yang ditunjukkan pada screenshot di bawah.
![ID Partner di Portal Partner](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/verticals/ordering/images/rtu-partnerid.png?authuser=6&hl=id)
Dengan mengambil 10000001 sebagai nilai PARTNER_ID sebagai contoh dari screenshot di atas, URL lengkap untuk mengirim permintaan API di sandbox dan produksi akan terlihat seperti dalam contoh di bawah.
Update sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
HAPUS dengan Sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Update produksi
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
HAPUS Produksi
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Mengupdate entity
Untuk memperbarui entity dalam inventaris Anda, gunakan endpoint update dalam permintaan HTTP POST. Setiap permintaan POST harus menyertakan parameter 10000001 beserta payload JSON yang berisi entity yang ingin Anda update.
Catatan: Pastikan feed data harian Anda juga berisi perubahan yang dikirimkan melalui API update real-time. Jika tidak, data Anda mungkin sudah tidak berlaku atau tidak berlaku lagi.
Mengupdate payload permintaan
Isi permintaan adalah objek JSON dengan daftar record. Setiap kumpulan data berkaitan dengan entitas yang diperbarui. Ini terdiri dari kolom proto_record
dan generation_timestamp
yang menunjukkan waktu pembaruan entity:
{ "records": [ { "proto_record":"ServiceData PROTO", "generation_timestamp":"UPDATE_TIMESTAMP" } ] }
ServiceData PROTO
: Terjemahan proto atau JSON dari entity ServiceData yang sedang Anda update.UPDATE_TIMESTAMP
: Pastikan untuk menyertakan stempel waktu saat entity dibuat di sistem backend Anda. Jika kolom ini tidak disertakan, kolom ini akan disetel ke waktu saat Google menerima permintaan. Saat mengupdate entity melalui permintaanbatchPush
, kolomgeneration_timestamp
digunakan untuk pembuatan versi entity. Lihat format nilai waktu yang diharapkan dalam skema inventaris relasional.
- Ukuran isi payload tidak boleh melebihi 5 MB.
- Menghapus spasi kosong untuk mengurangi ukuran.
- Dapat terdapat hingga 1.000 update dalam permintaan
batchPush
.
Contoh
Memperbarui PWT
Misalkan Anda sangat perlu memperbarui PWT layanan pengiriman dari 30-60 menjadi 60-90 menit. Update Anda harus berisi JSON untuk seluruh entity Layanan.
Pertimbangkan entity layanan yang terlihat seperti berikut:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
Update real-time Anda oleh HTTP POST adalah sebagai berikut (isi permintaan cukup dicetak agar mudah dibaca):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
Memperbarui beberapa entity
Untuk memperbarui beberapa entity restoran dalam satu panggilan API, sertakan beberapa kumpulan data di kolom proto_record dalam isi permintaan.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
Menghapus entity
Untuk menghapus entity dari inventaris Anda, gunakan endpoint DELETE dalam permintaan HTTP POST. Setiap permintaan POST harus menyertakan parameter PARTNER_ID beserta payload JSON yang berisi ID entitas yang ingin Anda hapus.
Catatan: Pastikan feed data harian Anda juga berisi perubahan yang dikirimkan melalui API update real-time. Jika tidak, penyerapan batch harian akan menimpa perubahan real-time Anda.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
Menambahkan entity
Jangan gunakan pembaruan real-time untuk menambahkan entitas baru karena dapat menyebabkan inkonsistensi data. Sebagai gantinya, gunakan feed batch.
Validasi & kode respons API
Ada dua jenis validasi yang dilakukan pada panggilan API update real-time:
- Level permintaan - Validasi ini memeriksa apakah payload mengikuti skema dan setiap
proto_record
berisi kolomid
dantype
. Pemeriksaan ini sinkron dan hasilnya ditampilkan dalam isi respons API. Kode respons 200 dan isi JSON kosong{}
berarti validasi ini lulus dan entity dalam permintaan tersebut dimasukkan ke dalam antrean untuk diproses. Kode respons non-200 berarti satu atau beberapa validasi ini gagal dan seluruh permintaan ditolak (termasuk semua entitas dalam payload). Misalnya, jikaproto_record
tidak memiliki@type
, respons error berikut akan ditampilkan:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- Tingkat entitas: Setiap entitas (proto_record) dalam payload divalidasi berdasarkan skema. Masalah yang ditemui pada fase validasi ini tidak dilaporkan dalam respons API. Tindakan ini hanya dilaporkan di dasbor Pelaporan RTU pada Pusat Tindakan.
Catatan: Kode respons 200 tidak berarti bahwa semua entity berhasil diserap.
Kuota API
Update API real-time memiliki kuota 1.500 permintaan setiap 60 detik, atau rata-rata 25 permintaan per detik. Jika kuota terlampaui, Google akan merespons dengan pesan error berikut:
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
Untuk menangani hal ini, coba lagi panggilan pada interval yang meningkat secara eksponensial hingga berhasil. Jika Anda sering menghabiskan kuota, pertimbangkan untuk menyertakan lebih banyak entity dalam satu permintaan API. Anda dapat menyertakan hingga 1.000 entity dalam satu panggilan API.
Waktu pemrosesan update real-time
Entity yang diperbarui melalui update real-time diproses dalam 5 menit.