RTU は主に、緊急事態の閉鎖や、定期的に変更されるメタデータ（到着予定時刻など）など、予測できない更新に使用します。変更をすぐに反映する必要がない場合は、代わりにバッチ フィードの取り込みを使用できます。リアルタイム更新は 5 分以内に処理されます。
Google Cloud Platform の設定
- GCP プロジェクトを設定します。RTU API にアクセスするには GCP プロジェクトが必要です。
- 編集者に food-support@google.com へのアクセス権を付与する
- Google POC に GCP プロジェクト番号を伝えます。リアルタイムで更新するには、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 コンソールにアクセスします。
- アクション センターのアカウントにも、Google Cloud プロジェクトが関連付けられています。そのプロジェクトがまだ選択されていない場合は、選択します。
- 左側のメニューで [サービス アカウント] をクリックします。
- [サービス アカウントを作成] をクリックします。
- サービス アカウントの名前を入力し、[作成] をクリックします。
- [ロールを選択] で、[Project] > [編集者] を選択します。
- [続行] をクリックします。
- 省略可: ユーザーを追加してサービス アカウントへのアクセス権を付与し、[完了] をクリックします。
- 作成したサービス アカウントの [その他] > [キーを作成] をクリックします。
- 形式として [JSON] を選択し、[作成] をクリックします。
- 新しい公開鍵と秘密鍵のペアが生成されたら、パソコンにダウンロードします。
API の操作
Realtime Updates API は、更新と削除の 2 種類の操作をサポートしています。リアルタイム更新 API を使用した新しいエンティティの追加はサポートされていません。単一の 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 は、次のスクリーンショットに示すように、[アカウントとユーザー] ページのアクション センターにあります。
上のスクリーンショットの 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 リクエストには、10000001 パラメータと、更新するエンティティを含む JSON ペイロードを含める必要があります。
注: 日次データ フィードにも、リアルタイム更新 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 以下にする必要があります。
- 空白を削除してサイズを小さくします。
- 1 つの
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 分で処理されます。