このページは Cloud Translation API によって翻訳されました。

v1 の増分在庫の更新

このセクションでは、時間的制約のあるフィードの更新を 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`	予期せぬ理由でサービスを無効にする必要がある場合。増分アップデート: 対象の `Service` エンティティを `@type` を `DisabledService` に変更して送信しますが、他のプロパティは同じに保ってください。完全フィード: Google が次にフェッチする前に、完全フィードのエンティティを更新して、`@type` を `DisabledService` に設定してください。そうしないと、エンティティは再度有効になります。
特定の商品が在庫切れである	`Menu`	増分アップデート: 指定された `MenuItem` に対して `offer.inventoryLevel` を 0 に設定し、他のすべてのデータを変更せずに、カプセル化している `Menu` エンティティを送信します。
メニューアイテムの価格変更	`Menu`	増分更新: `offer.price` を指定した `MenuItem` の更新価格に設定し、他のすべてのデータを変更せずに、カプセル化している `Menu` エンティティを送信します。
新しい最上位エンティティを追加タイプ `Menu`、`Restaurant`、`Service` のエンティティにのみ適用されます。	`Menu`、`Restaurant`、`Service`	たとえば、レストランに新しいメニューを追加する必要がある場合、増分更新: それに応じて、フィールド `hasMenu` が更新されて、レストランエンティティとともに新しいメニューエンティティを送信します。
最上位エンティティを完全に削除するタイプ `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 を使用して在庫を最新の状態に保つ

v1 の増分在庫の更新

設定

エンドポイント

v2 広告枠

v1 広告枠

v2 広告枠

v1 広告枠

サンドボックス リクエスト

更新と追加

ペイロード

エンティティの更新

例 1: レストランの更新

例 2: メニュー アイテムの価格を更新する

エンティティの追加

エンティティの削除

例 1: 最上位エンティティの削除

例 2: サブエンティティの削除

API レスポンス コード

コードサンプル

エンティティの更新

Node.js

Python

Java

エンティティを削除する

Node.js

Python

Java

ユースケース

バッチジョブと増分更新の処理時間に関する SLO

サンドボックスリクエスト

例 2: メニューアイテムの価格を更新する

API レスポンスコード