Visão geral da integração

Anúncios de Serviços Locais (LSA, na sigla em inglês) para parcerias com agregadores para exibir as fichas deles no Google.com. Neste guia, descrevemos como os agregadores podem fornecer dados estruturados LSA sobre os provedores deles. Especificamente, documentamos o conjunto de agregadores de endpoints de API que precisam ser implementados para integrar com o LSA.

Glossário

Agregador (ou parceiro): são parceiros que agregam provedores para quem oferecem serviços e cujos dados podem ser fornecidos à LSA.

Fornecedor (ou ficha da empresa) de terceiros: são as pequenas empresas individuais (por exemplo, encanamento de João), que tem uma relação comercial com agregadores. Agregadores fornecem informações sobre essas empresas aos Serviços Locais.

Visão geral

Os agregadores fornecerão dados sobre seus provedores (empresas) para os Serviços Locais usando feeds. Cada feed consiste em dados sobre vários provedores. Em um feed, os dados sobre um único fornecedor são encapsulados por um item do feed. Cada feed também especifica um carimbo de data/hora que indica a atualização. Cada feed também especifica um tipo de feed, que pode ser dados sobre o perfil ou avaliações do provedor, conforme descrito abaixo.

Tipos de feed

Para a integração inicial, cada feed pode ser um dos seguintes tipos:

  • Feeds de perfil: este feed fornece informações sobre perfis de provedores. Cada item de feed encapsula informações de perfil sobre um provedor específico. Isso inclui o ID da empresa, o nome da empresa, os locais de veiculação, os serviços oferecidos, o horário de funcionamento etc. O item do feed também contém metadados de veiculação dessa empresa (por exemplo, valor de orçamento mensal, status do anúncio etc.).

  • Feeds de avaliações: este feed fornece informações sobre avaliações de provedores. Cada item de feed encapsula uma lista detalhada de consumidores de um provedor específico. Cada avaliação de consumidor consiste no nome do consumidor, classificação (1 - 5), texto da avaliação, carimbo de data/hora da avaliação etc.

Veja mais detalhes sobre os campos específicos e a semântica deles no feed de perfil e no feed de avaliações.

Ingestão de feed

Os dados dos feeds são serializados como JSON. Para enviar dados, a LSA é compatível apenas com um mecanismo de pull. Há planos futuros para oferecer suporte a um mecanismo de push.

Mecanismo de puxar

No mecanismo de pull, os agregadores são compatíveis com um conjunto de endpoints REST predefinidos (URLs) que enviam e recebem objetos JSON. Isso é análogo para hospedar um ou mais arquivos em um servidor da Web. A LSA emitirá solicitações HTTP GET periodicamente para esses URLs para buscar dados. Veja detalhes sobre os URLs predefinidos na próxima seção sobre endpoints de APIs.

Mecanismo de push

No mecanismo de push, a LSA vai fornecer um endpoint para os agregadores chamarem e fornecerem dados. Em termos sensacionais, isso é o mesmo que um pull, mas oferece flexibilidade nos casos em que os agregadores querem enviar dados específicos para o Serviços Locais. Todas as semânticas, regras ou restrições descritas no protocolo se aplicam ao push e ao pull da mesma maneira.

Endpoints de API

Os agregadores a seguir oferecem suporte aos agregadores: um para o feed de perfil e outro para o feed de avaliação.

Recomendamos que os endpoints contenham informações de versão como a mostrada abaixo. Começamos com v1.

Endpoint Caminho
Feed do perfil /feeds/{version}/profile
Feed de avaliação /feeds/{version}/review

Parâmetro de endpoint

Parâmetros Descrição
maxresults Este é o limite de itens do feed que podem ser solicitados em uma página.
nextpagetoken Token de paginação para acessar a próxima página de resultados

Autenticação de endpoints

O Authentication usa autenticação de acesso básico de HTTP: nome de usuário e senha codificados em base64 para autenticação. Veja um exemplo abaixo.

  • username "Autorização" (para fins ilustrativos)
  • password J9adfdsafc3RfMjpVU1yif5XMw” (para fins ilustrativos)

Caixa de depósito SFTP para push

Caminho da caixa de depósito: partnerupload.google.com:19321

AVISO: os arquivos carregados nesta caixa de depósito SFTP são excluídos automaticamente após 24 horas.

Autenticação de endpoints

  • Par de chaves públicas/privadas (recomendado)

    • Use este tutorial para gerar pares de chaves.
    • Enviar a chave pública ao LSA e manter a chave privada para autenticação
    • A LSA vai usar a chave pública para gerar um nome de usuário e enviar de volta ao agregador

  • Autenticação de senha

    • A LSA vai gerar o nome de usuário e a senha e enviar de volta ao agregador

Referência rápida do comando SFTP

  1. Faça login. Use este comando para fazer login. Deixe de fora -i se você não usar uma chave privada.

    sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

  2. Copiar o arquivo Copie o arquivo no sistema remoto. Use o lls/lcd para o ls/cd no seu sistema local para encontrar o arquivo. Em seguida, copie o arquivo por:

    put <path_to_local_file>

  3. Verifique. Use ls para ver uma lista de pastas e arquivos no diretório SFTP e verifique se o arquivo foi copiado para o sistema remoto

Categorias do feed

Conforme observado anteriormente, cada feed é similar a um arquivo e consiste em vários itens de feed. Cada item do feed encapsula os dados de um determinado provedor (ID da empresa exclusivo). Cada feed também tem um carimbo de data/hora que indica a atualização dele. A categoria do feed especifica como o LSA interpreta um feed específico. Há duas categorias de feeds, conforme descrito abaixo.

O feed de snapshot contém uma lista completa de provedores (em um agregador) em um determinado carimbo de data/hora. Depois de processar esse feed de snapshot, as seguintes semânticas se aplicam:

  • O sistema atualizará os dados do provedor no banco de dados LSA (por exemplo, criará um novo provedor, se encontrado pela primeira vez) ou atualizará os dados do provedor se ele tiver sido processado em um feed anterior para qualquer provedor presente no feed.

  • Qualquer provedor no agregador atualmente presente no banco de dados da LSA, mas ausente no feed, será excluído.

O feed de atualização (ou incremental) contém uma lista parcial de provedores (em um agregador) em um determinado carimbo de data/hora. Depois do processamento de um feed incremental, a seguinte semântica será aplicada:

  • Para qualquer provedor presente no feed, o sistema atualizará os dados desse provedor no banco de dados LSA se o provedor tiver sido criado em um feed de snapshots anterior. (por exemplo, se um provedor for encontrado pela primeira vez, ele será um ambiente autônomo)

  • Para qualquer provedor atualmente presente no banco de dados LSA, mas ausente no feed, ele é um ambiente autônomo (ou seja, não haverá alterações nesse provedor).

A semântica do feed de perfil e de avaliações é um pouco diferenciada. Veja a semântica de feed individual para detalhes de processamento.

Feeds de perfil: * Feeds de snapshots baseados em pull * Feeds de snapshots baseados em push * Feeds de atualização baseados em push Feeds de atualizações baseadas em push: * Feeds de snapshots baseados em pull * Feeds de snapshots baseados em push

Os feeds de perfil separados são obrigatórios para:

  1. Provedores que são considerados qualificados para o selo Garantia do Google ou Avaliado pelo Google.

  2. Provedores que não estão qualificados para o selo.

Examples

Feeds de snapshot

Lembre-se de que um feed de snapshot consiste em uma lista completa de provedores. Por exemplo, se um agregador quiser que 100 provedores sejam ingeridos no LSA, o feed de snapshot vai precisar conter o estado mais recente de todos os 100 provedores.

Como funciona

Veja abaixo um exemplo simples que demonstra como a categoria de snapshot dos feeds de perfil funciona.

  • O snapshot 1 tem o Pro 1, Pro 2
  • O snapshot 2 tem o Pro 1, Pro 3

Depois de processar o Snapshot 1, o banco de dados LSA terá os benefícios Pro 1 e Pro 2. Durante o processamento do snapshot 2, o LSA vai atualizar o Pro 1, criar o Pro 3 e excluir o Pro 2. Ou seja, após o processamento do Snapshot 2, o banco de dados LSA vai ter o Pro 1 e o Pro 3.

Atualizar feeds (incrementais)

Lembre-se de que um feed de atualização contém uma lista parcial de provedores em um agregador. Por exemplo, se um agregador quiser atualizar apenas cinco dos que foram fornecidos anteriormente, o feed de atualização precisará conter apenas o estado mais recente para esses cinco provedores.

Como funciona

Veja abaixo um exemplo simples que demonstra como funciona a categoria de atualização "feeds de perfil".

  • Atualização 1: Pro 1, Pro 2
  • Atualização 2: Pro 1, Pro 3

Após o processamento da Atualização 1, o banco de dados LSA terá as versões Pro 1 e Pro 2. Durante o processamento da atualização 2, o LSA vai atualizar o Pro 1 e criar o Pro 3. Observe que o Pro 2 não é alterado. Ou seja, depois do processamento da atualização 2, o banco de dados LSA terá Pro1, Pro2 e Pro 3.

Implicações do snapshot e do pull

O mecanismo de feeds de snapshot + pull implica as seguintes restrições:

  • Pode haver um atraso de algumas horas para que os parceiros adicionem ou excluam provedores, atualizem informações do perfil, pausem anúncios ou mudem orçamentos. O atraso está diretamente relacionado à frequência das solicitações de envio.
  • Para atualizações urgentes de dados, pode ser necessário oferecer suporte manual a extração única.

Implicações do suporte incremental e push

Abrir o mecanismo update feeds + push implica as seguintes melhorias:

  • Os parceiros podem fornecer feed de snapshot por push ou pull. Para parceiros que preferem não manter o endpoint (para pull), podem usar o push para reduzir o custo de manutenção do endpoint. Os parceiros já oferecem suporte a feeds de snapshot no pull. Se você quiser, continue enviando snapshots no pull.
  • Os parceiros podem usar incrementais para atualizar apenas um subconjunto de provedores com mudanças de perfil. Isso melhora a atualização de dados do perfil.
  • Em termos de como escolher snapshot em vez de incrementais, push x pull, consulte esta seção para ver a abordagem de integração recomendada.

Os parceiros precisam ter feeds periódicos instantâneos, seja por push ou pull. Isso permite que a LSA lide com emergências como reversões e recuperação de sistema em caso de atualizações perdidas.

  • Com o mecanismo de push, os parceiros precisam enviar feeds de perfil de snapshot a cada duas horas e analisar feeds a cada seis horas para garantir a atualização dos dados de referência.
  • Com o mecanismo de pull, a LSA vai extrair feeds de perfil de snapshot a cada duas horas e analisar feeds a cada seis horas para garantir a atualização de dados de referência.
  • Os parceiros só precisam de um dos mecanismos (push ou pull), mas não de ambos, para fornecer feeds de snapshot.

Os parceiros que quiserem melhorar a atualização de dados podem enviar feeds de atualização por push. A LSA não extrai feeds de atualização.

  • Os feeds de atualização são usados para propagar os itens alterados desde o último snapshot sem aguardar o próximo snapshot.
  • A LSA recomenda que os provedores tenham um intervalo de mais de 5 minutos entre duas execuções.
  • É recomendável agrupar os itens de feed razoavelmente em um feed de atualização. Para atualizar cinco provedores, o LSA prefere que os provedores enviem um feed de atualização com cinco itens de feed em vez de enviar cinco feeds de atualização com um item por feed.
  • LSA é compatível com feeds incrementais apenas para feeds de perfis, e não para feeds de avaliações.

O LSA vai respeitar o campo feedTimestampMicros nos metadados para garantir a consistência dos dados. Um item do feed com um carimbo de data/hora mais antigo será ignorado para evitar a inatividade quando um item mais recente que atualiza o mesmo profissional tiver sido ingerido. É responsabilidade do parceiro refletir a atualização dos dados corretamente usando feedTimestampMicros nos feeds de snapshots e de atualização.

Os parceiros precisam usar a API Reporting para receber informações sobre leads e cobranças por provedor.