RTU は主に、緊急の閉鎖や定期的に変更されるメタデータ（予定時刻など）など、予測できない更新を対象としています。変更をすぐに反映する必要がない場合は、代わりにバッチ フィードの取り込みを使用できます。リアルタイム更新は 5 分以内に処理されます。
Google Cloud Platform の設定
- GCP プロジェクトを設定します。RTU API にアクセスするには、GCP プロジェクトが必要です。
- 編集者権限を付与 food-support@google.com
- GCP プロジェクト番号を Google の担当者に伝えます。リアルタイム更新を機能させるには、GCP プロジェクトを Actions Center アカウントに関連付ける必要があります。
- 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 コンソールにアクセスします。
- Actions Center のアカウントにも Google Cloud プロジェクトが関連付けられています。まだ選択していない場合は、そのプロジェクトを選択します。
- 左側のメニューで [サービス アカウント] をクリックします。
- [サービス アカウントを作成] をクリックします。
- サービス アカウントの名前を入力し、[作成] をクリックします。
- [ロールを選択] で、[プロジェクト] > [編集者] を選択します。
- [続行] をクリックします。
- 省略可: サービス アカウントへのアクセス権を付与するユーザーを追加し、[完了] をクリックします。
- 作成したサービス アカウントのその他アイコン > キーを作成をクリックします。
- 形式として [JSON] を選択し、[作成] をクリックします。
- 新しい公開鍵と秘密鍵のペアが生成されたら、マシンにダウンロードします。
API の操作
Real-time updates API は、更新と削除の 2 種類のオペレーションをサポートしています。Real-time update API を介して新しいエンティティを追加することはできません。1 つの API リクエストに複数の更新を含めると、リアルタイム更新をバッチ処理できます。1 回の API 呼び出しで最大 1,000 件の更新をバッチ処理できます。可能であれば、頻度ベースのアプローチ（X 分ごとにシステムをスキャンして変更を検出する）ではなく、トリガーベースのアプローチ（システムでデータが変更されたときに Google へのリアルタイム更新をトリガーする）を使用して RTU 経由で更新を送信することをおすすめします。
Real-time updates API は、サンドボックス環境と本番環境の両方で動作します。サンドボックス環境は API リクエストをテストするために使用され、本番環境は注文エンドツーエンド ユーザーに表示されるコンテンツを更新するために使用されます。
- サンドボックス -
partnerdev-mapsbooking.googleapis.com - 本番環境 -
mapsbooking.googleapis.com
エンドポイント
リアルタイム更新 API は、在庫更新の受信リクエストを処理するために 2 つのエンドポイントを公開します。
- 更新 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - DELETE -
/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 エンティティのプロトまたは 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 リクエストには、削除するエンティティの ID を含む JSON ペイロードとともに PARTNER_ID パラメータを含める必要があります。
注: リアルタイム更新 API を通じて送信された変更も、日次データフィードに含めるようにしてください。そうしないと、1 日のバッチ取り込みによってリアルタイムの変更が上書きされます。
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 分で処理されます。