RTU は主に、緊急閉鎖や定期的に変更されるメタデータ（到着予定時刻など）など、予測できない更新を対象としています。変更をすぐに反映する必要がない場合は、代わりにバッチフィードの取り込みを使用できます。リアルタイム更新は 5 分以内に処理されます。
Google Cloud Platform の設定
- GCP プロジェクトを設定する。RTU API にアクセスするには GCP プロジェクトが必要です。
- 編集者にアクセス権を付与する food-support@google.com
- Google POC に GCP プロジェクト番号を伝えます。リアルタイム更新を機能させるには、GCP プロジェクトがアクション センター アカウントに関連付けられている必要があります。
- Maps Booking API を有効にします:
- GCP で [API とサービス >Library にあります。
- 「Google Maps Booking API」を検索します。
<ph type="x-smartling-placeholder">
</ph> 
- サンドボックス インスタンス（「Google Maps Booking API（Dev）」）を見つけて、[有効にする] をクリックします。
- 本番環境インスタンス（「Google Maps Booking API」）を見つけて、[有効にする] をクリックします。
<ph type="x-smartling-placeholder">
</ph> 
- GCP プロジェクトに対して、編集者のロールを持つサービス アカウントを作成します。詳しくは、サービス アカウントの設定をご覧ください。
- バッチフィードは、リアルタイム更新を行っている環境にアップロードしてください。
- API 認証については、選択した言語の Google クライアント ライブラリをインストールすることをおすすめします。OAuth スコープとして「https://www.googleapis.com/auth/mapsbooking」を使用します。以下のコードサンプルでは、これらのライブラリを使用しています。それ以外の場合は、OAuth 2.0 を使用した Google API へのアクセスで説明されているように、トークン交換を手動で処理する必要があります。
サービス アカウントのセットアップ
リアルタイム アップデート API など、Google API に対して認証済みの HTTPS リクエストを行うには、サービス アカウントが必要です。
サービス アカウントを設定する手順は次のとおりです。
- Google Cloud Platform コンソールにアクセスします。
- Actions Center のアカウントにも、Google Cloud プロジェクトが関連付けられています。まだ選択していない場合は、そのプロジェクトを選択します。
- 左側のメニューで [サービス アカウント] をクリックします。
- [サービス アカウントを作成] をクリックします。
- サービス アカウントの名前を入力して [作成] をクリックします。
- [ロールを選択] で、[プロジェクト] >エディタ。
- [続行] をクリックします。
- 省略可: サービス アカウントへのアクセス権を付与するユーザーを追加して、[完了] をクリックします。
- [その他] >作成したサービス アカウントの鍵を作成します。
- 形式として [JSON] を選択し、[作成] をクリックします。
- 新しい公開鍵と秘密鍵のペアが生成されたら、パソコンにダウンロードします。
API の操作
Real-time updates API は、更新と削除の 2 種類のオペレーションをサポートしています。リアルタイム更新 API を使用した新しいエンティティの追加はサポートされていません。1 つの API リクエストに複数の更新を含めると、リアルタイム更新をバッチ処理できます。1 回の API 呼び出しで最大 1,000 件の更新をバッチ処理できます。可能であれば、頻度ベースのアプローチ（X 分ごとにシステムをスキャンする）ではなく、RTU 経由で更新を送信する（つまり、システムでデータが変更されると、Google へのリアルタイムの更新をトリガーする）トリガーベースのアプローチを使用することをおすすめします。
リアルタイム更新 API は、サンドボックス環境と本番環境の両方で動作します。サンドボックス環境は、API リクエストをテストし、本番環境では、エンド ツー エンドの注文ユーザーに表示されるコンテンツを更新するために使用されます。
- サンドボックス -
partnerdev-mapsbooking.googleapis.com - 本番環境 -
mapsbooking.googleapis.com
エンドポイント
リアルタイム更新 API は、インベントリ更新の受信リクエストを処理するために、次の 2 つのエンドポイントを公開します。
- 更新 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - 削除 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
パラメータ PARTNER_ID は、以下のスクリーンショットに示すように、アクション センターの [Account and users] ページで確認できます。
上のスクリーンショットの PARTNER_ID の値として 10000001 を例にとると、サンドボックスと本番環境で API リクエストを送信するための完全な URL は次のようになります。
サンドボックスの更新
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
サンドボックスの削除
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
製品版のアップデート
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
本番環境 DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
エンティティの更新
インベントリ内のエンティティを更新するには、HTTP POST リクエストで update エンドポイントを使用します。各 POST リクエストには、10000001 パラメータと、更新するエンティティを含む JSON ペイロードを含める必要があります。
注: 日次データフィードには、Realtime Updates API を使用して送信された変更も必ず含めてください。そうしないと、データが古くなっているか古くなっている可能性があります。
リクエスト ペイロードの更新
リクエストの本文は、レコードのリストを含む JSON オブジェクトです。各レコードは更新するエンティティに対応しています。proto_record フィールドと、エンティティの更新時刻を示す generation_timestamp で構成されます。
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: 更新する ServiceData エンティティの proto または JSON 変換。UPDATE_TIMESTAMP: バックエンド システムでエンティティが生成されたときのタイムスタンプを必ず含めてください。このフィールドが指定されていない場合、Google がリクエストを受信した時刻に設定されます。batchPushリクエストでエンティティを更新する場合は、エンティティのバージョニングにgeneration_timestampフィールドが使用されます。リレーショナル インベントリ スキーマで想定される時刻値の形式を確認してください。
- ペイロードの本文のサイズは 5 MB を超えないようにしてください。
- 空白文字を削除してサイズを小さくしてください。
batchPushリクエストで最大 1,000 件の更新が可能です。
例
到着予定時刻を更新する
配達サービスの到着予定時刻を 30 ～ 60 分から 60 ～ 90 分に緊急に更新する必要があるとします。更新には、Service エンティティ全体の JSON が含まれている必要があります。
次のようなサービス エンティティについて考えてみましょう。
{ "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" } }
HTTP POST によるリアルタイム更新は次のようになります（読みやすくするためにリクエスト本文は適切に出力されています）。
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" }] }
複数のエンティティを更新する
1 回の API 呼び出しで複数のレストラン エンティティを更新するには、リクエスト本文の proto_record フィールドに複数のレコードを含めます。
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" }] }
エントリの削除
インベントリからエンティティを削除するには、HTTP POST リクエストで DELETE エンドポイントを使用します。各 POST リクエストには、PARTNER_ID パラメータと、削除するエンティティの ID を含む JSON ペイロードを含める必要があります。
注: 日次データフィードには、リアルタイム アップデート API で送信された変更も含まれていることを確認します。そうしないと、毎日のバッチ取り込みによってリアルタイムの変更が上書きされます。
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" }] }
エンティティの追加
データの不整合が生じる可能性があるため、新しいエンティティの追加にリアルタイム更新を使用しないでください。代わりに、バッチフィードを使用してください。
検証とAPI レスポンス コード
リアルタイム更新 API 呼び出しでは、次の 2 種類の検証が行われます。
- リクエスト レベル - この検証では、ペイロードがスキーマに従っていて、すべての
proto_recordにidフィールドとtypeフィールドが含まれていることを確認します。これらのチェックは同期的で、結果は API レスポンスの本文で返されます。レスポンス コード 200 と空の JSON 本文{}は、これらの検証に合格し、そのリクエスト内のエンティティが処理のキューに追加されたことを意味します。200 以外のレスポンス コードは、これらの検証の 1 つ以上が失敗し、リクエスト全体（ペイロード内のすべてのエンティティを含む）が拒否されたことを意味します。たとえば、proto_recordに@typeがない場合は、次のエラー レスポンスが返されます。
{ "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." } ] }
- エンティティ レベル: ペイロード内の各エンティティ（proto_record）がスキーマに対して検証されます。検証のこのフェーズで発生した問題は、API レスポンスでは報告されません。報告は、アクション センターの RTU レポート ダッシュボードでのみ表示されます。
注: レスポンス コード 200 は、すべてのエンティティが正常に取り込まれたわけではありません。
API 割り当て
リアルタイム API 更新の割り当ては、60 秒ごとに 1,500 件のリクエスト、つまり 1 秒あたり平均 25 件のリクエストです。割り当てを超過すると、Google から次のエラー メッセージが返されます。
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
これに対処するには、成功するまで指数関数的に長い間隔で呼び出しを再試行します。定期的に割り当てを使い切る場合は、1 つの API リクエストにエンティティを追加することをご検討ください。1 回の API 呼び出しに最大 1,000 個のエンティティを含めることができます。
処理時間のリアルタイム更新
リアルタイム アップデートで更新されたエンティティは 5 分で処理されます。