Echtzeitaktualisierung

Echtzeitaktualisierungen

RTUs sind in erster Linie für Updates vorgesehen, die Sie nicht vorhersehen können, z. B. Notfallschließungen 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 Batch-Feed-Aufnahme verwenden. Echtzeitaktualisierungen werden innerhalb von maximal fünf Minuten verarbeitet.

Google Cloud Platform einrichten

Richten Sie ein GCP-Projekt ein. Für den Zugriff auf die RTU API ist ein GCP-Projekt erforderlich.
- Gewähren Sie dem Konto food-support@google.com Bearbeitungszugriff.
- Teilen Sie Ihrem Google-Ansprechpartner 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 & Dienste > Bibliothek auf.
  - Suchen Sie nach „Google Maps Booking API“.
  - Suchen Sie nach der Sandbox-Instanz („Google Maps Booking API (Dev)“) und klicken Sie auf Aktivieren.
  - Suchen Sie nach der Produktionsinstanz („Google Maps Booking API“) und klicken Sie auf Aktivieren.
  - Erstellen Sie ein Dienstkonto mit der Rolle „Editor“ für Ihr GCP-Projekt. Weitere Informationen finden Sie unter Dienstkonto einrichten.
  - Achten Sie darauf, Batch-Feeds in die Umgebung hochzuladen, in der Sie an Echtzeitupdates arbeiten.
  - 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 unten aufgeführten Codebeispielen werden diese Bibliotheken verwendet. Andernfalls müssen Sie den Tokenaustausch manuell vornehmen, wie unter Zugriff auf Google-APIs über OAuth 2.0 beschrieben.

Dienstkonto einrichten

Sie benötigen ein Dienstkonto, um authentifizierte HTTPS-Anfragen an Google-APIs wie die API für Echtzeitupdates 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ü 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 Mehr > Schlüssel erstellen.
Wählen Sie JSON als Format aus und klicken Sie auf Erstellen.
Nachdem Ihr neues öffentliches/privates Schlüsselpaar generiert wurde, laden Sie es auf Ihren Computer herunter.

Mit der API arbeiten

Die Real-time Updates API unterstützt zwei Arten von Vorgängen: „Update“ und „Delete“. Das Hinzufügen neuer Elemente über die Echtzeit-Update-API wird nicht unterstützt. Echtzeitaktualisierungen können in Batches zusammengefasst werden, wenn Sie mehrere Aktualisierungen in eine einzelne API-Anfrage aufnehmen. Sie können bis zu 1.000 Aktualisierungen in einem einzelnen API-Aufruf zusammenfassen. Wir empfehlen, nach Möglichkeit einen triggerbasierten Ansatz zu verwenden, um Updates über RTU zu senden. Das bedeutet, dass bei einer Datenänderung in Ihrem System ein Echtzeit-Update an Google ausgelöst wird. Bei einem frequenzbasierten Ansatz wird Ihr System alle X Minuten auf Änderungen gescannt.

Die API für Echtzeitaktualisierungen funktioniert sowohl in der Sandbox- als auch in der Produktionsumgebung. Die Sandbox-Umgebung wird zum Testen der API-Anfragen und die Produktionsumgebung zum Aktualisieren der Inhalte verwendet, die für Nutzer von „Bestellen – Ende-zu-Ende“ sichtbar sind.

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

Endpunkte

Die API für Echtzeitaktualisierungen bietet zwei Endpunkte für die Verarbeitung eingehender Anfragen für Bestandsaktualisierungen:

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

Den Parameter PARTNER_ID finden Sie im Actions Center auf der Seite Konto und Nutzer, wie im Screenshot unten dargestellt.

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

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

Update zur Produktion

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 den update-Endpunkt in einer HTTP POST-Anfrage, um Einheiten in Ihrem Inventar zu aktualisieren. Jede POST-Anfrage muss den Parameter 10000001 sowie eine JSON-Nutzlast mit der zu aktualisierenden Einheit enthalten.

Hinweis:Ihre täglichen Datenfeeds müssen auch alle Änderungen enthalten, die über die API für Echtzeit-Updates 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 aktualisierten Entität. Sie besteht aus dem Feld proto_record und dem Feld generation_timestamp, das den Zeitpunkt der Aktualisierung der Entität 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: Achten Sie darauf, den Zeitstempel der Generierung der Einheit in Ihren Backend-Systemen anzugeben. Wenn dieses Feld nicht angegeben ist, wird es auf den Zeitpunkt festgelegt, zu dem Google die Anfrage erhält. Wenn Sie eine Entität über eine batchPush-Anfrage aktualisieren, wird das Feld generation_timestamp für die Versionsverwaltung der Entität verwendet. Das erwartete Format von Zeitwerten finden Sie im relationalen Inventarschema.

Der Nutzlast-Body darf nicht größer als 5 MB sein.
Entfernen Sie Leerzeichen, um die Größe zu reduzieren.
Eine batchPush-Anfrage kann bis zu 1.000 Aktualisierungen enthalten.

Beispiele

Erweiterte Textanzeige aktualisieren

Angenommen, Sie müssen die voraussichtliche Ankunftszeit eines Lieferdienstes dringend von 30–60 Minuten auf 60–90 Minuten aktualisieren. Ihr Update muss das JSON für die gesamte Service-Entität enthalten.

Angenommen, Sie haben 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"
	}
}

Ihr Echtzeit-Update per HTTP POST sieht so aus (Anfragetexte sind 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 mehrere Datensätze 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 DELETE-Endpunkt in einer HTTP POST-Anfrage, um Entitäten aus Ihrem Inventar zu löschen. Jede POST-Anfrage muss den Parameter PARTNER_ID sowie die JSON-Nutzlast mit der Kennung der zu löschenden Einheit enthalten.

Hinweis:Ihre täglichen Datenfeeds müssen auch alle Änderungen enthalten, die über die Echtzeit-Update-API eingereicht wurden. Andernfalls werden Ihre Echtzeitänderungen durch die tägliche Batch-Aufnahme ü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 Echtzeit-Updates, um neue Elemente hinzuzufügen, da dies zu Dateninkonsistenzen führen kann. Verwenden Sie stattdessen Batch-Feeds.

Validierung und API-Antwortcodes

Es gibt zwei Arten von Validierungen, die für die API-Aufrufe für Echtzeitaktualisierungen durchgeführt werden:

Anfrageebene: Bei diesen Validierungen wird geprüft, ob die Nutzlast dem Schema entspricht und ob jedes proto_record die Felder id und type enthält. Diese Prüfungen sind synchron und die Ergebnisse werden im API-Antworttext zurückgegeben. Ein Antwortcode 200 und ein leerer JSON-Textkörper {} bedeuten, dass diese Validierungen bestanden wurden 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 Validierungen fehlgeschlagen sind und die gesamte Anfrage (einschließlich aller Entitäten in der Nutzlast) abgelehnt wird. Wenn beispielsweise in einem proto_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 Phase der Validierung auftreten, werden nicht in der API-Antwort gemeldet. Sie werden nur im Dashboard Berichte zu RTU im Actions Center erfasst.

Hinweis:Ein Antwortcode 200 bedeutet nicht, dass alle Elemente erfolgreich aufgenommen wurden.

API-Kontingente

API-Aktualisierungen in Echtzeit ist ein Kontingent von 1.500 Anfragen pro 60 Sekunden zugewiesen. Das entspricht durchschnittlich 25 Anfragen pro Sekunde. 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 Sie das Kontingent regelmäßig ausschöpfen, sollten Sie mehr Einheiten in eine API-Anfrage aufnehmen. Sie können bis zu 1.000 Elemente in einen API-Aufruf einfügen.

Verarbeitungszeiten für Echtzeitupdates

Eine Entität, die über ein Echtzeitupdate aktualisiert wird, wird innerhalb von 5 Minuten verarbeitet.

Zurück

Conversion-Tracking

Echtzeitaktualisierung Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.