As RTUs se destinam principalmente a atualizações que você não pode prever, como fechamentos de emergência ou metadados que mudam periodicamente (como HECs). Se a mudança não precisar aparecer imediatamente, use a ingestão de feeds em lote. As atualizações em tempo real são processadas em no máximo cinco minutos.
Configuração do Google Cloud Platform
- Configure um projeto do GCP. É necessário um projeto do GCP para acessar a API RTU.
- Conceder acesso de editor food-support@google.com
- Informe o número do projeto do GCP ao seu POC do Google.Para que as atualizações em tempo real funcionem, o projeto do GCP precisa estar associado à sua conta da Central de ações.
- Ative a API Maps Booking:
- No GCP, acesse APIs e Serviços > Biblioteca.
- Pesquise "API Google Maps Booking".
- Encontre a instância do sandbox ("API Google Maps Booking (Dev)" e clique em Ativar
- Encontre a instância de produção ("API Google Maps Booking") e clique em Ativar
- Criar uma conta de serviço com papel de editor no projeto do GCP. Para mais detalhes, consulte Configuração da conta de serviço.
- Certifique-se de fazer upload dos feeds em lote para o ambiente no qual você está trabalhando nas atualizações em tempo real.
- Para a autenticação de API, recomendamos instalar a biblioteca de cliente do Google no idioma de sua escolha. Use “https://www.googleapis.com/auth/mapsbooking” como o escopo do OAuth. Os exemplos de código abaixo usam essas bibliotecas. Caso contrário, você precisará processar trocas de token manualmente, conforme descrito em Como usar o OAuth 2.0 para acessar as APIs do Google.
Configuração da conta de serviço
Você precisa de uma conta de serviço para fazer solicitações HTTPS autenticadas às APIs do Google, como a API de atualizações em tempo real.
Para configurar uma conta de serviço, faça o seguinte:
- Acesse o console do Google Cloud Platform.
- Sua conta na Central de ações também tem um projeto do Google Cloud associado a ela. Selecione o projeto, se ele ainda não estiver selecionado.
- Clique em Contas de serviço no menu à esquerda.
- Clique em Criar conta de serviço.
- Digite um nome para a conta de serviço e clique em Criar.
- Em Selecionar papel, escolha Projeto > Editor.
- Clique em Continuar.
- Opcional: adicione usuários para conceder a eles acesso à conta de serviço e clique em Concluído.
- Clique em Mais > Crie uma chave para a conta de serviço que você acabou de criar.
- Selecione JSON como o formato e clique em Criar.
- Depois que o novo par de chaves públicas/privadas for gerado, faça o download dele para sua máquina.
Como trabalhar com a API
A API de atualizações em tempo real oferece suporte a dois tipos de operações: atualização e exclusão. Não é possível adicionar novas entidades usando a API de atualização em tempo real. As atualizações em tempo real podem ser agrupadas se você incluir várias atualizações em uma única solicitação de API. É possível agrupar até mil atualizações em uma única chamada de API. Se possível, recomendamos utilizar uma abordagem com base em gatilhos para enviar atualizações por RTU (ou seja, quando uma alteração de dados no sistema acionar uma atualização em tempo real para o Google), em vez de usar uma abordagem com base em frequência (por exemplo, a cada X minutos, verifique se há alterações no sistema).
A API de atualizações em tempo real opera em ambientes de sandbox e de produção. O ambiente de sandbox é usado para testar as solicitações de API e o ambiente de produção para atualizar o conteúdo visível para os usuários de pedidos de ponta a ponta.
- Sandbox:
partnerdev-mapsbooking.googleapis.com - Produção:
mapsbooking.googleapis.com
Endpoints
A API de atualizações em tempo real expõe dois endpoints para lidar com as solicitações recebidas para atualizações de inventário:
- ATUALIZAÇÃO -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - EXCLUIR -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
O parâmetro PARTNER_ID pode ser encontrado na Central de ações, na página Conta e usuários, conforme mostrado na captura de tela abaixo.
Considerando 10000001 como o valor de PARTNER_ID um exemplo da captura de tela acima, os URLs completos para enviar solicitações de API no sandbox e na produção serão semelhantes aos exemplos abaixo.
Atualização do sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
EXCLUSÃO do sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Atualização de produção
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Produção DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Como atualizar entidades
Para atualizar entidades no seu inventário, use o endpoint update em uma solicitação HTTP POST. Cada solicitação POST deve incluir o parâmetro 10000001 junto com um payload JSON contendo a entidade que você quer atualizar.
Observação:verifique se os feeds de dados diários também contêm as alterações enviadas pela API de atualizações em tempo real. Caso contrário, seus dados podem estar desatualizados ou desatualizados.
Atualizar payload da solicitação
O corpo da solicitação é um objeto JSON com uma lista de registros. Cada registro corresponde a uma entidade que está sendo atualizada. Ele consiste no campo proto_record e no generation_timestamp, que indica o horário da atualização da entidade:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: a conversão proto ou JSON da entidade ServiceData que você está atualizando.UPDATE_TIMESTAMP: inclua o carimbo de data/hora de quando a entidade foi gerada nos sistemas de back-end. Se esse campo não for incluído, ele será definido como o horário em que o Google receberá a solicitação. Ao atualizar uma entidade usando uma solicitaçãobatchPush, o campogeneration_timestampé usado para o controle de versões da entidade. Veja o formato esperado de valores de tempo no esquema do inventário relacional.
- O corpo do payload não pode exceder 5 MB.
- Retira os espaços em branco para reduzir o tamanho.
- Pode haver até mil atualizações em uma solicitação
batchPush.
Exemplos
Atualizar um HEC
Suponha que você precise atualizar com urgência o HEC de um serviço de entrega de 30 a 60 para 60 a 90 minutos. A atualização precisa conter o JSON de toda a entidade de serviço.
Considere uma entidade de serviço semelhante a esta:
{
"service": {
"service_id": "service/entity002",
"service_type": "DELIVERY",
"parent_entity_id": "entity002",
"lead_time": {
"min_lead_time_duration": "600s",
"max_lead_time_duration": "1800s"
},
"action_link_id": "delivery_link/entity002"
}
}
Veja a seguir a atualização em tempo real feita pelo POST HTTP (os corpos das solicitações estão impressos para facilitar a leitura):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
"records": [{
"proto_record": {
"@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
"service" : {
"service_id" : "23456/delivery",
"service_type" : "DELIVERY",
"parent_entity_id" : "23456",
"disabled" : "false",
"action_link_id": "delivery_link/entity002",
"lead_time" : {
"min_lead_time_duration" : {
"seconds": "3600"
},
"max_lead_time_duration" : {
"seconds": "5400"
}
}
}
},
"generation_timestamp": "2023-09-13T17:11:10.750Z"
}]
}
Atualizar várias entidades
Para atualizar várias entidades de restaurante em uma única chamada de API, inclua vários registros no campo proto_record do corpo da solicitação.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
"records": [{
"proto_record": {
"@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
"service" : {
"service_id" : "23456/delivery",
"service_type" : "DELIVERY",
"parent_entity_id" : "23456",
"disabled" : "false",
"action_link_id": "delivery_link/entity002",
"lead_time" : {
"min_lead_time_duration" : {
"seconds": "1800"
},
"max_lead_time_duration" : {
"seconds": "3600"
}
}
}
},
"generation_timestamp": "2023-09-13T17:11:10.750Z"
},
{
"proto_record": {
"@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
"fee" : {
"fee_id" : "12345/delivery_fee",
"fee_type" : "DELIVERY",
"fixed_amount" : {
"currency_code" : "USD",
"units" : "10",
"nanos" : "0"
},
"service_ids": ["service/entity002"]
}
},
"generation_timestamp" : "2023-09-13T17:11:10.750Z"
}]
}
Excluir entidades
Para excluir entidades do seu inventário, use o endpoint DELETE em uma solicitação HTTP POST. Cada solicitação POST precisa incluir o parâmetro PARTNER_ID com o payload JSON que contém o identificador da entidade que você quer excluir.
Observação:verifique se os feeds de dados diários também contêm as alterações enviadas pela API de atualização em tempo real. Caso contrário, a ingestão diária em lote vai substituir as alterações em tempo real.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
"records": [{
"proto_record": {
"@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
"service" : {
"service_id" : "23456/delivery"
}
},
"delete_time": "2023-09-13T17:11:10.750Z"
},
{
"proto_record": {
"@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
"fee" : {
"fee_id" : "12345/delivery_fee"
}
},
"delete_time" : "2023-09-13T17:11:10.750Z"
}]
}
Adicionar entidades
Não use atualizações em tempo real para adicionar novas entidades, porque isso pode resultar em inconsistências de dados. Em vez disso, use feeds em lote.
Validação e Códigos de resposta da API
Há dois tipos de validações realizadas nas chamadas de API de atualização em tempo real:
- Nível da solicitação: essas validações verificam se o payload segue o esquema e se cada
proto_recordcontém um campoidetype. Essas verificações são síncronas e os resultados são retornados no corpo da resposta da API. Um código de resposta 200 e um corpo JSON vazio{}significam que essas validações foram aprovadas e que as entidades dessa solicitação foram colocadas na fila para processamento. Um código de resposta diferente de 200 significa que uma ou mais dessas validações falharam e a solicitação inteira foi rejeitada (incluindo todas as entidades na carga). Por exemplo, se umproto_recordnão tiver um@type, a seguinte resposta de erro será retornada:
{
"error": {
"code": 400,
"message": "Record:{...}",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value."
}
]
}
- Nível da entidade: cada entidade (proto_record) no payload é validada em relação ao esquema. Os problemas encontrados nessa fase de validação não são informados na resposta da API. Elas são informadas apenas no painel de relatórios de RTU da Central de ações.
Observação:o código de resposta 200 não significa que todas as entidades foram ingeridas.
Cotas da API
As atualizações de API em tempo real têm uma cota de 1.500 solicitações a cada 60 segundos,ou 25 solicitações por segundo, em média. Quando uma cota é excedida, o Google responde com a seguinte mensagem de erro:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Para lidar com isso, repita a chamada em intervalos exponencialmente maiores até conseguir. Se você esgotar a cota regularmente, inclua mais entidades em uma solicitação de API. É possível incluir até mil entidades em uma chamada de API.
Atualizações em tempo real de tempos de processamento
Uma entidade atualizada por meio de uma atualização em tempo real é processada em cinco minutos.