Atualizações incrementais do inventário v1

Esta seção descreve como enviar atualizações urgentes dos seus feeds para o Google. A API Incremental Updates permite atualizar e excluir entidades nos seus feeds quase em tempo real.

Observação: é necessário adicionar esse recurso à sua ação, a menos que você tenha recebido uma isenção. Se você não tiver certeza se precisa implementar atualizações de inventário, entre em contato com seu consultor do Google.

Essa funcionalidade é destinada principalmente a atualizações que você não pode prever, como fechamentos de emergência. Como regra, qualquer mudança enviada pela API Incremental Updates precisa ser ativada em até uma semana. Se a mudança não precisar ser refletida imediatamente, use uma atualização em lote. As atualizações incrementais são processadas em até cinco minutos.

Configuração

Para implementar atualizações incrementais, faça o seguinte:

1. Siga as etapas descritas em Criar e configurar um projeto para criar um projeto.
2. Siga as etapas descritas em Configurar uma conta de serviço para criar uma conta de serviço. Você precisa ser "Proprietário" do projeto para adicionar uma função de "Editor" à conta de serviço.
3. (Opcional, mas recomendado) Instale a Biblioteca de cliente do Google no idioma de sua escolha para facilitar o uso do OAuth 2.0 ao chamar a API. Os exemplos de código abaixo usam essas bibliotecas. Caso contrário, será necessário processar as trocas de token manualmente, conforme descrito em Como usar o OAuth 2.0 para acessar as APIs do Google.

Endpoint

Para notificar o Google sobre uma atualização, faça uma solicitação HTTP POST para a API Incremental Updates e inclua um payload de atualizações e adições. O esquema de inventário usado determina para qual endpoint fazer a solicitação:

Inventário v2

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push

inventário v1

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push

Para remover uma entidade, faça uma solicitação HTTP DELETE para o endpoint a seguir que corresponde ao esquema de inventário usado:

Inventário v2

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

Inventário v1

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

Nas solicitações acima, substitua o seguinte:

• PROJECT_ID: o ID do projeto do Google Cloud associado ao projeto que você criou em Criar e configurar um projeto.
• TYPE (somente esquema de inventário v2): o tipo de entidade (propriedade @type) do objeto no feed de dados que você quer atualizar.
• ENTITY_ID: ID da entidade incluída no payload. Codifique o ID da entidade em URL.
• DELETE_TIME (somente endpoint de exclusão): campo opcional para indicar o momento em que a entidade foi excluída nos seus sistemas (o padrão é quando a solicitação é recebida). O valor de tempo não pode estar no futuro. Ao enviar uma entidade por uma chamada incremental, o controle de versões de entidade também usa o campo delete_time no caso de uma chamada de exclusão. Formatar este valor como yyyy-mm-ddTHH:mm:ssZ

Por exemplo, você tem um projeto com um ID de "delivery-provider-id" que usa o esquema de inventário v2. Você quer fazer mudanças no restaurante com um tipo de entidade de restaurante "MenuSection" e um ID de entidade "menuSection_122". O endpoint para atualizações dos seus dados será o seguinte:

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push

Para remover essa mesma entidade, faça esta chamada de API HTTP DELETE:

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

Solicitações de sandbox

Para solicitações de sandbox, siga as orientações em Endpoint acima, mas faça solicitações para /v2/sandbox/apps/ em vez de /v2/apps/. Por exemplo, uma solicitação de exclusão de sandbox para o esquema de inventário v2 é estruturada da seguinte maneira:

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

Atualizações e adições

Seus feeds de lote diários também precisam conter todas as mudanças enviadas por essa API. Caso contrário, as atualizações em lote vão substituir as mudanças incrementais.

Payload

Cada solicitação POST precisa incluir os parâmetros de solicitação com o payload JSON que contém os dados estruturados de qualquer tipo de entidade listado no esquema de inventário.

O JSON vai aparecer da mesma forma que no feed em lote, com as seguintes diferenças:

• O corpo do payload não pode exceder 5 MB. Assim como nos feeds em lote, sugerimos que você remova espaços em branco para ajustar mais dados.
• O envelope é o seguinte:

{
  "entity": {
    "data":"ENTITY_DATA",
    "vertical":"FOODORDERING"
  },
  "update_time":"UPDATE_TIMESTAMP"
}

No payload acima, substitua o seguinte:

• ENTITY_DATA: entidade no formato JSON serializada como uma string. A entidade JSON-LD precisa ser transmitida como uma string no campo data.
• UPDATE_TIMESTAMP (opcional): carimbo de data/hora em que a entidade foi atualizada nos seus sistemas. O valor de tempo não pode estar no futuro. O carimbo de data/hora padrão é quando o Google recebe a solicitação. Ao enviar uma entidade por uma solicitação incremental, o controle de versão da entidade também usa o campo update_time no caso de uma solicitação de adição/atualização.

Observação: ao usar o esquema de inventário v1, é necessário enviar a entidade de nível superior inteira, mesmo que você precise atualizar apenas uma parte dela (como o preço de um item de menu). O ID da entidade de nível superior faz parte do URL POST e, portanto, não é incluído como parte do payload JSON-LD da solicitação.

Atualizar uma entidade

Exemplo 1: atualizar um restaurante

Suponha que você precise atualizar com urgência o número de telefone de um restaurante. Sua atualização contém o JSON de todo o restaurante.

Considere um feed em lote parecido com este:

{
  "@type": "Restaurant",
  "@id": "restaurant12345",
  "name": "Some Restaurant",
  "url": "https://www.provider.com/somerestaurant",
  "telephone": "[phone]",
  "streetAddress": "345 Spear St",
  "addressLocality": "San Francisco",
  "addressRegion": "CA",
  "postalCode": "94105",
  "addressCountry": "US",
  "latitude": 37.472842,
  "longitude": -122.217144
}

A atualização incremental por POST HTTP será a seguinte:

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": "[phone]",
      "streetAddress": "345 Spear St",
      "addressLocality": "San Francisco",
      "addressRegion": "CA",
      "postalCode": "94105",
      "addressCountry": "US",
      "latitude": 37.472842,
      "longitude": -122.217144
    },
    "vertical": "FOODORDERING"
  }
}

Observação: no exemplo acima, "data" não é serializado como uma string para facilidade de leitura.

Exemplo 2: atualizar o preço de um item do menu

Suponha que você precise mudar o preço de um item do menu. Como no Exemplo 1, a atualização precisa conter o JSON de toda a entidade de nível superior (o menu), e o feed usa o esquema de inventário v1.

Considere um feed em lote parecido com este:

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

A atualização incremental por POST será a seguinte:

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

Observação: no exemplo acima, "data" não é serializado como uma string para facilidade de leitura.

Como adicionar uma entidade

Para adicionar entidades, evite usar atualizações de inventário. Em vez disso, use o processo de feeds em lote, conforme descrito para o esquema de inventário v2.

Como remover uma entidade

Para remover entidades de alto nível, use um endpoint ligeiramente modificado e use o HTTP DELETE em vez do HTTP POST na solicitação.

Não use o HTTP DELETE para remover uma subentidade em uma entidade de nível superior, como um item de menu em um menu. Em vez disso, trate a remoção de subentidades como uma atualização de uma entidade de nível superior em que a subentidade é removida da lista ou do parâmetro relevante.

Exemplo 1: exclusão de uma entidade de nível superior

Considere uma situação em que você quer excluir um restaurante em um feed que usa o esquema de inventário v1. Você também precisa excluir os serviços e menus.

Um endpoint de exemplo para uma entidade de cardápio com o 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

Um exemplo de endpoint para uma entidade de restaurante com o 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

Um endpoint de exemplo para uma entidade de serviço com o 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
}

Exemplo 2: remoção de subentidades

Para remover uma subentidade de uma entidade de nível superior, envie a entidade de nível superior com a subentidade removida do campo correspondente. O exemplo a seguir pressupõe que o feed usa o esquema de inventário v1.

Por exemplo, para remover uma área de cobertura, atualize o serviço com a área de cobertura removida da lista 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"
  }
}

Observação: o Google processa exclusões em lote, não em tempo real.

Códigos de resposta da API

Uma chamada bem-sucedida não significa que o feed é válido ou correto, apenas que a chamada de API foi feita. As chamadas bem-sucedidas recebem um código de resposta HTTP 200, além de um corpo de resposta vazio:

{}

Em caso de falhas, o código de resposta HTTP não será 200, e o corpo da resposta indicará o que deu errado.

Por exemplo, se o usuário tiver definido o valor "vertical" no envelope como FAKE_VERTICAL, você vai receber a mensagem abaixo:

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

Exemplo de código

Confira abaixo alguns exemplos de como usar a API Incremental Updates em várias línguas. Esses exemplos usam as bibliotecas Google Auth e assumem um feed usando o esquema de inventário v1. Para soluções alternativas, consulte Usar o OAuth 2.0 para aplicativos de servidor para servidor.

Como atualizar entidades

Node.js

Este código usa a biblioteca de autenticação do Google para 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 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

Esse código usa a biblioteca de autenticação do Google para 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 = '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

Esse código usa a biblioteca de autenticação do Google para Java.

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

Como remover entidades

Node.js

Este código usa a biblioteca de autenticação do Google para 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

Esse código usa a biblioteca de autenticação do Google para 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

Esse código usa a biblioteca de autenticação do Google para 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));
}

Casos de uso

Os casos de uso a seguir são exemplos de atualizações incrementais, atualizações completas de feed e o conteúdo em um nível alto na chamada de API:

Cenário	Entidade de nível superior	Descrição e efeitos
Como desativar um serviço	DisabledService	Você precisa desativar um serviço por um motivo imprevisto. Atualizações incrementais:envie a entidade Service em questão com @type alterado para DisabledService, mas mantenha as outras propriedades iguais. Feeds completos:atualize a entidade dos feeds completos para que @type seja definido como DisabledService antes da próxima busca pelo Google. Caso contrário, a entidade será reativada.
Um item específico está esgotado	Menu	Atualizações incrementais:envie a entidade Menu encapsulante com offer.inventoryLevel definido como 0 para o MenuItem fornecido e todos os outros dados inalterados.
Mudança de preço do item do menu	Menu	Atualizações incrementais:envie a entidade Menu encapsulada com offer.price definida como o preço atualizado para o MenuItem fornecido e todos os outros dados inalterados.
Adicionar nova entidade de nível superior Aplicável apenas a entidades dos tipos Menu, Restaurant e Service.	Menu, Restaurant, Service	Por exemplo, você precisa adicionar um novo cardápio a um restaurante. Atualizações incrementais:envie a nova entidade de menu com a entidade de restaurante, e o campo hasMenu dela será atualizado.
Excluir entidade de nível superior permanentemente Aplicável apenas a entidades dos tipos Menu, Restaurant e Service.	Menu, Restaurant, Service	Atualizações incrementais:envie uma exclusão explícita. Feeds completos:remova a entidade dos feeds completos antes da próxima busca pelo Google. Caso contrário, ela será adicionada novamente.
Adicionar uma nova área de entrega em um Service específico	Service	Feeds incrementais:envie a entidade Service em questão com todos os campos intactos, como você faria normalmente nos feeds completos, com a nova área de entrega especificada no areaServed da Service.
Atualizar o horário estimado de chegada da entrega em Service	Service	Feeds incrementais:envie o Service igual aos feeds, exceto que o hoursAvailable.deliveryHours é atualizado de acordo.
Atualizar os preços de entrega em Service	Service	Feeds incrementais:envie um Service completo com o offers.priceSpecification.price atualizado.
Atualizar o horário de entrega ou retirada em Service	Service	Feeds incrementais:envie o Service igual aos feeds, exceto que o hoursAvailable é atualizado de acordo.
Service (mudar o valor mínimo do pedido)	Service	Feeds incrementais:envie um Service completo com o Service.offers.priceSpecification.eligibleTransactionVolume atualizado.
Excluir MenuItem permanentemente	Menu	Feeds incrementais:envie o Menu igual aos feeds, mas com o MenuItem removido da lista hasMenuItems.

SLO no tempo de processamento para trabalhos em lote e atualizações incrementais

Uma entidade adicionada por uma atualização incremental ou em lote será processada em um ou dois dias. Uma entidade atualizada ou excluída em lote será processada em duas horas, enquanto uma entidade atualizada por uma atualização incremental será processada em cinco minutos. Uma entidade desatualizada é excluída em sete dias.

Você pode enviar ao Google:

• Vários jobs em lote por dia para manter seu inventário atualizado OU
• Um job em lote por dia e APIs incrementais para manter seu inventário atualizado.