Pembaruan inventaris inkremental v2

Bagian ini menjelaskan cara mengirim pembaruan yang mendesak terhadap waktu untuk inventaris Anda entitas kepada Google. API Pembaruan Inkremental memungkinkan Anda mendorong pembaruan dan menghapus entity di inventaris Sandbox atau Produksi secara hampir real time.

Fungsi ini terutama ditujukan untuk pembaruan yang tidak dapat Anda antisipasi, seperti penutupan darurat. Biasanya, setiap perubahan yang dikirimkan melalui API Pembaruan Inkremental harus berupa perubahan yang harus ditayangkan tidak lebih dari satu jam. Jika perubahan Anda tidak perlu segera dicerminkan, Anda dapat menggunakan penyerapan batch sebagai gantinya. 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 Compute Engine API. Contoh kode yang disertakan di bawah ini menggunakan library ini. Jika tidak, Anda akan harus menangani pertukaran token secara manual seperti yang dijelaskan dalam Menggunakan OAuth 2.0 untuk Mengakses Google API.

Endpoint

Pada permintaan di bawah, ganti kode berikut:

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

Memperbarui endpoint

Untuk mengubah entity, buat permintaan POST HTTP ke endpoint berikut dan menyertakan 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 suatu 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 di 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 "MenuSection" entitas dengan ID "menuSection_122" dari "delivery-provider-id" Anda 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 API Pembaruan Inkremental di inventaris sandbox, ikuti panduan di Endpoint di atas, tetapi membuat 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 bersama dengan JSON payload yang berisi data terstruktur dari jenis entitas apa pun yang tercantum dalam skema inventaris Anda.

Mengupdate payload

JSON akan terlihat sama seperti yang ada di feed batch, dengan perbedaan berikut:

  • Isi payload tidak boleh melebihi 5 MB. Serupa dengan batch feed, sebaiknya hapus spasi kosong demi mendapatkan 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"
}

Dalam payload di atas, ganti kode berikut:

  • ENTITY_DATA: Entitas dalam format JSON diserialisasi sebagai string. Tujuan Entitas JSON-LD harus diteruskan sebagai string di kolom data.
  • UPDATE_TIMESTAMP (opsional): Stempel waktu saat entitas diperbarui sistem-sistem Anda. Nilai waktu tidak boleh di masa mendatang. Stempel waktu default adalah saat Google akan menerima permintaan tersebut. Saat mengirim entitas melalui permintaan, pembuatan versi entitas juga menggunakan update_time jika ada permintaan tambahkan/pembaruan.

Contoh

Contoh 1: Memperbarui restoran

Misalkan Anda sangat perlu memperbarui nomor telepon sebuah restoran. Nama 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
}

Maka 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 entity 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

Misalkan Anda perlu mengubah harga item menu. Seperti di Contoh 1, harus berisi JSON untuk seluruh entitas level teratas (menu), dan 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 pembaruan inkremental Anda melalui 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/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 feed batch seperti yang dijelaskan untuk skema inventaris v2.

Menghapus entity

Untuk menghapus entitas tingkat teratas, gunakan endpoint yang sedikit diubah, dan gunakan HTTP DELETE, bukan HTTP POST dalam permintaan.

Menghapus entity tingkat teratas

Bayangkan situasi saat Anda ingin menghapus restoran di feed. Anda harus menghapus juga 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 entitas 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 entitas 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-entitas dalam entitas level teratas, seperti item menu dalam menu. Sebaliknya, perlakukan penghapusan subentitas sebagai pembaruan entitas tingkat teratas tempat sub-entitas dihapus dari daftar yang relevan atau reverseReference.

Kode respons API

Panggilan yang berhasil tidak berarti feed valid atau benar, hanya saja Panggilan API telah dilakukan. Panggilan yang berhasil akan menerima kode respons HTTP 200, beserta dengan isi respons kosong:

{}

Jika gagal, kode respons HTTP tidak akan 200, dan isi respons menunjukkan adanya kesalahan.

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

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

Di bawah ini adalah beberapa contoh cara menggunakan API Pembaruan Inkremental 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

Node.js

Kode ini menggunakan library autentikasi Google untuk Node.js.

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

Kode ini menggunakan library autentikasi Google untuk Python.

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

Kode ini menggunakan library autentikasi Google untuk Java.

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 entity

Node.js

Kode ini menggunakan library autentikasi Google untuk Node.js.

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

Kode ini menggunakan library autentikasi Google untuk Python.

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

Kode ini menggunakan library autentikasi Google untuk Java.

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 pembaruan inkremental, pembaruan feed lengkap, dan konten di level tinggi dalam panggilan API:

Skenario Entitas yang akan diperbarui Deskripsi dan efek
Menonaktifkan layanan Service

Anda perlu menonaktifkan layanan karena alasan yang tidak terduga.

Update inkremental: Perbarui entity Service di pertanyaan dengan menetapkan properti isDisabled-nya ke true, tetapi menjaga properti lainnya tetap sama.

Feed lengkap: Pastikan untuk memperbarui entitas dari feed lengkap agar isDisabled ditetapkan ke true sebelum pengambilan berikutnya oleh Google. Jika tidak, entitas tersebut akan diaktifkan kembali.

Stok item tertentu habis MenuItemOffer Update inkremental: Mengirim enkapsulasi MenuItemOffer entity dengan inventoryLevel ditetapkan ke 0 untuk nilai yang diberikan MenuItem, dan semua data lainnya tidak berubah.
Perubahan harga item menu MenuItemOffer Update inkremental: Mengirim enkapsulasi MenuItemOffer entitas dengan price ditetapkan ke harga terbaru untuk item yang diberikan MenuItem, dan semua data lainnya tidak berubah.

Tambahkan entitas tingkat teratas baru

Hanya berlaku untuk entity jenis Menu, Restaurant, dan Service.

Menu, Restaurant, Service

Misalnya, Anda perlu menambahkan menu baru ke restoran.

Feed lengkap: Tambahkan entity dalam feed data Anda dan tunggu penyerapan batch.

Menghapus entity tingkat teratas secara permanen

Hanya berlaku untuk entity jenis Menu, Restaurant, dan Service.

Menu, Restaurant, Service

Update inkremental: Mengirim penghapusan eksplisit.

Feed lengkap: Pastikan untuk menghapus entitas dari feed lengkap sebelum pengambilan berikutnya oleh Google, jika tidak, entitas akan ditambahkan kembali.

Tambahkan area pengiriman baru di Service spesifik ServiceArea Feed inkremental: Mengirim entitas ServiceArea yang dimaksud bersama semua kolom tetap utuh, seperti yang biasa Anda lakukan dalam feed lengkap, dengan area pengiriman baru yang ditentukan dalam polygon, geoRadius, atau postalCode.
Perbarui perkiraan waktu tiba pengiriman di Service ServiceHours Feed inkremental: Kirim ServiceHours sama seperti di feed, kecuali leadTimeMin-nya diperbarui sebagaimana mestinya.
Perbarui harga pengiriman di Service Fee Feed inkremental: Kirim pengiriman lengkap Fee dengan price diperbarui.
Perbarui jam buka pengiriman atau bawa pulang di Service ServiceHours Feed inkremental: Kirim ServiceHours sama seperti di feed, kecuali properti opens dan closes-nya diperbarui sebagaimana mestinya.
Service (mengubah jumlah pesanan minimum) Fee Feed inkremental: Kirim Fee lengkap dengan minPrice diperbarui
Menghapus MenuItem secara permanen Menu Feed inkremental: Kirim MenuItem sama seperti yang ada di feed, tetapi dengan parentMenuSectionId kosong.

SLO tentang waktu pemrosesan untuk tugas batch dan update inkremental

Entitas yang diperbarui atau dihapus melalui batch akan diproses dalam 2 jam dalam mode upaya terbaik, sedangkan entitas yang diperbarui melalui pembaruan 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 memastikan inventaris Anda selalu terbaru, ATAU
  • Satu tugas batch per hari dan API Inkremental untuk menjaga inventaris Anda tetap terbaru.