Pembaruan inventaris inkremental v2

Bagian ini menjelaskan cara mengirim pembaruan yang mendesak dari entitas inventaris Anda ke Google. Dengan Nested Update API, Anda dapat mengirim update dan menghapus entity di inventaris Sandbox atau Produksi secara hampir real time.

Fungsi ini utamanya ditujukan untuk pembaruan yang tidak dapat Anda perkirakan, seperti penutupan darurat. Pada umumnya, setiap perubahan yang dikirim melalui inkremental Update API haruslah perubahan yang harus diterapkan tidak lebih dari satu jam. Jika perubahan tidak perlu segera diterapkan, Anda dapat menggunakan penyerapan batch. Pembaruan inkremental diproses dalam waktu tidak lebih dari lima menit.

Prasyarat

Item berikut diperlukan sebelum Anda menerapkan update inkremental:

1. Akun layanan dibuat dengan peran editor untuk project Action Anda. Untuk mengetahui detail selengkapnya, lihat Membuat dan menyiapkan project.
2. Feed data produksi atau sandbox dihosting dan diserap. Untuk mengetahui detail selengkapnya, lihat Penyerapan batch.
3. (Opsional, tetapi direkomendasikan) Instal library Klien Google dalam bahasa pilihan Anda untuk memfasilitasi penggunaan OAuth 2.0 saat memanggil API. Contoh kode yang disertakan di bawah ini menggunakan library ini. Jika tidak, Anda harus menangani pertukaran token secara manual seperti yang dijelaskan dalam Menggunakan OAuth 2.0 untuk Mengakses Google API.

Endpoints

Pada permintaan di bawah ini, ganti hal berikut:

• PROJECT_ID: Project ID Google Cloud yang terkait dengan project yang Anda buat di Membuat dan menyiapkan project.
• TYPE: Jenis entity (properti @type) objek di feed data yang ingin Anda perbarui.
• ENTITY_ID (hanya hapus endpoint): ID entity yang akan dihapus. Pastikan untuk mengenkode ID entitas Anda ke URL.
• DELETE_TIME (hapus endpoint saja): Kolom opsional untuk menunjukkan waktu penghapusan entity di sistem Anda (defaultnya adalah saat permintaan diterima). Nilai waktu tidak boleh di masa yang akan datang. Saat mengirim entity melalui panggilan inkremental, pembuatan versi entity juga menggunakan kolom delete_time dalam kasus panggilan penghapusan. Format nilai ini sebagai yyyy-mm-ddTHH:mm:ssZ

Memperbarui endpoint

Untuk mengubah entity, buat permintaan HTTP POST ke endpoint berikut dan sertakan payload update dan penambahan. Anda dapat melakukan pembaruan hingga 1.000 entity dalam satu panggilan API.

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

Misalnya, jika Anda ingin memperbarui entity dalam sebuah project dengan ID "delivery-provider-id", endpoint-nya adalah sebagai berikut:

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

Menghapus endpoint

Untuk menghapus entity dalam inventaris Anda, buat permintaan HTTP DELETE ke endpoint berikut.

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

Misalnya, untuk menghapus entitas "MenuSection" dengan ID "menuSection_122" dari project "delivery-provider-id", Anda harus membuat panggilan HTTP DELETE API ke:

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

Lingkungan sandbox

Untuk menggunakan Promotional Update API di inventaris sandbox Anda, ikuti panduan di Endpoint di atas, tetapi buat permintaan ke /v2/sandbox/apps/, bukan ke /v2/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

Mengupdate entity

Setiap permintaan POST harus menyertakan parameter permintaan beserta payload JSON yang berisi data terstruktur dari jenis entity apa pun yang tercantum dalam skema inventaris.

Mengupdate payload

JSON akan muncul sama seperti di feed batch, dengan perbedaan berikut:

• Ukuran isi payload tidak boleh melebihi 5 MB. Demikian pula dengan feed batch, sebaiknya Anda menghapus spasi kosong untuk menyesuaikan lebih banyak data.
• Amplopnya adalah sebagai berikut:

{
  "requests": [
    {
      "entity": {
        "data":"ENTITY_DATA",
        "name": "apps/project_id>/entities/type/entity_id"
      },
      "update_time":"UPDATE_TIMESTAMP"
    },
  ],
  "vertical": "FOODORDERING"
}

Pada payload di atas, ganti hal berikut:

• ENTITY_DATA: Entitas dalam format JSON diserialisasi sebagai string. Entity JSON-LD harus diteruskan sebagai string di kolom data.
• UPDATE_TIMESTAMP (opsional): Stempel waktu saat entity diupdate di sistem Anda. Nilai waktu tidak boleh di masa yang akan datang. Stempel waktu default adalah saat Google menerima permintaan. Saat mengirim entity melalui permintaan inkremental, pembuatan versi entity juga menggunakan kolom update_time dalam kasus permintaan penambahan/update.

Contoh

Contoh 1: Memperbarui restoran

Misalkan Anda perlu segera memperbarui nomor telepon sebuah restoran. Update Anda berisi JSON untuk seluruh restoran.

Pertimbangkan feed batch yang terlihat seperti berikut:

{
  "@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
}

Update inkremental Anda melalui HTTP POST akan menjadi seperti berikut:

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"
}

Contoh 2: Memperbarui beberapa restoran

Untuk memperbarui dua entitas restoran dalam satu panggilan API, permintaan HTTP POST adalah sebagai berikut:

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"
}

Contoh 3: Memperbarui harga item menu

Misalnya, Anda perlu mengubah harga item menu. Seperti pada Contoh 1, update Anda harus berisi JSON untuk seluruh entity level teratas (menu), dan feed menggunakan skema inventaris v1.

Pertimbangkan feed batch yang terlihat seperti berikut:

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

Maka update inkremental Anda melalui POST akan menjadi seperti berikut:

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"
}

Menambahkan entity

Untuk menambahkan entitas, hindari penggunaan pembaruan inventaris. Sebagai gantinya, gunakan proses feed batch seperti yang dijelaskan untuk skema inventaris v2.

Menghapus entitas

Untuk menghapus entity level teratas, gunakan endpoint yang sedikit dimodifikasi, dan gunakan HTTP DELETE, bukan HTTP POST dalam permintaan.

Menghapus entity level teratas

Pertimbangkan situasi saat Anda ingin menghapus restoran dalam feed. Anda juga harus menghapus layanan dan menunya.

Contoh endpoint untuk entity menu dengan ID "provider/restaurant/menu/nr":

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

Contoh endpoint untuk entity restoran dengan 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

Contoh endpoint untuk entity layanan dengan 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
}

Menghapus sub-entitas

Jangan gunakan HTTP DELETE untuk menghapus sub-entity dalam entity level teratas, seperti item menu dalam menu. Sebagai gantinya, perlakukan penghapusan sub-entitas sebagai pembaruan pada entity level teratas tempat sub-entity dihapus dari daftar yang relevan atau reverseReference.

Kode respons API

Panggilan yang berhasil bukan berarti feed valid atau benar, hanya berarti panggilan API dilakukan. Panggilan yang berhasil akan menerima kode respons HTTP 200, beserta isi respons kosong:

{}

Jika terjadi kegagalan, kode respons HTTP tidaklah 200, dan isi respons menunjukkan masalahnya.

Misalnya, jika pengguna telah menetapkan nilai "vertikal" dalam amplop ke FAKE_VERTICAL, Anda akan menerima pesan di bawah:

{
  "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\""
          }
        ]
      }
    ]
  }
}

Contoh kode

Berikut adalah beberapa contoh cara menggunakan inkremental Update API dalam berbagai bahasa. Contoh ini menggunakan Library Google Auth, dan mengasumsikan feed menggunakan skema inventaris v1. Untuk solusi alternatif, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.

Mengupdate entity

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)

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 '{}'

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);
}

Menghapus entitas

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)

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 '{}'

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));
}

Kasus penggunaan

Kasus penggunaan berikut adalah contoh update inkremental, update feed lengkap, dan konten level tinggi dalam panggilan API:

SLO tentang waktu pemrosesan untuk tugas batch dan update inkremental

Entity yang diperbarui atau dihapus melalui batch akan diproses dalam waktu 2 jam dalam mode upaya terbaik, sedangkan entitas yang diperbarui melalui update inkremental akan diproses dalam 5 menit. Entitas yang sudah tidak berlaku akan dihapus dalam 7 hari.

Anda dapat mengirim:

• Beberapa tugas batch per hari untuk menjaga inventaris Anda tetap terbaru, ATAU
• Satu tugas batch per hari dan API inkremental untuk menjaga inventaris Anda tetap terbaru.