v2 増分広告枠の更新

このセクションでは、時間的制約のあるインベントリ エンティティの更新を Google に送信する方法について説明します。増分アップデート API を使用すると、サンドボックス インベントリや本番環境インベントリの更新を push し、ほぼリアルタイムで削除できます。

この機能は主に、緊急閉鎖など、予測できない更新を目的としています。原則として、増分更新 API を使用して送信される変更は、1 時間以内に反映する必要がある変更です。変更をすぐに反映する必要がない場合は、代わりにバッチ取り込みを使用できます。増分アップデートは 5 分以内に処理されます。

Prerequisites

増分アップデートを実装するには、以下の項目が必要です。

  1. Actions プロジェクトに対する編集者のロールを持つサービス アカウントが作成されます。詳細については、プロジェクトの作成と設定をご覧ください。
  2. 本番環境またはサンドボックスのデータフィードがホストされ、取り込まれます。詳細については、バッチ取り込みをご覧ください。
  3. （省略可、ただし推奨）選択した言語で Google クライアント ライブラリをインストールして、API を呼び出すときに OAuth 2.0 を使用できるようにします。以下のコードサンプルでは、これらのライブラリを使用しています。それ以外の場合は、OAuth 2.0 を使用した Google API へのアクセスの説明に従って、トークン交換を手動で処理する必要があります。

エンドポイント

以下のリクエストで、次のように置き換えます。

  • PROJECT_ID: プロジェクトの作成と設定で作成したプロジェクトに関連付けられた Google Cloud プロジェクト ID。
  • TYPE: 更新するデータフィードのオブジェクトのエンティティ タイプ（@type プロパティ）。
  • ENTITY_ID（エンドポイントのみを削除）: 削除するエンティティの ID。エンティティ ID は URL エンコードしてください。
  • DELETE_TIME（エンドポイントのみを削除）: エンティティがシステムで削除された時間を示すオプションのフィールド（デフォルトはリクエストの受信時）。過去の日時には将来の日時を指定できません。増分呼び出しでエンティティを送信する場合、エンティティのバージョン管理では、削除呼び出しの場合は delete_time フィールドも使用します。この値を yyyy-mm-ddTHH:mm:ssZ としてフォーマットします。

エンドポイントの更新

エンティティを変更するには、次のエンドポイントに HTTP POST リクエストを行い、更新と追加のペイロードを含めます。1 回の API 呼び出しで最大 1,000 個のエンティティを更新できます。

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush

たとえば、ID が「delivery-provider-id&quot」であるプロジェクトのエンティティを更新する場合、エンドポイントは次のようになります。

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush

エンドポイントの削除

インベントリ内のエンティティを削除するには、次のエンドポイントに HTTP DELETE リクエストを送信します。

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME

たとえば、ID が「menuSection_122」の「MenuSection"」エンティティを "delivery-provider-id" プロジェクトから削除するには、次のような HTTP DELETE API 呼び出しを実行します。

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING

サンドボックス環境

サンドボックスの一覧表で増分更新 API を使用するには、上記のエンドポイントのガイダンスに沿って操作しますが、/v2/apps/ ではなく /v2/sandbox/apps/ にリクエストを送信します。

https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities:batchPush

https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME

エンティティの更新

各 POST リクエストには、リクエスト パラメータとともに、インベントリ スキーマにリストされているエンティティ タイプの構造化データを含む JSON ペイロードを含める必要があります。

ペイロードの更新

JSON はバッチ フィードと同じように表示されますが、次の点が異なります。

  • ペイロード本文のサイズは 5 MB を超えないようにしてください。バッチフィードの場合と同様に、より多くのデータを適合させるため、空白文字を削除することをおすすめします。
  • エンベロープは次のとおりです。
{
  "requests": [
    {
      "entity": {
        "data":"ENTITY_DATA",
        "name": "apps/project_id>/entities/type/entity_id"
      },
      "update_time":"UPDATE_TIMESTAMP"
    },
  ],
  "vertical": "FOODORDERING"
}

上記のペイロードを、次のように置き換えます。

  • 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/sandbox/apps/provider-project/entities:batchPush
Host: actions.googleapis.com
Content-Type: application/ld+json
{
  "requests": [
    {
      "entity": {
        "name": "apps/provider-project/entities/restaurant/restaurant12345",
        "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 回の API 呼び出しで 2 つのレストラン エンティティを更新するには、HTTP POST リクエストは次のようになります。

POST v2/sandbox/apps/provider-project/entities:batchPush
Host: actions.googleapis.com
Content-Type: application/ld+json
{
  "requests": [
    {
      "entity": {
        "name": "apps/provider-project/entities/restaurant/restaurant12345",
        "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
        }
      }
    },
    {
      "entity": {
        "name": "apps/provider-project/entities/restaurant/restaurant123",
        "data": {
          "@type": "Restaurant",
          "@id": "restaurant123",
          "name": "Some Other Restaurant",
          "url": "https://www.provider.com/somerestaurant",
          "telephone": "+16501231235",
          "streetAddress": "385 Spear St",
          "addressLocality": "San Mateo",
          "addressRegion": "CA",
          "postalCode": "94115",
          "addressCountry": "US"
        }
      }
    }
  ]
  "vertical": "FOODORDERING"
}

例 3: メニュー項目の価格を更新する

メニューアイテムの価格を変更する必要があるとします。例 1 のように、更新にはトップレベル エンティティ（メニュー）全体の JSON が含まれ、フィードでは v1 インベントリ スキーマが使用されています。

次のようなバッチフィードについて考えてみます。

{
  "@type": "MenuItemOffer",
  "@id": "menuitemoffer6680262",
  "sku": "offer-cola",
  "menuItemId": "menuitem896532",
  "price": 3.00,
  "priceCurrency": "USD"
}

この場合、POST による増分更新は次のようになります。

POST v2/sandbox/apps/provider-project/entities:batchPush
Host: actions.googleapis.com
Content-Type: application/ld+json
{
  "requests": [
    {
      "entity": {
        "name": "apps/provider-project/entities/menuitemoffer/menuitemoffer6680262",
        "data": {
          "@type": "MenuItemOffer",
          "@id": "menuitemoffer6680262",
          "sku": "offer-cola",
          "menuItemId": "menuitem896532",
          "price": 1.00,
          "priceCurrency": "USD"
        },
        "vertical": "FOODORDERING"
      }
    }
  ]
  "vertical": "FOODORDERING"
}

エンティティの追加

エンティティを追加するには、在庫の更新は使用しないでください。代わりに、v2 広告枠スキーマで説明されているバッチフィードのプロセスを使用してください。

エンティティの削除

最上位のエンティティを削除するには、少し変更されたエンドポイントを使用し、リクエストで HTTP POST ではなく HTTP DELETE を使用します。

トップレベル エンティティの削除

フィード内のレストランを削除する必要がある状況を想定してください。そのサービスとメニューも削除する必要があります。

ID "provider/restaurant/menu/nr" のメニュー エンティティのサンプル エンドポイント:

DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com

ID "https://www.provider.com/restaurant/nr" を持つレストラン エンティティのサンプル エンドポイント:

DELETE v2/apps/delivery-provider-id/entities/restaurant/provider%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com

ID "https://www.provider.com/restaurant/service/nr" を持つサービス エンティティのサンプル エンドポイント:

DELETE v2/apps/delivery-provider-id/entities/service/provider%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}

サブエンティティを削除する

HTTP DELETE を使用して、最上位エンティティ（メニュー内のメニュー項目など）内のサブエンティティを削除しないでください。代わりに、サブエンティティの削除は、関連するリストまたは reverseReference からサブエンティティが削除されたトップレベル エンティティの更新として扱います。

API レスポンス コード

呼び出しが成功したということは、フィードが有効であるとは限りません。また、API 呼び出しが行われた可能性もあります。呼び出しが成功すると、HTTP レスポンス コード 200 と空のレスポンス本文が返されます。

{}

失敗した場合、HTTP レスポンス コードは 200 ではなく、レスポンス本文に何が問題があったかを示します。

たとえば、ユーザーがエンベロープの「カテゴリ」の値を 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\""
          }
        ]
      }
    ]
  }
}

コードサンプル

さまざまな言語で増分アップデート 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 = 'your/entity/id'
const PROJECT_ID = 'type/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(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:batchPush`,
    body: {
      requests: [
        {
          entity: {
            data: JSON.stringify(entity)
            name: `apps/${PROJECT_ID}/entities/${ENTITY_ID}`
          }
        }
      ],
      vertical: 'FOODORDERING'
    },
    json: true
  },
  (err, res, body) => {
    if (err) { return console.log(err); }
    console.log(`Response: ${JSON.stringify(res)}`)
  })
}

updateEntity(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 = 'type/your/entity/id'

ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities:batchPush' % (
    PROJECT_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()

entity = {}
entity['data'] = data #entity JSON-LD serialized as string
entity['name'] = 'apps/%s/entities/%s' % (PROJECT_ID, urllib.quote(ENTITY_ID, '') )

# Populating the request
request = {}
request['entity'] = entity
requestArray = [request]

# Populating the payload
payload = {}
payload['requests'] = requestArray
payload['vertical'] = 'FOODORDERING'

response = authed_session.post(ENDPOINT, json=payload)

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 = "type/your-entity-id";

/**
 * 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 data) {
  String authToken = getAuthToken();
  String endpoint = String.format("https://actions.googleapis.com/v2/apps/%s/entities/:batchPush", PROJECT_ID);

  JSONObject entity = new JSONObject();
  entity.put("data", data.toString());
  entity.put("name", String.format("apps/%s/entities/%s", PROJECT_ID, URLEncoder.encode(ENTITY_ID, "UTF-8")));

  JSONObject request = new JSONObject();
  request.put("entity", entity);

  JSONArray requestArray = new JSONArray();
  requestArray.put(request);

  JSONObject payload = new JSONObject();
  payload.put("requests", requestArray);
  payload.put("vertical", FOODORDERING);

  // Execute POST request
  executePostRequest(endpoint, authToken, payload);
}

エンティティの削除

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 呼び出しで増分更新、フルフィード更新、コンテンツの概要を使用する場合の例です。

シナリオ 更新するエンティティ 説明と効果
サービスを無効にする Service

予期しない理由でサービスを無効にする必要があります。

増分更新: 対象の Service エンティティを isDisabled プロパティを true に設定して更新しますが、他のプロパティは同じに保ちます。

完全なフィード: Google が次に取得するデータの前に、完全なフィードのエンティティを更新して、isDisabled を true に設定してください。そうしないと、エンティティは再び有効になります。
特定の商品が在庫切れである MenuItemOffer 増分更新: 指定された MenuItem の inventoryLevel を 0 に設定して、カプセル化された MenuItemOffer エンティティを送信します。その他のデータはすべて変更しません。
メニュー アイテム価格の変更 MenuItemOffer 増分更新: price が特定の MenuItem の更新済み価格に設定され、他のデータはすべて変更されていない、カプセル化された MenuItemOffer エンティティを送信します。

新しい最上位のエンティティを追加

タイプが Menu、Restaurant、Service のエンティティにのみ適用されます。

 Menu、Restaurant、Service

たとえば、レストランに新しいメニューを追加する必要があります。

全文フィード: データフィードにエンティティを追加し、一括取り込みが完了するまで待ちます。

最上位のエンティティを完全に削除

タイプが Menu、Restaurant、Service のエンティティにのみ適用されます。

 Menu、Restaurant、Service

増分更新: 明示的な削除を送信します。

完全なフィード: Google が次に取得するデータの前に、完全なフィードからエンティティを削除してください。削除しない場合、エンティティは再度追加されます。
特定の Service に新しい配送エリアを追加する ServiceArea 増分フィード: 通常のフィードと同じように通常の ServiceArea エンティティもフィールドはそのまま送信しますが、新しい配信地域は polygon、geoRadius、postalCode の形で指定します。
Serviceの配達予定時刻を更新します ServiceHours 増分フィード: ServiceHours はフィードと同様に送信しますが、leadTimeMin が適宜更新されます。
Serviceの送料を更新 Fee 増分フィード: price を更新して完全配信の Fee を送信します。
Serviceの配達時間またはテイクアウト時間を更新してください ServiceHours 増分フィード: ServiceHours はフィードと同様に送信しますが、opens プロパティと closes プロパティが適宜更新されます。
Service（最低注文額を変更） Fee 増分フィード: minPrice を含む完全な Fee を送信します。
MenuItem を完全に削除 Menu 増分フィード: フィードと同じ MenuItem を送信しますが、parentMenuSectionId は空です。

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

バッチで更新または削除されたエンティティはベスト エフォート モードで 2 時間以内に処理されますが、増分更新で更新されたエンティティは 5 分で処理されます。古いエンティティは 7 日後に削除されます。

次のいずれかを Google に送信できます。

  • 在庫を最新の状態に保つために、1 日に複数のバッチジョブを作成する。
  • 1 日あたり 1 つのバッチジョブと、在庫を最新の状態に保つための増分 API。