As RTUs são destinadas principalmente a atualizações que não podem ser previstas, como interdições de emergência ou metadados que mudam periodicamente (como ETAs). Se a mudança não precisar ser refletida imediatamente, use o processamento 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
- Configurar um projeto do GCP. É necessário ter um projeto do GCP para acessar a API RTU.
- Conceda acesso de editor: food-support@google.com
- Informe ao seu contato de operações de parceiro do Google o número do projeto do GCP.Ele precisa estar associado à sua conta da Central de ações para que as atualizações em tempo real funcionem.
- Ativar 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
- Crie 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 de feeds em lote para o ambiente no qual está trabalhando com atualizações em tempo real.
- Para a autenticação de API, recomendamos instalar a biblioteca de cliente do Google na linguagem de sua escolha. Use “https://www.googleapis.com/auth/mapsbooking” como o escopo do OAuth. Os exemplos de código incluídos abaixo usam essas bibliotecas. Caso contrário, você vai precisar processar as 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 para as 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 > Criar 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ública/privada for gerado, faça o download dele para sua máquina.
Como trabalhar com a API
A API Real-time Updates é compatível com 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 poderão 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. Recomendamos o uso de uma abordagem baseada em gatilhos para enviar atualizações por RTU (ou seja, se uma mudança de dados no sistema acionar uma atualização em tempo real para o Google), em vez de uma abordagem com base em frequência (ou seja, se possível, faça uma varredura no sistema para detectar alterações a cada X minutos).
A API de atualizações em tempo real opera em ambientes de sandbox e de produção. O ambiente sandbox é usado para testar as solicitações de API e o ambiente de produção para atualizar o conteúdo visível para 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 de atualização 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 como um exemplo da captura de tela acima, os URLs completos para envio de 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 precisa 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. Ela 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 traduçã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 recebe a solicitação. Ao atualizar uma entidade por 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 de inventário relacional.
- O corpo do payload não pode exceder 5 MB.
- Remova os espaços em branco para reduzir o tamanho.
- Pode haver até 1.000 atualizações em uma solicitação
batchPush.
Exemplos
Atualizar um HEC
Suponha que você precise com urgência para atualizar 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 com a seguinte aparência:
{
"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 por HTTP POST (os corpos das solicitações estão bem 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 restaurantes 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 junto com o payload JSON que contém o identificador da entidade que você deseja 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 os camposidetype. 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 as entidades da solicitação foram enfileiradas para processamento. Um código de resposta diferente de 200 significa que uma ou mais dessas validações falharam e a solicitação inteira é rejeitada (incluindo todas as entidades no payload). 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. Eles só são informados 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 da API em tempo real têm uma cota de 1.500 solicitações a cada 60 segundos ou,em média, 25 solicitações por segundo. 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, tente fazer a chamada novamente 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.
Tempos de processamento: atualizações em tempo real
Uma entidade atualizada por meio de uma atualização em tempo real é processada em cinco minutos.