Aktionslinks für Standorte

Verwalten Sie die Google-Aktionsschaltflächen eines Standorts (Bestellung, Lieferung, Abholung, Tischreservierung, Terminbuchung) über die Listings API.

Aktionslinks für Standorte sind die Aktionsschaltflächen, die Google im Profil eines Unternehmens anzeigt: Order online (Online bestellen), Get delivery (Liefern lassen), Reserve a table (Tisch reservieren), Book an appointment (Termin buchen) und so weiter. Die Listings API verwaltet sie als Teil eines Standorts, sodass Sie sie über dieselben Endpunkte zum Erstellen und Aktualisieren festlegen, die Sie bereits verwenden, und über jeden Endpunkt zum Lesen von Standorten wieder abrufen können.

Das Feld `placeActionLinks`

Sowohl beim Erstellen als auch beim Aktualisieren wird ein placeActionLinks-Array in input akzeptiert. Jedes Element:

Feld	Typ	Erforderlich	Beschreibung
`placeActionType`	enum	ja	Einer der unten aufgeführten gültigen Typen.
`uri`	string	ja	Ziel-URL.
`isPreferred`	boolean	nein	Kennzeichnet diesen Link als bevorzugten Link für seinen Typ. Höchstens ein bevorzugter Link pro Typ.
`action`	string	nein	`add` (der Standardwert) oder `delete`. Wird nur beim Aktualisieren verwendet.
`name`	string	nein	Die Kennung des Links, die von den Leseendpunkten zurückgegeben wird, sobald der Link mit Google synchronisiert wurde. Beim Schreiben optional; geben Sie sie an, wenn sie verfügbar ist, um einen bestimmten gespeicherten Link möglichst präzise anzusprechen.

Gültige Werte für placeActionType:

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

So wird ein Link zugeordnet (zum Bearbeiten / Löschen): anhand von name, falls vorhanden, andernfalls anhand von placeActionType + uri. Geben Sie name an, wenn Ihnen dieser Wert (aus einem Lesevorgang) vorliegt, um eine möglichst präzise Zuordnung zu erzielen. Ein neu hinzugefügter Link, der noch nicht mit Google synchronisiert wurde, hat keine name und wird daher anhand von placeActionType + uri zugeordnet.

Aktionen

Das Schreibmodell ist append/upsert, kein Ersetzen. Beim Aktualisieren sind nur die Links betroffen, auf die Sie verweisen; Links, die Sie nicht angeben, bleiben unverändert.

Aktion	Zweck	Zuordnung
`add`	Einen neuen Link hinzufügen oder `uri` / `isPreferred` eines gespeicherten Links direkt aktualisieren.	`name`, falls vorhanden, sonst `placeActionType` + `uri`
`delete`	Einen gespeicherten Link entfernen und seine Entfernung aus Google in die Warteschlange stellen.	`name`, falls vorhanden, sonst `placeActionType` + `uri`

Um die URL eines Links zu ändern, entfernen Sie den alten Link und fügen Sie den neuen in derselben Anfrage hinzu (siehe URL eines Links ändern).

Empfohlene Abläufe

Es gibt zwei unterstützte Möglichkeiten, die Aktionslinks eines Standorts zu erfassen und mit Google synchron zu halten.

Ablauf 1: Zuerst in Google erstellen, dann verbinden

Der Händler richtet die Aktionslinks für den Standort direkt in seinem Google Business Profile ein.
Dieser Google Business Profile-Standort wird mit der Listings API verbunden.
Beim Verbinden ruft die Listings API die aktuell bei Google vorhandenen Links ab und übernimmt sie in den verwalteten Linkbestand des Standorts. Sie müssen sie nicht erneut über die API eingeben.

Ablauf 2: Zuerst in der Listings API erstellen, dann verbinden

Erstellen Sie den Standort in der Listings API mit seinen Aktionslinks (Standort erstellen), oder fügen Sie sie später hinzu (Standort aktualisieren).
Beim Verbinden mit Google Business Profile ruft die Listings API die aktuell vorhandenen Links ab und führt sie mit dem verwalteten Linkbestand zusammen:
- Links, die sich eindeutig zuordnen lassen, werden in den verwalteten Linkbestand aufgenommen;
- alle bei Google vorhandenen Links, die nicht automatisch zusammengeführt werden können (oder einfach noch nicht im verwalteten Linkbestand enthalten sind), werden Ihnen unter discoveredPlaceActionLinks zur Prüfung angezeigt.
Bei jeder Übermittlung an Google prüft die Listings API die aktuell vorhandenen Links erneut. Jeder neue Link, der direkt in Google Business Profile gefunden wird und den die Listings API nicht verwaltet, wird zu discoveredPlaceActionLinks hinzugefügt.

Gefundene Links

Gefundene Links sind Aktionslinks für Standorte, die im Google-Profil des Unternehmens vorhanden sind, aber nicht in Listings API verwaltet werden. Sie werden durch die oben beschriebenen Abläufe abgerufen (zusätzliche Links, die beim Verbinden gefunden werden, oder neue Links, die bei einer späteren Übermittlung gefunden werden) und von jedem Lese-Endpunkt getrennt von Ihren verwalteten Links unter discoveredPlaceActionLinks (mit derselben Struktur wie placeActionLinks) zurückgegeben: auflisten, nach IDs, nach Filialcodes und suchen.

JSON

{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

Einen gefundenen Link übernehmen

Um einen gefundenen Link zu verwalten, senden Sie ihn mit action: "add" an Standort aktualisieren – derselbe Aufruf wie beim Hinzufügen eines beliebigen Links (identifiziert durch placeActionType + uri). Andere Links bleiben unverändert.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

Danach erscheint der Link unter placeActionLinks und wird aus discoveredPlaceActionLinks entfernt. Ein gefundener Link, den Sie nicht übernehmen, bleibt einfach aufgeführt (und wird automatisch entfernt, wenn er später bei Google verschwindet); es ist keine Aktion erforderlich.

Beispiele

Jede Aktualisierung gibt die vollständige, aktuelle Menge von placeActionLinks des Standorts zurück (unter Berücksichtigung der Änderung). Direkt nach einem Schreibvorgang sind name und submissionStatus eines Links auf null gesetzt; sie werden befüllt, sobald der Link mit Google synchronisiert wird.

Einen Link hinzufügen

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Die URL eines Links ändern

Bei einer URL-Änderung wird der alte Link entfernt und der neue in derselben Anfrage hinzugefügt. Wenn der alte Link bereits mit Google synchronisiert wurde, geben Sie seinen name bei delete an, um eine möglichst genaue Zuordnung zu ermöglichen; andernfalls wird placeActionType + uri verwendet.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

Um nur isPreferred zu ändern (bei gleichbleibender URL), senden Sie den Link erneut mit action: "add" und dem neuen Wert.

Einen Link entfernen

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

Einen Standort mit Links erstellen

Beim Erstellen ist jeder Link neu, daher ist action standardmäßig auf add gesetzt.

Shell

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

Hinweise

Höchstens ein bevorzugter Link pro Typ.
submissionStatus eines Links spiegelt die letzte Synchronisierung mit Google wider (success, failed usw.), ergänzt durch einen für Menschen lesbaren Wert für submissionMessage.
Google wendet Aktionslinks für Standorte nur auf verifizierte Standorte an.