RTU'lar öncelikle acil durum kapatmaları gibi öngöremediğiniz güncellemeler veya düzenli olarak değişen meta veriler (ör. tahmini varış zamanları) için tasarlanmıştır. Değişikliğinizin hemen yansıtılması gerekmiyorsa bunun yerine toplu feed alımını kullanabilirsiniz. Anlık güncellemeler en fazla beş dakika içinde işlenir.
Google Cloud Platform kurulumu
- GCP projesi oluşturun. RTU API'ye erişmek için bir GCP projesi gerekir.
- food-support@google.com adresine düzenleyici erişimi verin.
- Google İletişim Noktanızı GCP proje numarası hakkında bilgilendirin.Gerçek zamanlı güncellemelerin çalışması için GCP projenizin İşlemler Merkezi hesabınızla ilişkilendirilmesi gerekir.
- Maps Booking API'yi etkinleştirin:
- GCP'de API'ler ve Hizmetler > Kitaplık'a gidin.
- "Google Maps Booking API"yi arayın.
- Sandbox örneğini ("Google Maps Booking API (Dev)") bulun ve Etkinleştir'i tıklayın.
- Üretim örneğini ("Google Maps Booking API") bulun ve Etkinleştir'i tıklayın.
- GCP projenizde düzenleyici rolüne sahip bir hizmet hesabı oluşturun. Daha fazla bilgi için Hizmet hesabı kurulumu başlıklı makaleyi inceleyin.
- Toplu feed'leri, anlık güncellemeler üzerinde çalıştığınız ortama yüklediğinizden emin olun.
- API kimlik doğrulaması için Google istemci kitaplığını tercih ettiğiniz dilde yüklemenizi öneririz. OAuth kapsamı olarak "https://www.googleapis.com/auth/mapsbooking" kullanın. Aşağıda yer alan kod örneklerinde bu kitaplıklar kullanılmaktadır. Aksi takdirde, Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde açıklandığı gibi jeton değişimlerini manuel olarak yapmanız gerekir.
Hizmet hesabı kurulumu
Gerçek zamanlı güncellemeler API'si gibi Google API'lerine kimliği doğrulanmış HTTPS istekleri göndermek için hizmet hesabına ihtiyacınız vardır.
Hizmet hesabı oluşturmak için aşağıdakileri yapın:
- Google Cloud Platform Console'a erişin.
- İşlemler Merkezi'ndeki hesabınızla ilişkili bir Google Cloud projesi de olmalıdır. Henüz seçilmediyse ilgili projeyi seçin.
- Soldaki menüde Hizmet Hesapları'nı tıklayın.
- Create Service Account'u (Hizmet Hesabı Oluştur) tıklayın.
- Hizmet hesabı için bir ad girip Oluştur'u tıklayın.
- Rol seçin bölümünde Proje > Düzenleyici'yi seçin.
- Devam'ı tıklayın.
- İsteğe bağlı: Kullanıcılara hizmet hesabına erişim izni vermek için kullanıcı ekleyin ve Bitti'yi tıklayın.
- Yeni oluşturduğunuz hizmet hesabı için diğer > Anahtar oluştur'u tıklayın.
- Biçim olarak JSON'ı seçip Oluştur'u tıklayın.
- Yeni herkese açık/özel anahtar çiftiniz oluşturulduktan sonra makinenize indirin.
API ile çalışma
Gerçek Zamanlı Güncellemeler API'si iki tür işlemi destekler: Güncelleme ve Silme. Gerçek zamanlı güncelleme API'si aracılığıyla yeni öğe ekleme desteklenmez. Tek bir API isteğine birden fazla güncelleme eklerseniz gerçek zamanlı güncellemeler toplu olarak gönderilebilir. Tek bir API çağrısında 1.000'e kadar güncellemeyi toplu olarak gönderebilirsiniz. Mümkünse, sıklığa dayalı bir yaklaşım (ör. sisteminizi X dakikada bir değişiklikler için tarama) yerine, RTU aracılığıyla güncelleme göndermek için tetikleyici tabanlı bir yaklaşım (ör. sisteminizdeki bir veri değişikliğinde Google'a gerçek zamanlı bir güncelleme tetikleme) kullanmanızı öneririz.
Anlık güncellemeler API'si hem test hem de üretim ortamlarında çalışır. API isteklerini test etmek için test ortamı, Uçtan Uca Sipariş kullanıcılarına görünen içeriği güncellemek için ise üretim ortamı kullanılır.
- Korumalı alan -
partnerdev-mapsbooking.googleapis.com - Üretim -
mapsbooking.googleapis.com
Uç noktalar
Gerçek zamanlı güncellemeler API'si, envanter güncellemeleriyle ilgili gelen istekleri işlemek için iki uç nokta sunar:
- GÜNCELLEME -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - SİL -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
PARTNER_ID parametresi, aşağıdaki ekran görüntüsünde gösterildiği gibi İşlemler Merkezi'ndeki Hesap ve kullanıcılar sayfasında bulunabilir.
Yukarıdaki ekran görüntüsünde PARTNER_ID değeri olarak 10000001'i örnek alırsak API isteklerini test ortamında ve üretimde göndermek için kullanılan tam URL'ler aşağıdaki örneklerdeki gibi görünür.
Korumalı alan güncellemesi
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Üretim güncellemesi
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Production DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Öğeleri güncelleme
Envanterinizdeki öğeleri güncellemek için HTTP POST isteğinde update uç noktasını kullanın. Her POST isteği, güncellemek istediğiniz öğeyi içeren bir JSON yüküyle birlikte 10000001 parametresini içermelidir.
Not: Günlük veri feed'lerinizin, anlık güncellemeler API'si aracılığıyla gönderilen tüm değişiklikleri de içerdiğinden emin olun. Aksi takdirde verileriniz güncel olmayabilir veya eski olabilir.
İstek yükünü güncelleme
İstek gövdesi, kayıt listesi içeren bir JSON nesnesidir. Her kayıt, güncellenen bir öğeye karşılık gelir. Bu, proto_record alanı ve öğe güncelleme zamanını gösteren generation_timestamp alanından oluşur:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: Güncellediğiniz ServiceData varlığının proto veya JSON çevirisi.UPDATE_TIMESTAMP: Varlığın oluşturulduğu zaman damgasını arka uç sistemlerinize eklediğinizden emin olun. Bu alan dahil edilmezse Google'ın isteği aldığı zamana ayarlanır. Bir varlıkbatchPushisteği aracılığıyla güncellenirken varlık sürümü oluşturma içingeneration_timestampalanı kullanılır. İlişkisel envanter şemasında zaman değerlerinin beklenen biçimini inceleyin.
- Yük gövdesi 5 MB'ı geçmemelidir.
- Boyutu küçültmek için boşlukları kaldırın.
batchPushisteğinde en fazla 1.000 güncelleme olabilir.
Örnekler
Genişletilmiş metin reklam güncelleme
Bir teslimat hizmetinin tahmini varış süresini 30-60 dakikadan 60-90 dakikaya acilen güncellemeniz gerektiğini varsayalım. Güncellemeniz, tüm Hizmet öğesinin JSON'unu içermelidir.
Aşağıdaki gibi bir hizmet öğesi düşünün:
{ "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" } }
HTTP POST ile yaptığınız anlık güncelleme aşağıdaki gibidir (istek gövdeleri okunabilirlik için oldukça iyi biçimlendirilmiştir):
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" }] }
Birden fazla öğeyi güncelleme
Tek bir API çağrısında birden fazla restoran öğesini güncellemek için istek gövdesinin proto_record alanına birden fazla kayıt ekleyin.
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" }] }
Varlıkları silme
Envanterinizdeki öğeleri silmek için HTTP POST isteğinde DELETE uç noktasını kullanın. Her POST isteği, silmek istediğiniz öğenin tanımlayıcısını içeren JSON yüküyle birlikte PARTNER_ID parametresini içermelidir.
Not: Günlük veri feed'lerinizin, anlık güncelleme API'si aracılığıyla gönderilen tüm değişiklikleri de içerdiğinden emin olun. Aksi takdirde, günlük toplu alım işlemi, anlık değişikliklerinizin üzerine yazar.
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" }] }
Öğe ekleme
Yeni öğeler eklemek için anlık güncellemeleri kullanmayın. Aksi takdirde veri tutarsızlıkları oluşabilir. Bunun yerine toplu feed'leri kullanın.
Doğrulama ve API yanıt kodları
Anlık güncelleme API çağrıları üzerinde iki tür doğrulama gerçekleştirilir:
- İstek düzeyi: Bu doğrulama, yükün şemaya uyduğunu ve her
proto_recordöğesininidvetypealanlarını içerdiğini kontrol eder. Bu kontroller eşzamanlıdır ve sonuçlar API yanıt gövdesinde döndürülür. 200 yanıt kodu ve boş bir JSON gövdesi{}, bu doğrulamaların başarılı olduğunu ve söz konusu isteğin içindeki öğelerin işlenmek üzere sıraya alındığını gösterir. 200 dışında bir yanıt kodu, bu doğrulama işlemlerinden bir veya daha fazlasının başarısız olduğu ve tüm isteğin (yükteki tüm öğeler dahil) reddedildiği anlamına gelir. Örneğin, birproto_recordöğesinde@typeeksikse aşağıdaki hata yanıtı döndürülür:
{ "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." } ] }
- Öğe düzeyi: Yükteki her öğe (proto_record) şemaya göre doğrulanır. Doğrulamanın bu aşamasında karşılaşılan sorunlar API yanıtında bildirilmez. Yalnızca İşlem Merkezi'nin RTU Raporlama kontrol panelinde raporlanır.
Not: 200 yanıt kodu, tüm öğelerin başarıyla alındığı anlamına gelmez.
API kotaları
Gerçek zamanlı API güncellemeleri için 60 saniyede 1.500 istek veya ortalama olarak saniyede 25 istek kotası vardır. Kota aşıldığında Google aşağıdaki hata mesajıyla yanıt verir:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}Bunu çözmek için başarılı olana kadar görüşmeyi katlanarak artan aralıklarla tekrar deneyin. Kotayı düzenli olarak tüketiyorsanız tek bir API isteğine daha fazla öğe eklemeyi düşünebilirsiniz. Tek bir API çağrısına en fazla 1.000 öğe ekleyebilirsiniz.
İşlem süreleri ve anlık güncellemeler
Gerçek zamanlı güncelleme yoluyla güncellenen bir öğe 5 dakika içinde işlenir.