Diese Seite wurde von der Cloud Translation API übersetzt.

Echtzeitaktualisierung

Echtzeitaktualisierungen

Echtzeitaktualisierungen sind in erster Linie für Aktualisierungen gedacht, die nicht vorhersehbar sind, z. B. Notsperrungen oder Metadaten, die sich regelmäßig ändern (z. B. geschätzte Ankunftszeiten). Wenn Ihre Änderung nicht sofort berücksichtigt werden muss, können Sie stattdessen die Batchfeedaufnahme verwenden. Echtzeitaktualisierungen werden innerhalb von maximal fünf Minuten verarbeitet.

Google Cloud Platform einrichten

Ein GCP-Projekt einrichten. Für den Zugriff auf die RTU API ist ein GCP-Projekt erforderlich.
- Bearbeiterzugriff gewähren food-support@google.com
- Teilen Sie Ihrem Google-POC die GCP-Projektnummer mit.Ihr GCP-Projekt muss mit Ihrem Actions Center-Konto verknüpft sein, damit Echtzeitaktualisierungen funktionieren.
- Maps Booking API aktivieren:
  - Rufen Sie in der GCP APIs und Dienste > Bibliothek auf.
  - Suchen Sie nach „Google Maps Booking API“.
  - 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.
  - Erstellen Sie ein Dienstkonto mit der Rolle „Bearbeiter“ für Ihr GCP-Projekt. Weitere Informationen finden Sie unter Einrichtung eines Dienstkontos.
  - Laden Sie Batchfeeds in die Umgebung hoch, in der Sie Echtzeitaktualisierungen vornehmen.
  - Für die API-Authentifizierung empfehlen wir, die Google-Clientbibliothek in der Sprache Ihrer Wahl zu installieren. Verwenden Sie „https://www.googleapis.com/auth/mapsbooking“ als OAuth-Bereich. In den folgenden Codebeispielen werden diese Bibliotheken verwendet. Andernfalls müssen Sie den Token-Austausch manuell vornehmen, wie im Hilfeartikel Über OAuth 2.0 auf Google APIs zugreifen beschrieben.

Dienstkonto einrichten

Sie benötigen ein Dienstkonto, um authentifizierte HTTPS-Anfragen an Google APIs zu senden, z. B. an die Realtime Updates API.

So richten Sie ein Dienstkonto ein:

Rufen Sie die Google Cloud Platform Console auf.
Ihrem Konto im Actions Center ist auch ein Google Cloud-Projekt zugewiesen. Wählen Sie dieses Projekt aus, falls es noch nicht ausgewählt ist.
Klicken Sie im Menü links 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 Option Projekt > Bearbeiter aus.
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 für das gerade erstellte Dienstkonto auf das Dreipunkt-Menü > Schlüssel erstellen.
Wählen Sie als Format JSON aus und klicken Sie auf Erstellen.
Laden Sie das neue öffentliche/private Schlüsselpaar auf Ihren Computer herunter.

Mit der API arbeiten

Die API für Echtzeitaktualisierungen unterstützt zwei Arten von Vorgängen: Aktualisieren und Löschen. Das Hinzufügen neuer Entitäten über die Realtime Update API wird nicht unterstützt. Echtzeitaktualisierungen können in Batches zusammengefasst werden, wenn Sie mehrere Aktualisierungen in einer einzigen API-Anfrage angeben. Sie können bis zu 1.000 Aktualisierungen in einem einzigen API-Aufruf ausführen. Wir empfehlen, nach Möglichkeit einen triggerbasierten Ansatz zu verwenden, um Aktualisierungen per RTU zu senden (d.h. bei einer Datenänderung in Ihrem System eine Echtzeitaktualisierung an Google auslösen), anstatt einen frequenzbasierten Ansatz (d.h. alle X Minuten Ihr System auf Änderungen prüfen).

Die API für Echtzeitaktualisierungen funktioniert sowohl in der Sandbox- als auch in der Produktionsumgebung. In der Sandbox-Umgebung werden die API-Anfragen getestet und in der Produktionsumgebung werden die Inhalte aktualisiert, die für End-to-End-Nutzer der Bestellfunktion sichtbar sind.

Sandbox – partnerdev-mapsbooking.googleapis.com
Produktion – mapsbooking.googleapis.com

Endpunkte

Die API für Echtzeitaktualisierungen stellt zwei Endpunkte bereit, um eingehende Anfragen für Bestandsaktualisierungen zu verarbeiten:

AKTUALISIERUNG – /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
LÖSCHEN – /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

Der Parameter PARTNER_ID befindet sich im Actions Center auf der Seite Konto und Nutzer (siehe Screenshot unten).

Wenn wir 10000001 als Wert für PARTNER_ID aus dem Screenshot oben verwenden, sehen die vollständigen URLs zum Senden von API-Anfragen in der Sandbox und in der Produktion so aus wie in den folgenden Beispielen.

Sandbox-Update

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

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

Wenn du Entitäten in deinem Inventar aktualisieren möchtest, verwende den Endpunkt update in einer HTTP POST-Anfrage. Jede POST-Anfrage muss den Parameter „10000001“ sowie eine JSON-Nutzlast mit dem zu aktualisierenden Objekt enthalten.

Hinweis:Ihre täglichen Datenfeeds müssen auch alle Änderungen enthalten, die über die Realtime Updates API eingereicht wurden. Andernfalls sind Ihre Daten möglicherweise veraltet.

Nutzlast der Aktualisierungsanfrage

Der Anfragetext ist ein JSON-Objekt mit einer Liste von Einträgen. Jeder Datensatz entspricht einer Entität, die aktualisiert wird. Sie besteht aus dem Feld proto_record und dem generation_timestamp, das die Uhrzeit der Entitätsaktualisierung angibt:

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

ServiceData PROTO: Die Proto- oder JSON-Übersetzung der ServiceData-Entität, die Sie aktualisieren.
UPDATE_TIMESTAMP: Geben Sie in Ihren Backend-Systemen den Zeitstempel an, zu dem die Entität generiert wurde. Wenn dieses Feld nicht enthalten ist, wird es auf die Uhrzeit festgelegt, zu der Google die Anfrage erhält. Wenn eine Entität über eine batchPush-Anfrage aktualisiert wird, wird das Feld generation_timestamp für die Entitätsversionierung verwendet. Informationen zum erwarteten Format von Zeitwerten im relationalen Inventarschema

Der Payload-Body darf maximal 5 MB groß sein.
Entfernen Sie Leerzeichen, um die Größe zu reduzieren.
Eine batchPush-Anfrage kann bis zu 1.000 Aktualisierungen enthalten.

Beispiele

Geschätzte Ankunftszeit aktualisieren

Angenommen, Sie müssen dringend die geschätzte Ankunftszeit eines Lieferservice von 30–60 auf 60–90 Minuten aktualisieren. Ihre Aktualisierung muss das JSON für die gesamte Dienstentität enthalten.

Betrachten Sie eine Dienstentität, 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"
	}
}

Die Echtzeitaktualisierung per HTTP POST sieht so aus (Anfragekörper zur besseren Lesbarkeit formatiert):

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

Wenn Sie mehrere Restaurantentitäten in einem einzigen API-Aufruf aktualisieren möchten, fügen Sie dem Feld „proto_record“ im Anfragetext mehrere Einträge hinzu.

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

Wenn Sie Entitäten aus Ihrem Inventar löschen möchten, verwenden Sie den Endpunkt DELETE in einer HTTP-POST-Anfrage. Jede POST-Anfrage muss den Parameter „PARTNER_ID“ sowie die JSON-Nutzlast mit der Kennung der Entität enthalten, die Sie löschen möchten.

Hinweis:Ihre täglichen Datenfeeds müssen auch alle Änderungen enthalten, die über die Echtzeit-Aktualisierungs-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 Batchfeeds.

Validierungs- und API-Antwortcodes

Es gibt zwei Arten von Validierungen, die bei den API-Aufrufen für Echtzeitaktualisierungen ausgeführt werden:

Anfrageebene: Bei dieser Validierung wird geprüft, ob die Nutzlast dem Schema entspricht und jede proto_record die Felder id und type enthält. Diese Prüfungen sind synchron und die Ergebnisse werden im API-Antwortkörper zurückgegeben. Ein Antwortcode 200 und ein leerer JSON-Textkörper {} bedeuten, dass diese Prüfungen bestanden haben und die Entitäten in dieser Anfrage zur Verarbeitung in die Warteschlange gestellt wurden. Ein Antwortcode, der nicht 200 ist, bedeutet, dass eine oder mehrere dieser Prüfungen fehlgeschlagen sind und die gesamte Anfrage abgelehnt wird (einschließlich aller Entitäten in der Nutzlast). Wenn bei einer proto_record beispielsweise eine @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 mit dem Schema abgeglichen. Probleme, die in dieser Validierungsphase auftreten, werden nicht in der API-Antwort gemeldet. Sie werden nur im Dashboard RTU-Berichte im Info-Center erfasst.

Hinweis:Ein Antwortcode 200 bedeutet nicht, dass alle Entitäten erfolgreich aufgenommen wurden.

API-Kontingente

API-Aktualisierungen in Echtzeit haben ein Kontingent von 1.500 Anfragen pro 60 Sekunden, was durchschnittlich 25 Anfragen pro Sekunde entspricht. Wird das Kontingent überschritten, siehst du folgenden Fehlermeldung:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Wiederhole den Aufruf in diesem Fall in exponentiell größeren Abständen, bis er erfolgreich ist. Wenn du das Kontingent regelmäßig ausschöpfst, solltest du mehr Entitäten in eine API-Anfrage aufnehmen. Sie können bis zu 1.000 Entitäten in einem API-Aufruf angeben.