このセクションでは、時間的制約のあるフィードの更新を Google に送信する方法について説明します。Incremental Updates API を使用すると、ほぼリアルタイムでフィード内のエンティティの更新と削除を行うことができます。
この機能は主に、緊急閉鎖など、予測できない更新を目的としています。原則として、増分アップデート API で送信する変更は、1 週間以内に公開する必要があります。変更を直ちに反映する必要がない場合は、代わりにバッチ アップデートを使用できます。増分アップデートは 5 分以内に処理されます。
設定
増分アップデートを実装する手順は次のとおりです。
- プロジェクトを作成して設定するの手順に沿ってプロジェクトを作成します。
- サービス アカウントの設定で説明されている手順に沿って、サービス アカウントを作成します。サービス アカウントに「編集者」のロールを追加するには、プロジェクトの「オーナー」である必要があります。
- (省略可、ただし推奨)API の呼び出し時に OAuth 2.0 を簡単に使用できるように、任意の言語で Google クライアント ライブラリをインストールします。以下のコードサンプルでは、これらのライブラリが使用されています。それ以外の場合は、OAuth 2.0 を使用した Google API へのアクセスの説明に従ってトークン交換を手動で処理する必要があります。
エンドポイント
Google に更新を通知するには、Incremental Updates API への HTTP POST リクエストを作成し、更新と追加のペイロードを含めます。使用するインベントリ スキーマによって、リクエストを行うエンドポイントが決まります。
v2 広告枠
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push
v1 広告枠
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push
エンティティを削除するには、使用するインベントリ スキーマに対応する次のエンドポイントに HTTP DELETE リクエストを行います。
v2 広告枠
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
v1 広告枠
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
上記のリクエストで、次のように置き換えます。
- PROJECT_ID: プロジェクトの作成と設定で作成したプロジェクトに関連付けられた Google Cloud プロジェクト ID。
- TYPE(v2 在庫スキーマのみ): 更新するデータフィードのオブジェクトのエンティティ タイプ(
@type
プロパティ)。 - ENTITY_ID: ペイロードに含まれるエンティティの ID。エンティティ ID は URL エンコードしてください。
- DELETE_TIME(削除エンドポイントのみ): システムでエンティティが削除された時刻を示すオプション フィールド(デフォルトはリクエストを受信したとき)。時刻に将来の時刻は指定できません。増分呼び出しでエンティティを送信する場合、エンティティのバージョニングは、削除呼び出しの際に
delete_time
フィールドも使用します。この値をyyyy-mm-ddTHH:mm:ssZ
の形式で指定します。
たとえば、v2 インベントリ スキーマを使用する ID が「delivery-provider-id」のプロジェクトがあるとします。レストランのエンティティ タイプが「MenuSection」、エンティティ ID が「menuSection_122」のレストランに変更を加えるとします。データを更新するためのエンドポイントは次のとおりです。
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push
同じエンティティを削除するには、次の HTTP DELETE API 呼び出しを行います。
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
サンドボックス リクエスト
サンドボックス リクエストの場合は、上記のエンドポイントのガイダンスに従いますが、/v2/apps/
ではなく /v2/sandbox/apps/
にリクエストを送信します。たとえば、v2 インベントリ スキーマのサンドボックス削除リクエストは、次のように構成されています。
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
更新と追加
毎日のバッチフィードには、この API で送信された変更も含める必要があります。そうしないと、バッチ アップデートで増分変更が上書きされます。
ペイロード
各 POST リクエストには、リクエスト パラメータと、インベントリ スキーマにリストされている任意のエンティティ タイプの構造化データを含む JSON ペイロードを含める必要があります。
JSON はバッチフィードの場合と同じように表示されますが、次の点が異なります。
- ペイロードの本文のサイズは 5 MB を超えないようにしてください。バッチフィードと同様に、より多くのデータを適合させるために空白を削除することをおすすめします。
- エンベロープは次のとおりです。
{ "entity": { "data":"ENTITY_DATA", "vertical":"FOODORDERING" }, "update_time":"UPDATE_TIMESTAMP" }
上記のペイロードで、次のように置き換えます。
- ENTITY_DATA: 文字列としてシリアル化された JSON 形式のエンティティ。JSON-LD エンティティは、
data
フィールドに文字列として渡す必要があります。 - UPDATE_TIMESTAMP(省略可): システムでエンティティが更新された時点のタイムスタンプ。時刻に将来の時刻は指定できません。デフォルトのタイムスタンプは、Google がリクエストを受け取った時点です。増分リクエストでエンティティを送信する場合、追加/更新リクエストの場合、エンティティのバージョニングも
update_time
フィールドを使用します。
エンティティの更新
例 1: レストランの更新
レストランの電話番号を緊急に更新する必要があるとします。アップデートには、レストラン全体の JSON が含まれています。
次のようなバッチフィードについて考えてみましょう。
{ "@type": "Restaurant", "@id": "restaurant12345", "name": "Some Restaurant", "url": "https://www.provider.com/somerestaurant", "telephone": "+16501234567", "streetAddress": "345 Spear St", "addressLocality": "San Francisco", "addressRegion": "CA", "postalCode": "94105", "addressCountry": "US", "latitude": 37.472842, "longitude": -122.217144 }
この場合、HTTP POST による増分アップデートは次のようになります。
POST v2/apps/provider-project/entities/Restaurant/restaurant12345:push Host: actions.googleapis.com Content-Type: application/ld+json { "entity": { "data": { "@type": "Restaurant", "@id": "restaurant12345", "name": "Some Restaurant", "url": "https://www.provider.com/somerestaurant", "telephone": "+16501235555", "streetAddress": "345 Spear St", "addressLocality": "San Francisco", "addressRegion": "CA", "postalCode": "94105", "addressCountry": "US", "latitude": 37.472842, "longitude": -122.217144 }, "vertical": "FOODORDERING" } }
例 2: メニュー アイテムの価格を更新する
メニュー アイテムの価格を変更する必要があるとします。例 1 と同様に、更新には最上位エンティティ(メニュー)全体の JSON が含まれている必要があります。フィードでは v1 在庫スキーマを使用します。
次のようなバッチフィードについて考えてみましょう。
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
この場合、POST による増分アップデートは次のようになります。
POST v2/apps/provider-project/entities/MenuItemOffer/menuitemoffer6680262:push Host: actions.googleapis.com Content-Type: application/ld+json { "entity": { "data": { "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 1.00, "priceCurrency": "USD" }, "vertical": "FOODORDERING" } }
エンティティの追加
エンティティを追加するには、在庫の更新を使用しないでください。代わりに、v2 在庫スキーマの説明に沿ってバッチフィードのプロセスを使用してください。
エンティティの削除
最上位エンティティを削除するには、少し変更したエンドポイントを使用し、リクエストで HTTP POST ではなく HTTP DELETE を使用します。
HTTP DELETE を使用して、最上位エンティティ内のサブエンティティ(メニュー内のメニュー項目など)を削除しないでください。代わりに、サブエンティティの削除は、トップレベル エンティティに対する更新として扱い、関連リストまたはパラメータからサブエンティティを削除します。
例 1: 最上位エンティティの削除
たとえば、v1 在庫スキーマを使用するフィードでレストランを削除する場合について考えてみましょう。そのサービスとメニューも削除する必要があります。
ID が「https://www.provider.com/restaurant/menu/nr」のメニュー エンティティのサンプル エンドポイント:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
ID が「https://www.provider.com/restaurant/nr」であるレストラン エンティティのサンプル エンドポイント:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
ID が「https://www.provider.com/restaurant/service/nr」であるサービス エンティティのサンプル エンドポイント:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}
例 2: サブエンティティの削除
最上位エンティティからサブエンティティを削除するには、対応するフィールドからサブエンティティを削除して、上位エンティティを送信します。次の例では、フィードが v1 在庫スキーマを使用していることを前提としています。
たとえば、サービス提供地域を削除するには、areaServed
リストからサービス提供地域を削除してサービスを更新します。
POST v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fservice%2Fnr:push
Host: actions.googleapis.com
Content-Type: application/ld+json
{
"entity": {
// Note: "data" is not serialized as a string in our example for readability.
"data": {
"@type": "Service",
"provider": {
"@type": "Restaurant",
"@id": "https://www.provider.com/restaurant/nr"
},
"areaServed": [
{
"@type": "GeoCircle",
"geoMidpoint": {
"@type": "GeoCoordinates",
"latitude": "42.362757",
"longitude": "-71.087109"
},
"geoRadius": "10000"
}
// area2 is removed.
]
...
},
"vertical": "FOODORDERING"
}
}
API レスポンス コード
呼び出しが成功しても、それはフィードが有効または正しいということではなく、API 呼び出しが行われたことだけです。呼び出しに成功すると、HTTP レスポンス コード 200 とともに空のレスポンス本文が返されます。
{}
失敗すると、HTTP レスポンス コードは 200 ではなく、エラーの原因はレスポンスの本文に表示されます。
たとえば、ユーザーがエンベロープの「vertical」値を FAKE_VERTICAL
に設定すると、次のようなメッセージが表示されます。
{
"error": {
"code": 400,
"message": "Invalid value at 'entity.vertical' (TYPE_ENUM), \"FAKE_VERTICAL\"",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "entity.vertical",
"description": "Invalid value at 'entity.vertical' (TYPE_ENUM), \"FAKE_VERTICAL\""
}
]
}
]
}
}
コードサンプル
以下に、さまざまな言語での Incremental Updates API の使用方法の例を示します。以下のサンプルでは Google 認証ライブラリを使用し、フィードは v1 在庫スキーマを使用することを前提としています。別の解決策については、サーバー間アプリケーションに OAuth 2.0 を使用するをご覧ください。
エンティティの更新
Node.js
このコードでは Node.js 用の Google 認証ライブラリを使用しています。
const {auth} = require('google-auth-library') const request = require('request'); // The service account client secret file downloaded from the Google Cloud Console const serviceAccountJson = require('./service-account.json') // entity.json is a file that contains the entity data in json format const entity = require('./entity.json') const ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant' const PROJECT_ID = 'your-project-id' /** * Get the authorization token using a service account. */ async function getAuthToken() { let client = auth.fromJSON(serviceAccountJson) client.scopes = ['https://www.googleapis.com/auth/assistant'] const tokens = await client.authorize() return tokens.access_token; } /** * Send an incremental update to update or add an entity */ async function updateEntity(entityId, entity) { const token = await getAuthToken() request.post({ headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, url: `https://actions.googleapis.com/v2/apps/${PROJECT_ID}/entities/${encodeURIComponent(entityId)}:push`, body: { entity: { data: JSON.stringify(entity), vertical: 'FOODORDERING', } }, json: true }, (err, res, body) => { if (err) { return console.log(err); } console.log(`Response: ${JSON.stringify(res)}`) }) } updateEntity(ENTITY_ID, entity)
Python
このコードは Python 用の Google 認証ライブラリを使用します。
from google.oauth2 import service_account from google.auth.transport.requests import AuthorizedSession import json import urllib PROJECT_ID = 'your-project-id' ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant' ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities/%s:push' % ( PROJECT_ID, urllib.quote(ENTITY_ID, '')) # service-account.json is the service account client secret file downloaded from the # Google Cloud Console credentials = service_account.Credentials.from_service_account_file( 'service-account.json') scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/assistant']) authed_session = AuthorizedSession(scoped_credentials) # Retrieving the entity update_file = open("entity.json") #JSON file containing entity data in json format. data = update_file.read() # Populating the entity with wrapper entity = {} entity['data'] = data #entity JSON-LD serialized as string entity['vertical'] = 'FOODORDERING' request = {} request['entity'] = entity response = authed_session.post(ENDPOINT, json=request) print(response.text) #if successful, will be '{}'
Java
このコードは Java 用の Google 認証ライブラリを使用しています。
private static final String PROJECT_ID = "your-project-id"; private static final String ENTITY_ID = "http://www.provider.com/somerestaurant"; /** * Get the authorization token using a service account. */ private static String getAuthToken() { InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json"); ServiceAccountCredentials.Builder credentialsSimpleBuilder = ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder(); credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/assistant")); AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken(); return accessToken.getTokenValue(); } /** * Send an incremental update to update or add an entity. * @param entityId The id of the entity to update. * @param entity the json of the entity to be updated. */ public void updateEntity(String entityId, JSONObject entity) { String authToken = getAuthToken(); String endpoint = String.format( "https://actions.googleapis.com/v2/apps/%s/entities/%s:push", PROJECT_ID, URLEncoder.encode(entityId, "UTF-8")); JSONObject data = new JSONObject(); data.put("data", entity.toString()); data.put("vertical", "FOODORDERING"); JSONObject jsonBody = new JSONObject(); jsonBody.put("entity", data); // Execute POST request executePostRequest(endpoint, authToken, jsonBody); }
エンティティを削除する
Node.js
このコードでは Node.js 用の Google 認証ライブラリを使用しています。
const {auth} = require('google-auth-library') const request = require('request'); // The service account client secret file downloaded from the Google Cloud Console const serviceAccountJson = require('./service-account.json') // entity.json is a file that contains the entity data in json format const entity = require('./entity.json') const ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant' const PROJECT_ID = 'your-project-id' /** * Get the authorization token using a service account. */ async function getAuthToken() { let client = auth.fromJSON(serviceAccountJson) client.scopes = ['https://www.googleapis.com/auth/assistant'] const tokens = await client.authorize() return tokens.access_token; } /** * Send an incremental update to delete an entity */ async function deleteEntity(entityId) { const token = await getAuthToken() request.delete({ headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, url: `https://actions.googleapis.com/v2/apps/${PROJECT_ID}/entities/${encodeURIComponent(entityId)}?entity.vertical=FOODORDERING`, body: {}, json: true }, (err, res, body) => { if (err) { return console.log(err); } console.log(`Response: ${JSON.stringify(res)}`) }) } deleteEntity(ENTITY_ID)
Python
このコードは Python 用の Google 認証ライブラリを使用します。
from google.oauth2 import service_account from google.auth.transport.requests import AuthorizedSession import json import urllib # Service config PROJECT_ID = 'your-project-id' ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant' DELETE_TIME = '2018-04-07T14:30:00-07:00' ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities/%s?entity.vertical=FOODORDERING&delete_time=%s' % ( PROJECT_ID, urllib.quote(ENTITY_ID, ''), urllib.quote(DELETE_TIME, '')) # service-account.json is the service account client secret file downloaded from the # Google Cloud Console credentials = service_account.Credentials.from_service_account_file( 'service-account.json') scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/assistant']) authed_session = AuthorizedSession(scoped_credentials) response = authed_session.delete(ENDPOINT) print(response.text) #if successful, will be '{}'
Java
このコードは Java 用の Google 認証ライブラリを使用しています。
private static final String PROJECT_ID = "your-project-id"; private static final String ENTITY_ID = "restaurant/http://www.provider.com/somerestaurant"; /** * Get the authorization token using a service account. */ private static String getAuthToken() { InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json"); ServiceAccountCredentials.Builder credentialsSimpleBuilder = ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder(); credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/assistant")); AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken(); return accessToken.getTokenValue(); } /** * Send an incremental update to delete an entity. * @param entityId The id of the entity to delete. */ public void deleteEntity(String entityId) { String authToken = getAuthToken(); String endpoint = String.format( "https://actions.googleapis.com/v2/apps/%s/entities/%s?entity.vertical=FOODORDERING", PROJECT_ID, URLEncoder.encode(entityId, "UTF-8")); // Execute DELETE request System.out.println(executeDeleteRequest(endpoint, authToken)); }
ユースケース
増分更新、完全なフィード更新、API 呼び出しにおけるコンテンツの概要の例を以下に示します。
シナリオ | 最上位エンティティ | 説明と効果 |
---|---|---|
サービスの無効化 | DisabledService |
予期せぬ理由でサービスを無効にする必要がある場合。 増分アップデート: 対象の 完全フィード: Google が次にフェッチする前に、完全フィードのエンティティを更新して、 |
特定の商品が在庫切れである | Menu |
増分アップデート: 指定された MenuItem に対して offer.inventoryLevel を 0 に設定し、他のすべてのデータを変更せずに、カプセル化している Menu エンティティを送信します。 |
メニュー アイテムの価格変更 | Menu |
増分更新: offer.price を指定した MenuItem の更新価格に設定し、他のすべてのデータを変更せずに、カプセル化している Menu エンティティを送信します。 |
新しい最上位エンティティを追加 タイプ |
Menu 、Restaurant 、Service |
たとえば、レストランに新しいメニューを追加する必要がある場合、 増分更新: それに応じて、フィールド |
最上位エンティティを完全に削除する タイプ |
Menu 、Restaurant 、Service |
増分アップデート: 明示的な削除を送信します。 完全フィード: Google が次にフェッチする前に、全文フィードからエンティティを削除してください。削除しないと、エンティティは再度追加されます。 |
特定の Service で新しい配送地域を追加する |
Service |
増分フィード: 完全なフィードの場合と同様に、該当する Service エンティティの全フィールドをそのままにして、新しい配信地域を Service の areaServed 内で指定します。 |
Service の到着予定時刻を更新 |
Service |
増分フィード: フィードの場合と同様に Service を送信しますが、hoursAvailable.deliveryHours はそれに応じて更新されます。 |
「Service 」の配送価格を更新してください |
Service |
増分フィード: offers.priceSpecification.price を更新して完全な Service を送信します。 |
Service の宅配またはテイクアウトの営業時間を更新してください |
Service |
増分フィード: フィードの場合と同様に Service を送信しますが、hoursAvailable はそれに応じて更新されます。 |
Service (最低注文額の変更) |
Service |
増分フィード: Service.offers.priceSpecification.eligibleTransactionVolume を更新して完全な Service を送信します。 |
MenuItem を完全に削除 |
Menu |
増分フィード: フィードの場合と同様に Menu を送信しますが、この MenuItem は hasMenuItems リストから削除します。 |
バッチジョブと増分更新の処理時間に関する SLO
バッチ更新または増分更新で追加されたエンティティは、1 ~ 2 日で処理されます。バッチで更新または削除されたエンティティは 2 時間以内に処理されますが、増分更新で更新されたエンティティは 5 分で処理されます。古いエンティティは 7 日後に削除されます。
次のどちらかを Google に送信できます。
- 在庫を最新の状態に保つために 1 日に複数のバッチジョブを使用する。または
- 1 日に 1 つのバッチジョブと増分 API を使用して在庫を最新の状態に保つ