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 utilizada para rastrear páginas com dados estruturados de vaga de emprego ou transmissão ao vivo.

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 as ações que você pode executar com a API Indexing:

Atualizar um URL
POST https://indexing.googleapis.com/v3/urlNotifications:publish
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_UPDATED"
}
Remover um URL
POST https://indexing.googleapis.com/v3/urlNotifications:publish
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
Receber status da notificação
GET 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.

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 de 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 ponto de extremidade:
    POST 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 dos seus servidores, notifique o Google para que possamos removê-la do nosso índice e para que não haja uma nova tentativa de rastrear o URL. Antes de solicitar a remoção, você precisa remover a página do seu servidor e o URL tem que retornar um código de status 404 ou 410.

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

  1. Envie uma solicitação POST para o seguinte ponto de extremidade:
    POST 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 ponto de extremidade a seguir. Os URLs especificados precisam ter codificação de URL. Por exemplo, substitua : (dois-pontos) por %3A e / (barras) por %2F.
    GET 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 seu 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 ponto de extremidade:

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, consulte Como enviar solicitações em lote (em inglês).

Enviar comentários sobre…