プレイスアクションリンク

Listings API を通じて、拠点の Google アクションボタン（注文、配達、テイクアウト、予約、来店予約）を管理します。

プレイスアクションリンクは、Google がビジネスのプロフィールに表示する オンラインで注文、配達を依頼、席を予約、来店予約などのアクションボタンです。Listings API はこれらを拠点の一部として管理するため、すでに使用しているものと同じ作成および更新エンドポイントで設定でき、拠点を取得するすべてのエンドポイントで読み取ることができます。

`placeActionLinks` フィールド

作成と更新のどちらでも、input に placeActionLinks 配列を指定できます。各要素は次のとおりです。

フィールド	型	必須	説明
`placeActionType`	enum	はい	以下の有効なタイプのいずれかです。
`uri`	string	はい	リンク先の URL です。
`isPreferred`	boolean	いいえ	このリンクを、そのタイプの優先リンクとして指定します。タイプごとに指定できる優先リンクは最大 1 つです。
`action`	string	いいえ	`add`（デフォルト）または `delete` です。更新時にのみ使用します。
`name`	string	いいえ	リンクの識別子で、リンクが Google に同期されると、取得エンドポイントから返されます。書き込み時は省略可能ですが、利用できる場合は指定することで、保存済みの特定のリンクを最も正確に対象にできます。

placeActionType の有効な値：

Code

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

リンクの照合方法（編集・削除時）：name がある場合はそれを使用し、ない場合は placeActionType + uri を使用します。最も正確に照合するには、取得時に得た name があれば指定してください。新しく追加され、まだ Google に同期されていないリンクには name がないため、placeActionType + uri で照合します。

アクション

書き込みモデルは置換ではなく、append/upsert（追加または更新）です。更新時に影響を受けるのは指定したリンクのみで、指定しなかったリンクは変更されません。

アクション	目的	照合
`add`	新しいリンクを追加するか、保存済みリンクの `uri` / `isPreferred` をその場で更新します。	`name` がある場合はそれを使用し、ない場合は `placeActionType` + `uri` を使用します
`delete`	保存済みリンクを削除し、Google からの削除をキューに追加します。	`name` がある場合はそれを使用し、ない場合は `placeActionType` + `uri` を使用します

リンクの URL を変更するには、同じリクエスト内で古いリンクを削除し、新しいリンクを追加します（リンクの URL を変更するを参照）。

推奨フロー

拠点のプレイスアクションリンクを登録し、Google との同期を維持する方法は 2 つあります。

フロー 1：まず Google で作成してから接続する

事業者が Google Business Profileでプレイスアクションリンクを直接設定します。
その Google Business Profileの拠点を Listings API に接続します。
接続時に、Listings API が Google で公開中のリンクを取得し、その拠点の管理対象に取り込みます。API を通じて再入力する必要はありません。

フロー 2：まず Listings API で作成してから接続する

Listings API でプレイスアクションリンクを含めて拠点を作成するか（拠点を作成する）、後からリンクを追加します（拠点を更新する）。
Google Business Profileへの接続時に、Listings API が公開中のリンクを取得し、管理対象のリンクと統合します。
- 問題なく照合できたリンクは、管理対象に加わります。
- Google にあるリンクのうち、自動で統合できないもの（または単にまだ管理対象に含まれていないもの）は、確認できるように discoveredPlaceActionLinks に表示されます。
Google への送信のたびに、Listings API は公開中のリンクを再確認します。Google Business Profile内で直接見つかった、Listings API が管理していない新しいリンクはすべて discoveredPlaceActionLinks に追加されます。

検出されたリンクとは、ビジネスの Google プロフィールに存在するものの、Listings API では管理されていないプレイスアクションリンクです。これらは上記のフロー（接続時に見つかった追加のリンク、または後の送信時に見つかった新しいリンク）によって取り込まれ、すべての読み取りエンドポイント（一覧取得、ID による取得、店舗コードによる取得、検索）で、管理対象のリンクとは別に、discoveredPlaceActionLinks（placeActionLinks と同じ構造）に含めて返されます。

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    }  ]}

検出されたリンクを管理対象にする

検出されたリンクの管理を開始するには、action: "add" を指定して、そのリンクを拠点の更新に送信します。これは、任意のリンク（placeActionType + uri で識別）を追加する場合と同じ呼び出しです。他のリンクは変更されません。

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" }      ]    }  }'

この操作後、リンクは placeActionLinks に表示され、discoveredPlaceActionLinks から削除されます。管理対象にしない検出済みリンクは、そのまま一覧に残ります（後で Google から消えた場合は、自動的に一覧からも削除されます）。対応は不要です。

例

更新のたびに、その拠点の最新の完全な placeActionLinks のセット（変更を反映したもの）が返されます。書き込み直後は、リンクの name と submissionStatus は null であり、リンクが Google に同期されると値が設定されます。

リンクを追加する

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" }      ]    }  }'

リンクの URL を変更する

URL を変更するには、同じリクエスト内で古いリンクを削除し、新しいリンクを追加します。古いリンクが Google に同期済みの場合は、最も正確に照合できるよう、delete にそのリンクの name を含めます。それ以外の場合は、placeActionType + uri が使用されます。

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" }      ]    }  }'

isPreferred のみを変更する場合（URL は同じ）は、action: "add" と新しい値を指定してリンクを再送信します。

リンクを削除する

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" }      ]    }  }'

リンクを含む拠点を作成する

作成時はすべてのリンクが新規のため、action のデフォルト値は add です。

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" }      ]    }  }'

注意事項

タイプごとに設定できる優先リンクは最大 1 つです。
リンクの submissionStatus は Google への直近の同期結果（success、failed など）を反映し、人が読める形式の submissionMessage が付きます。
Google は、確認済みの拠点にのみプレイスアクションリンクを適用します。