Echtzeitaktualisierungen sind in erster Linie für Updates gedacht, die Sie nicht vorhersehen können, z. B. Notfallschließungen oder Metadaten, die sich regelmäßig ändern (z. B. voraussichtliche Ankunftszeiten). Wenn Ihre Änderung nicht sofort übernommen werden muss, können Sie stattdessen die Batchfeedaufnahme verwenden. Echtzeitaktualisierungen werden in maximal fünf Minuten verarbeitet.
Google Cloud Platform einrichten
- GCP-Projekt einrichten Für den Zugriff auf die RTU API ist ein GCP-Projekt erforderlich.
- Mitbearbeiterzugriff gewähren: food-support@google.com
- Teilen Sie Ihrem Google-Ansprechpartner die Google Cloud-Projektnummer mit.Ihr GCP-Projekt muss mit Ihrem Actions Center-Konto verknüpft sein, damit Aktualisierungen in Echtzeit funktionieren.
- Maps Booking API aktivieren:
- Gehen Sie in der GCP zu APIs und Dienste > Mediathek.
- Suchen Sie nach „Google Maps Booking API“. <ph type="x-smartling-placeholder">
- Suchen Sie die Sandbox-Instanz („Google Maps Booking API (Dev)“) und klicken Sie auf Aktivieren.
- Suchen Sie die Produktionsinstanz („Google Maps Booking API“) und klicken Sie auf Aktivieren. <ph type="x-smartling-placeholder">
- Erstellen Sie ein Dienstkonto mit der Rolle „Bearbeiter“ für Ihr GCP-Projekt. Weitere Informationen finden Sie unter Dienstkonto einrichten.
- Stellen Sie sicher, dass Sie Batch-Feeds in die Umgebung hochladen, in der Sie an Echtzeitaktualisierungen arbeiten.
- Für die API-Authentifizierung empfehlen wir die Installation der Google-Clientbibliothek in der Sprache Ihrer Wahl. Verwenden Sie „https://www.googleapis.com/auth/mapsbooking“ als OAuth-Bereich. Diese Bibliotheken werden in den unten aufgeführten Codebeispielen verwendet. Andernfalls müssen Sie den Tokenaustausch manuell durchführen, wie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden beschrieben.
Dienstkonto einrichten
Sie benötigen ein Dienstkonto, um authentifizierte HTTPS-Anfragen an Google APIs wie die Real-Time Updates API zu senden.
So richten Sie ein Dienstkonto ein:
- Rufen Sie die Google Cloud Platform Console auf.
- Mit Ihrem Konto im Actions Center ist auch ein Google Cloud-Projekt verknüpft. Wählen Sie dieses Projekt aus, falls es noch nicht ausgewählt ist.
- Klicken Sie im Menü auf der linken Seite auf Dienstkonten.
- Klicken Sie auf Dienstkonto erstellen.
- Geben Sie einen Namen für das Dienstkonto ein und klicken Sie auf Erstellen.
- Wählen Sie unter Rolle auswählen die Rolle Projekt > Editor:
- Klicken Sie auf Weiter.
- Optional: Fügen Sie Nutzer hinzu, um ihnen Zugriff auf das Dienstkonto zu gewähren, und klicken Sie auf Fertig.
- Klicken Sie auf Mehr > Erstellen Sie einen Schlüssel für das gerade erstellte Dienstkonto.
- Wählen Sie JSON als Format aus und klicken Sie auf Erstellen.
- Nachdem Sie ein neues öffentliches/privates Schlüsselpaar generiert haben, laden Sie es auf Ihren Computer herunter.
Mit der API arbeiten
Die Real-time Updates API unterstützt zwei Arten von Vorgängen: Aktualisieren und Löschen. Das Hinzufügen neuer Entitäten über die API für Echtzeitaktualisierungen wird nicht unterstützt. Echtzeitaktualisierungen können in Batches zusammengefasst werden, wenn eine einzelne API-Anfrage mehrere Aktualisierungen umfasst. In einem API-Aufruf können bis zu 1.000 Aktualisierungen zusammengefasst werden. Wir empfehlen einen Trigger-basierten Ansatz, um Aktualisierungen über Echtzeitdaten zu senden (z.B. wenn eine Datenänderung in Ihrem System eine Echtzeit-Aktualisierung an Google auslöst), anstatt einen häufigkeitsbasierten Ansatz (z.B. alle x Minuten, die Ihr System auf Änderungen scannen), zu verwenden.
Die Real-Time Updates API funktioniert sowohl in der Sandbox- als auch in der Produktionsumgebung. Die Sandbox-Umgebung wird zum Testen der API-Anfragen und die Produktionsumgebung verwendet, um die Inhalte zu aktualisieren, die für End-to-End-Nutzer des Bestellvorgangs sichtbar sind.
- Sandbox –
partnerdev-mapsbooking.googleapis.com
- Produktion –
mapsbooking.googleapis.com
Endpunkte
Die API für Echtzeitaktualisierungen stellt zwei Endpunkte zur Verfügung, um die eingehenden Anfragen für Inventaraktualisierungen zu verarbeiten:
- AKTUALISIEREN –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
- LÖSCHEN –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Sie finden den Parameter PARTNER_ID im Actions Center auf der Seite Konto und Nutzer (siehe Screenshot unten).
Wenn Sie 10000001 als Wert für PARTNER_ID aus dem Screenshot oben nehmen, sehen die vollständigen URLs zum Senden von API-Anfragen in der Sandbox und in der Produktion wie in den folgenden Beispielen aus.
Sandbox-Update
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox LÖSCHEN
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Produktionsupdate
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Produktion – LÖSCHEN
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Entitäten aktualisieren
Verwenden Sie zum Aktualisieren von Entitäten in Ihrem Inventar den Endpunkt update in einer HTTP-POST-Anfrage. Jede POST-Anfrage muss den Parameter 10000001 zusammen mit einer JSON-Nutzlast enthalten, die die zu aktualisierende Entität enthält.
Hinweis: Achten Sie darauf, dass Ihre täglichen Datenfeeds auch Änderungen enthalten, die über die Real-Time Updates API eingereicht wurden. Andernfalls sind Ihre Daten möglicherweise veraltet.
Nutzlast der Anfrage aktualisieren
Der Anfragetext ist ein JSON-Objekt mit einer Liste von Datensätzen. Jeder Datensatz entspricht einer Entität, die aktualisiert wird. Sie besteht aus dem Feld proto_record
und dem generation_timestamp
, das den Zeitpunkt der Entitätsaktualisierung angibt:
{ "records": [ { "proto_record":"ServiceData PROTO", "generation_timestamp":"UPDATE_TIMESTAMP" } ] }
ServiceData PROTO
: Die Proto- oder JSON-Übersetzung der Entität ServiceData, die Sie aktualisieren.UPDATE_TIMESTAMP
: Geben Sie unbedingt den Zeitstempel an, der angibt, wann die Entität in Ihren Back-End-Systemen generiert wurde. Wenn dieses Feld nicht enthalten ist, wird es auf den Zeitpunkt festgelegt, zu dem Google die Anfrage erhält. Beim Aktualisieren einer Entität über einebatchPush
-Anfrage wird das Feldgeneration_timestamp
für die Entitätsversionsverwaltung verwendet. Das erwartete Format von Zeitwerten finden Sie im relationalen Inventarschema.
- Der Nutzlasttext darf nicht größer als 5 MB sein.
- Entfernen Sie Leerzeichen, um die Größe zu verringern.
- Eine
batchPush
-Anfrage kann bis zu 1.000 Aktualisierungen enthalten.
Beispiele
Voraussichtliche Ankunftszeit aktualisieren
Angenommen, Sie müssen die voraussichtliche Ankunftszeit eines Lieferservice dringend von 30–60 Minuten auf 60–90 Minuten ändern. Die Aktualisierung muss den JSON-Code für die gesamte Dienstentität enthalten.
Stellen Sie sich eine Dienstentität vor, die so aussieht:
{ "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" } }
Ihre Echtzeit-Aktualisierung durch HTTP POST sieht so aus (Anfragetexte werden zur besseren Lesbarkeit gedruckt):
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" }] }
Mehrere Entitäten aktualisieren
Um mehrere Restaurantentitäten in einem einzigen API-Aufruf zu aktualisieren, fügen Sie mehrere Einträge in das Feld „proto_record“ des Anfragetexts ein.
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" }] }
Entitäten löschen
Verwenden Sie den Endpunkt DELETE in einer HTTP-POST-Anfrage, um Entitäten aus Ihrem Inventar zu löschen. Jede POST-Anfrage muss den PARTNER_ID-Parameter zusammen mit der JSON-Nutzlast enthalten, die die ID der zu löschenden Entität enthält.
Hinweis:Ihre täglichen Datenfeeds müssen auch Änderungen enthalten, die über die Real-Time Update API eingereicht wurden. Andernfalls werden Ihre Echtzeitänderungen durch die tägliche Batchaufnahme überschrieben.
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" }] }
Entitäten hinzufügen
Verwenden Sie keine Echtzeitaktualisierungen, um neue Entitäten hinzuzufügen, da dies zu Dateninkonsistenzen führen kann. Verwenden Sie stattdessen Batch-Feeds.
Validierung und API-Antwortcodes
Bei den API-Aufrufen für Echtzeit-Updates werden zwei Arten von Validierungen ausgeführt:
- Anfrageebene: Diese Validierungen prüfen, ob die Nutzlast dem Schema folgt und jedes
proto_record
die Felderid
undtype
enthält. Diese Prüfungen sind synchron und die Ergebnisse werden im API-Antworttext zurückgegeben. Ein Antwortcode 200 und ein leerer JSON-Text ({}
) bedeuten, dass diese Validierungen bestanden wurden und die Entitäten in dieser Anfrage zur Verarbeitung in die Warteschlange gestellt wurden. Ein Nicht-200-Antwortcode bedeutet, dass eine oder mehrere dieser Validierungen fehlgeschlagen sind und die gesamte Anfrage abgelehnt wird (einschließlich aller Entitäten in der Nutzlast). Wenn beispielsweise in einerproto_record
ein@type
fehlt, wird die folgende Fehlerantwort zurückgegeben:
{ "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." } ] }
- Entitätsebene: Jede Entität (proto_record) in der Nutzlast wird anhand des Schemas validiert. Probleme, die in dieser Validierungsphase aufgetreten sind, werden nicht in der API-Antwort aufgeführt. Sie werden nur im Dashboard für RTU-Berichte im Actions Center aufgeführt.
Hinweis:Der Antwortcode 200 bedeutet nicht, dass alle Entitäten erfolgreich aufgenommen wurden.
API-Kontingente
Echtzeit-API-Updates haben ein Kontingent von 1.500 Anfragen alle 60 Sekunden oder 25 Anfragen pro Sekunde im Durchschnitt. Wenn ein Kontingent überschritten wird, antwortet Google mit der folgenden Fehlermeldung:
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
Um dies zu vermeiden, wiederholen Sie den Aufruf in exponentiell größeren Intervallen, bis er erfolgreich ist. Wenn Sie das Kontingent regelmäßig ausgeschöpft haben, sollten Sie erwägen, mehr Entitäten in eine API-Anfrage aufzunehmen. Ein API-Aufruf kann bis zu 1.000 Entitäten umfassen.
Verarbeitungszeiten – Echtzeitaktualisierungen
Eine durch ein Echtzeitupdate aktualisierte Entität wird in 5 Minuten verarbeitet.