RTU は、緊急閉鎖など予測できない更新や、定期的に変更されるメタデータ（到着予定時刻など）を主な対象としています。変更をすぐに反映する必要がない場合は、バッチ フィードの取り込みを使用できます。リアルタイム更新は 5 分以内に処理されます。
Google Cloud Platform の設定
- GCP プロジェクトを設定します。RTU API にアクセスするには、GCP プロジェクトが必要です。
- 編集者のアクセス権を food-support@google.com に付与します。
- GCP プロジェクト番号を Google の担当者に伝えます。リアルタイム更新を機能させるには、GCP プロジェクトをアクション センター アカウントに関連付ける必要があります。
- Maps Booking API を有効にします。
- GCP で、[API とサービス] > [ライブラリ] に移動します。
- 「Google Maps Booking API」を検索します。
- サンドボックス インスタンス（「Google Maps Booking API (Dev)」）を見つけて、[有効にする] をクリックします。
- 本番環境インスタンス（「Google Maps Booking API」）を見つけて、[有効にする] をクリックします。
- GCP プロジェクトに編集者ロールを持つサービス アカウントを作成します。詳細については、サービス アカウントの設定をご覧ください。
- バッチフィードは、リアルタイム更新の作業を行っている環境にアップロードしてください。
- API 認証には、選択した言語で Google クライアント ライブラリをインストールすることをおすすめします。OAuth スコープとして「https://www.googleapis.com/auth/mapsbooking」を使用します。以下のコードサンプルでは、これらのライブラリを使用しています。それ以外の場合は、OAuth 2.0 を使用して Google API にアクセスするで説明されているように、トークン交換を手動で処理する必要があります。
サービス アカウントを設定する
リアルタイム更新 API などの Google API に対して認証済みの HTTPS リクエストを行うには、サービス アカウントが必要です。
サービス アカウントを設定するには、次の操作を行います。
- Google Cloud Platform コンソールにアクセスします。
- アクション センターのアカウントにも、関連付けられた Google Cloud プロジェクトがあります。まだ選択されていない場合は、そのプロジェクトを選択します。
- 左側のメニューで [サービス アカウント] をクリックします。
- [サービス アカウントを作成] をクリックします。
- サービス アカウントの名前を入力し、[作成] をクリックします。
- [ロールを選択] で、[プロジェクト] > [編集者] を選択します。
- [続行] をクリックします。
- 省略可: ユーザーを追加してサービス アカウントへのアクセス権を付与し、[完了] をクリックします。
- 作成したサービス アカウントの [その他] > [キーを作成] をクリックします。
- 形式として [JSON] を選択し、[作成] をクリックします。
- 新しい公開鍵と秘密鍵のペアが生成されたら、パソコンにダウンロードします。
API の操作
リアルタイム更新 API は、更新と削除の 2 種類のオペレーションをサポートしています。リアルタイム更新 API を介して新しいエンティティを追加することはできません。1 つの API リクエストに複数の更新を含めると、リアルタイム更新をバッチ処理できます。1 回の API 呼び出しで最大 1,000 件の更新をバッチ処理できます。可能であれば、頻度ベースのアプローチ（X 分ごとにシステムで変更をスキャンする）ではなく、トリガーベースのアプローチ（システムでデータが変更されたら、Google にリアルタイムで更新をトリガーする）を使用して RTU 経由で更新を送信することをおすすめします。
リアルタイム更新 API は、サンドボックス環境と本番環境の両方で動作します。サンドボックス環境は API リクエストのテストに使用され、本番環境は Ordering エンドツーエンド ユーザーに表示されるコンテンツの更新に使用されます。
- サンドボックス -
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 は、下のスクリーンショットに示すように、アクション センターの [アカウントとユーザー] ページで確認できます。
上記のスクリーンショットの例のように、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
本番環境の削除
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
エンティティの更新
インベントリ内のエンティティを更新するには、HTTP POST リクエストで update エンドポイントを使用します。各 POST リクエストには、更新するエンティティを含む JSON ペイロードとともに 10000001 パラメータを含める必要があります。
注: リアルタイム更新 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 件の更新を含めることができます。
例
ETA を更新する
たとえば、配達サービスの到着予定時刻を 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 リクエストには、削除するエンティティの識別子を含む JSON ペイロードとともに、PARTNER_ID パラメータを含める必要があります。
注: リアルタイム更新 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 リクエストが割り当てられます。割り当てを超過すると、次のエラー メッセージが返されます。
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}この処理を行うには、成功するまで指数関数的に間隔を延ばして呼び出しを再試行します。割り当てを定期的に使い切っている場合は、1 つの API リクエストに含めるエンティティの数を増やすことを検討してください。1 回の API 呼び出しで最大 1,000 個のエンティティを含めることができます。
処理時間のリアルタイム更新
リアルタイム更新で更新されたエンティティは 5 分で処理されます。