Anúncios dos Serviços locais (LSA, na sigla em inglês) para fazer parceria com agregadores e mostrar as listagens (ou provedores) deles no Google.com. Neste guia, descrevemos como os agregadores podem fornecer dados estruturados de LSA sobre os provedores. Especificamente, documentamos o conjunto de endpoints de API que os agregadores precisam implementar para a integração com a LSA.
Glossário
Agregador (ou parceiro): são parceiros que agregam provedores a quem prestam serviços e cujos dados podem ser fornecidos para a LSA.
Provedor terceirizado (ou ficha): são as pequenas empresas individuais (por exemplo, Joe’s plumbing), que podem ter uma relação comercial com agregadores. Os agregadores fornecem aos Serviços Locais informações sobre essas empresas.
Visão geral
Os agregadores fornecem dados sobre os provedores (empresas) aos Serviços Locais usando feeds. Cada feed consiste em dados sobre vários provedores. Em um feed, os dados de um único provedor são encapsulados por um item de feed. Cada feed também especifica um carimbo de data/hora que indica se ele está atualizado. Cada feed também especifica um tipo, que pode ser dados sobre o perfil ou as 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: fornecem informações sobre perfis de provedores. Cada item do feed encapsula informações de perfil sobre um provedor específico. Isso inclui um ID exclusivo, nome, locais de veiculação, serviços oferecidos, horário de funcionamento etc. O item de feed também contém metadados de veiculação para essa empresa (por exemplo, valor do orçamento mensal, status do anúncio etc.).
Feeds de avaliações: fornecem informações sobre as avaliações dos provedores. Cada item do feed encapsula uma lista de avaliações detalhadas de um provedor específico. Cada avaliação do consumidor consiste no nome do consumidor, classificação (1 a 5), texto da avaliação, carimbo de data/hora da avaliação etc.
Mais detalhes sobre os campos específicos e a semântica deles em Feed de perfil e Feed de avaliações.
Transferência de feeds
Os dados do feed são serializados como JSON. Para enviar dados, a LSA só vai aceitar um mecanismo de extração. Temos planos de oferecer suporte a um mecanismo de push no futuro.
Mecanismo de pull
No mecanismo de extração, os agregadores oferecem suporte a um conjunto de endpoints REST predefinidos (URLs) que enviam e recebem objetos JSON. Isso é análogo a hospedar um ou mais arquivos em um servidor da Web. A LSA vai emitir periodicamente solicitações HTTP GET para esses URLs e buscar dados. Os detalhes sobre os URLs predefinidos podem ser encontrados na próxima seção sobre endpoints da API.
Mecanismo de push
No mecanismo de push, a LSA fornece um endpoint para os agregadores chamarem e fornecerem dados. Semanticamente, é o mesmo que um pull, mas oferece flexibilidade nos casos em que os agregadores querem enviar dados específicos para os Serviços locais. Todas as semânticas, regras ou restrições descritas no protocolo se aplicam a push e pull da mesma maneira.
Endpoints de API
Os seguintes endpoints precisam ser compatíveis com os agregadores: um para feed de perfil e outro para feed de avaliações.
Caminho de endpoints recomendados
Recomendamos que os endpoints contenham informações de versão, como abaixo. Comece com v1.
| Endpoint | Caminho |
|---|---|
| Feed de perfil | /feeds/{version}/profile |
| Feed de revisão | /feeds/{version}/review |
Parâmetro de endpoint
| Parâmetros | Descrição |
|---|---|
maxresults |
É o limite de itens do feed que podem ser solicitados em uma página. |
nextpagetoken |
Token de paginação para receber a próxima página de resultados. |
Autenticação de endpoints
A autenticação usa a autenticação de acesso básico HTTP: nome de usuário e senha codificados em base64 para autenticação. Veja um exemplo abaixo.
username"Autorização" (para fins ilustrativos)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (para fins ilustrativos)
Caixa de depósito SFTP para Push
Caminho do Dropbox: partnerupload.google.com:19321
AVISO: os arquivos carregados nessa caixa de depósito SFTP são excluídos automaticamente após 24 horas.
Autenticação de endpoints
Par de chaves pública/privada (recomendado)
- Use este tutorial para gerar pares de chaves.
- Envie a chave pública para o LSA e mantenha 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 com senha
- A LSA vai gerar o nome de usuário e a senha e enviar de volta ao agregador.
Referência rápida de comandos SFTP
Faça login. Use este comando para fazer login. (Omita -i
se você não usa uma chave privada). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comCopiar arquivo. Copie o arquivo para o sistema remoto. Você pode usar
lls/lcdparals/cdno sistema local e encontrar o arquivo. Em seguida, copie o arquivo usando:put <path_to_local_file>Verificar. Use
lspara conferir uma lista de pastas e arquivos no diretório SFTP e verifique se o arquivo foi copiado para o sistema remoto.
Categorias de feed
Conforme observado anteriormente, cada feed é análogo a um arquivo e consiste em vários itens de feed. Cada item do feed encapsula dados sobre um provedor específico (ID comercial exclusivo). Cada feed também tem um carimbo de data/hora que indica a atualização dele. A categoria do feed especifica como a LSA interpreta um feed. Há duas categorias de feeds, conforme descrito abaixo.
O feed de resumo contém uma lista completa de provedores (em um agregador) em um carimbo de data/hora específico. Após o processamento desse feed de snapshots, as seguintes semânticas se aplicam:
Para qualquer provedor presente no feed, o sistema vai atualizar os dados dele no banco de dados de LSA. Por exemplo, criar um novo provedor se ele for encontrado pela primeira vez ou atualizar os dados se ele já tiver sido processado em um feed anterior.
Qualquer provedor no agregador que esteja no banco de dados de PSA, mas não 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 de processar um feed incremental, as seguintes semânticas serão aplicadas:
Para qualquer provedor presente no feed, o sistema vai atualizar os dados dele no banco de dados de LSA se ele tiver sido criado em um feed de snapshot anterior. Por exemplo, se um provedor for encontrado pela primeira vez, ele será uma operação nula.
Para qualquer provedor presente no banco de dados de LSA, mas ausente no feed, isso não faz nada (ou seja, não haverá mudança para esse provedor).
A semântica do feed de perfil e de avaliações é um pouco diferente. Consulte a semântica de feed individual para detalhes do processamento.
Feeds de perfil: * Feeds de instantâneo baseados em pull * Feeds de instantâneo baseados em push * Feeds de atualização baseados em push Feeds de avaliações: * Feeds de instantâneo baseados em pull * Feeds de instantâneo baseados em push
São necessários feeds de perfil separados para:
Provedores considerados qualificados para o selo da Garantia do Google ou Avaliado pelo Google.
Provedores que não se qualificam para o selo.
Exemplos
Feeds de snapshots
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 na LSA, o feed de snapshot precisará conter o estado mais recente de todos os 100 provedores.
Como funciona
Confira abaixo um exemplo simples de como funciona a categoria de snapshot dos feeds de perfil.
- Snapshot 1 tem Pro 1 e Pro 2
- O Snapshot 2 tem Pro 1 e Pro 3
Depois de processar o Snapshot 1, o banco de dados da LSA terá Pro 1 e Pro 2. Durante o processamento do Snapshot 2, a LSA vai atualizar o Pro 1, criar o Pro 3 e excluir o Pro 2. Ou seja, depois do processamento do Snapshot 2, o banco de dados da LSA terá Pro 1 e 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 5 dos 100 provedores fornecidos anteriormente, o feed de atualização precisará conter apenas o estado mais recente desses 5 provedores.
Como funciona
Confira abaixo um exemplo simples de como funciona a categoria de atualização dos 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 da LSA terá Pro 1 e Pro 2. Durante o processamento da Atualização 2, a LSA vai atualizar o Pro 1 e criar o Pro 3. O Pro 2 não foi alterado. Ou seja, após o processamento da Atualização 2, o banco de dados da LSA terá Pro1, Pro2 e Pro 3.
Implicações de snapshot e extração
O mecanismo de feeds de snapshots + extração implica as seguintes restrições:
- Pode haver um atraso de algumas horas para que os parceiros adicionem ou excluam provedores, atualizem informações de perfil, pausem anúncios ou mudem orçamentos. O atraso está diretamente relacionado à frequência das solicitações de envio.
- Para atualizações de dados urgentes, talvez seja necessário oferecer suporte manual a uma solicitação única/ad hoc.
Implicações do suporte incremental e por push
Abrir o mecanismo atualizar feeds + push implica as seguintes melhorias:
- Os parceiros podem enviar o feed de instantâneos por push ou pull. Os parceiros que preferem não manter o endpoint (para extração) podem usar o push para reduzir o custo de manutenção do endpoint. Os parceiros que já oferecem suporte a feeds de snapshots por solicitação podem continuar fazendo isso.
- Os parceiros podem usar incrementais para atualizar apenas um subconjunto de provedores com mudanças de perfil. Isso melhora a atualização dos dados do perfil.
- Para saber como escolher entre snapshots e incrementais, push e pull, consulte esta seção para ver a abordagem de integração recomendada.
Abordagem de integração recomendada
Os parceiros precisam ter feeds de snapshots periódicos, seja por push ou pull. Isso permite que a LSA lide com emergências, como rollbacks e recuperação do sistema, em caso de atualizações perdidas.
- Com o mecanismo de push, os parceiros precisam enviar feeds de perfil de snapshot a cada 2 horas e revisar os feeds a cada 6 horas para garantir a atualização dos dados de base.
- Com o mecanismo de extração, a LSA extrai feeds de perfil de snapshot a cada duas horas e revisa os feeds a cada seis horas para garantir a atualização dos dados de base.
- Os parceiros precisam de apenas um dos mecanismos (push ou pull), mas não os dois, para entregar feeds de snapshots.
Opcionalmente, os parceiros que quiserem melhorar a atualização dos dados podem enviar feeds de atualização por push. A LSA não vai extrair feeds de atualização.
- Os feeds de atualização são usados para propagar itens alterados desde o último snapshot sem esperar pelo próximo.
- A LSA recomenda que os provedores tenham um intervalo de mais de 5 minutos entre dois pushes.
- Recomendamos agrupar os feeditems de maneira razoável em um feed de atualização. Para atualizar cinco provedores, a LSA prefere que eles enviem um feed de atualização com cinco feeditems em vez de cinco feeds de atualização com um feeditem em cada.
- Os anúncios locais por pesquisa só aceitam feeds incrementais para feeds de perfil, não para feeds de avaliações.
A LSA vai respeitar o campo feedTimestampMicros nos metadados para garantir a consistência dos dados. Um item de feed com um carimbo de data/hora mais antigo será ignorado para evitar
introduzir obsolescência se um item mais recente que atualiza a mesma propriedade tiver sido
ingerido. É responsabilidade do parceiro refletir a atualização de dados corretamente
usando feedTimestampMicros nos feeds de snapshot e de atualização.
Os parceiros precisam usar a API Reporting para receber informações sobre leads e cobranças por provedor.