Como usar a API Indexing

Use a API Indexing para solicitar ao Google que atualize ou remova páginas de eventos de transmissão ao vivo ou de anúncios de emprego do índice do Google. As solicitações precisam especificar o local de uma página da Web. É possível também ver o status das notificações que você enviou ao Google. A API Indexing só pode ser usada para rastrear páginas com JobPosting ou BroadcastEvent incorporado em um VideoObject.

Diretrizes

As diretrizes a seguir se aplicam ao uso da API Indexing.

  • Nossas políticas de spam se aplicam ao conteúdo enviado com a API Indexing.
  • Todas as chamadas para https://indexing.googleapis.com/v3/UrlNotifications:publish precisam usar "application/json" como o cabeçalho Content-Type.
  • Você pode enviar somente um URL no corpo de uma solicitação de atualização ou combinar até cem solicitações em um lote, conforme descrito em Enviar solicitações de indexação em lote. Não burle nossos limites de envio, por exemplo, usando várias contas.
  • O corpo da solicitação nesses exemplos é o valor da variável content usada nos exemplos de token de acesso.

O que você pode fazer com a API

Ao enviar uma solicitação à API Indexing, defina o local de uma página da Web independente para notificar o Google de que é possível rastrear ou remover essa página do índice.

Os exemplos a seguir mostram o que você pode fazer com a API Indexing:

Exemplos
Atualizar um URL

Envie a seguinte solicitação HTTP POST para o endpoint https://indexing.googleapis.com/v3/urlNotifications:publish. Exemplo:

{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_UPDATED"
}
Remover um URL

Envie a seguinte solicitação HTTP POST para o endpoint https://indexing.googleapis.com/v3/urlNotifications:publish. Exemplo:

{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
Receber status da notificação

Envie uma solicitação HTTP GET para o endpoint https://indexing.googleapis.com/v3/urlNotifications/metadata.

Parâmetros

A tabela a seguir descreve os campos necessários para todos os métodos (atualizar e remover um URL):

Campos
url

Obrigatório

É o local totalmente qualificado do item que você quer atualizar ou remover.
type

Obrigatório

É o tipo da notificação que você enviou.

Atualizar um URL

Para notificar o Google sobre um novo URL a ser rastreado ou sobre a atualização de um URL previamente enviado, siga as etapas abaixo:

  1. Envie uma solicitação HTTP POST para o seguinte endpoint: 
    https://indexing.googleapis.com/v3/urlNotifications:publish
  2. No corpo da solicitação, especifique o local da página usando esta sintaxe: 
    {
  "url": "CONTENT_LOCATION",
  "type": "URL_UPDATED"
}
  3. O Google responde a chamadas bem-sucedidas da API Indexing com uma HTTP 200. Uma resposta HTTP 200 significa que poderá haver uma nova tentativa do Google de rastrear esse URL em breve. O corpo da resposta contém um objeto UrlNotificationMetadata, com campos que correspondem àqueles retornados por uma solicitação de status da notificação.
  4. Se você não receber uma resposta HTTP 200, consulte os erros específicos da API Indexing.
  5. Se o conteúdo da página mudar, envie outra notificação de atualização para acionar um novo rastreamento da página pelo Google.
  6. A API Indexing oferece uma cota padrão para testes. Para usar a API, solicite aprovação e cota.

Remover um URL

Depois de excluir uma página de seus servidores ou adicionar a tag <meta name="robots" content="noindex" /> na seção <head> de uma determinada página, notifique o Google para que possamos remover do nosso índice e para que não haja uma nova tentativa de rastreamento. Antes de solicitar a remoção, o URL precisa retornar um código de status 404 ou 410 ou a página precisa conter a tag <meta name="robots" content="noindex" /> meta.

Para solicitar a remoção do nosso índice, siga estas etapas:

  1. Envie uma solicitação POST para o seguinte endpoint: 
    https://indexing.googleapis.com/v3/urlNotifications:publish
  2. Especifique o URL que você quer remover no corpo da solicitação usando esta sintaxe: 
    {
  "url": "CONTENT_LOCATION",
  "type": "URL_DELETED"
}

    Exemplo:

    {
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
  3. O Google responde a chamadas bem-sucedidas da API Indexing com uma HTTP 200. Uma resposta HTTP 200 significa que pode haver remoção desse URL do índice pelo Google. O corpo da resposta contém um objeto UrlNotificationMetadata, com campos que correspondem àqueles retornados por uma solicitação de status da notificação.
  4. Se você não receber uma resposta HTTP 200, consulte os erros específicos da API Indexing.
  5. A API Indexing oferece uma cota padrão para testes. Para usar a API, solicite aprovação e cota.

Receber status da notificação

Você pode usar a API Indexing para verificar a última vez que o Google recebeu cada tipo de notificação relacionada a determinado URL. A solicitação GET não informa quando o Google indexa ou remove um URL. Ela só comunica se a solicitação foi enviada.

Para conferir o status de uma notificação, siga estas etapas:

  1. Envie uma solicitação GET para o endpoint a seguir. Os URLs especificados precisam ter codificação de URL. Por exemplo, substitua : (dois pontos) por %3A e / (barras) por %2F. 
    https://indexing.googleapis.com/v3/urlNotifications/metadata?url=ENCODED_URL

    Exemplo:

    GET https://indexing.googleapis.com/v3/urlNotifications/metadata?url=https%3A%2F%2Fcareers.google.com%2Fjobs%2Fgoogle%2Ftechnical-writer
  2. A API Indexing responde com uma mensagem HTTP 200 com um payload que contém detalhes sobre a notificação. O exemplo a seguir mostra o corpo de uma resposta que contém informações sobre uma notificação de atualização e exclusão: 
    {
  url: "http://foo.com",
  latest_update: {
    type: "URL_UPDATED",
    notify_time: "2017-07-31T19:30:54.524457662Z"
  },
  latest_remove: {
    type: "URL_DELETED",
    notify_time: "2017-08-31T19:30:54.524457662Z"
  }
}
  3. Se você não receber uma resposta HTTP 200, consulte os erros específicos da API Indexing.
  4. A API Indexing oferece uma cota padrão para testes. Para usar a API, solicite aprovação e cota.

Enviar solicitações de indexação em lote

Para reduzir o número de conexões HTTP que o cliente precisa fazer, você pode combinar até cem chamadas para a API Indexing em uma única solicitação HTTP. Use uma solicitação de várias partes, chamada lote, para fazer isso.

Para enviar uma solicitação em lote à API Indexing, use o seguinte endpoint:

https://indexing.googleapis.com/batch

O corpo de uma solicitação em lote contém várias partes. Cada parte é uma solicitação HTTP completa, com seu próprio verbo, URL, cabeçalhos e corpo. Cada parte dentro de uma solicitação em lote não pode ter mais de 1 MB.

Para facilitar o envio de solicitações em lote, as bibliotecas de cliente de APIs do Google são compatíveis com lotes. Para ver mais informações sobre lotes com as bibliotecas de cliente, consulte as seguintes páginas específicas das linguagens:

Se você usar os exemplos de lotes nessas páginas, talvez seja necessário atualizar seu código para refletir os requisitos de implementação descritos em Receber um token de acesso.

O exemplo a seguir de corpo de mensagem de solicitação em lote inclui uma notificação de atualização e uma de remoção:

POST /batch HTTP/1.1
Host: indexing.googleapis.com
Content-Length: content_length
Content-Type: multipart/mixed; boundary="===============7330845974216740156=="
Authorization: Bearer oauth2_token

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+2>

POST /v3/urlNotifications:publish [1]
Content-Type: application/json
accept: application/json
content-length: 58

{ "url": "http://example.com/jobs/42", "type": "URL_UPDATED" }
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1>

POST /v3/urlNotifications:publish [2]
Content-Type: application/json
accept: application/json
content-length: 75

{ "url": "http://example.com/widgets/1", "type": "URL_UPDATED" }
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+3>

POST /v3/urlNotifications:publish [3]
Content-Type: application/json
accept: application/json
content-length: 58

{ "url": "http://example.com/jobs/43", "type": "URL_DELETED" }
--===============7330845974216740156==

Para saber mais, veja como enviar solicitações em lote.