Como usar a API Indexing

Visão geral

Use a API Indexing para solicitar ao Google que atualize ou remova páginas 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. No momento, a API Indexing só pode ser usada para rastrear páginas com JobPosting ou BroadcastEvent incorporado a um VideoObject.

Ao enviar uma solicitação à API Indexing, defina o local de uma página da Web autônoma 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:

Atualizar um URL 

Send the following HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish endpoint
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_UPDATED"
}
Remover um URL 

Send the following HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish endpoint
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
Receber status da notificação 

Send a HTTP GET request to https://indexing.googleapis.com/v3/urlNotifications/metadata endpoint

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.

Diretrizes

As diretrizes a seguir se aplicam às solicitações de atualização e remoção de URL.

  • 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.
  • O corpo da solicitação nesses exemplos é o valor da variável content usada nos exemplos de token de acesso.

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 POST para o seguinte endpoint: 
    Send a HTTP POST request to 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. Pode ser necessário mais cota do que o padrão. Para visualizar sua cota atual e solicitar mais cota, consulte 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 removê-la do nosso índice e para que não haja uma nova tentativa de rastreá-la. Antes de solicitar a remoção, o URL precisa retornar um código de status 404 ou 410 ou a página ter a tag <meta name="robots" content="noindex" /> meta.

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

  1. Envie uma solicitação POST para o seguinte endpoint: 
    Send a HTTP POST request to 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. Pode ser necessário mais cota do que o padrão. Para visualizar sua cota atual e solicitar mais cota, consulte 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 ver o status de uma notificação, siga as etapas abaixo:

  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. 
    Send a HTTP GET request to https://indexing.googleapis.com/v3/urlNotifications/metadata?url=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. Pode ser necessário mais cota do que o padrão. Para visualizar sua cota atual e solicitar mais cota, consulte 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 a funcionalidade de 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.