Como usar o REST para chamar a API

Este documento descreve como usar a API JSON da Pesquisa personalizada do Google.

Como realizar uma solicitação

REST, ou transferência de estado representacional, na API JSON da Pesquisa personalizada é um pouco diferente do REST tradicional. Em vez de fornecer acesso a recursos, a API fornece acesso a um serviço. Dessa forma, a API fornece um URI que atua como extremidade do serviço.

Você pode recuperar resultados de uma pesquisa específica enviando um GET HTTP solicitação ao URI. Você transmite os detalhes da solicitação de pesquisa como parâmetros de consulta. O formato do URI da API Custom Search JSON é:

https://www.googleapis.com/customsearch/v1?[parameters]

Três consultas [parameters] são necessárias para cada solicitação de pesquisa:

  • Chave de API: use o parâmetro de consulta key para identificar o aplicativo.

  • ID do Mecanismo de Pesquisa Programável: use cx para especificar o o Mecanismo de Pesquisa Programável que você quer usar para essa pesquisa. O mecanismo de pesquisa precisa ser criado com o painel de controle. Observação: o ID do mecanismo de pesquisa (cx) pode ter um formato diferente (por exemplo, 8ac1ab64606d234f1)

  • Consulta de pesquisa: use o parâmetro de consulta q para especificar sua expressão de pesquisa.

Todos os outros parâmetros de consulta são opcionais.

Veja um exemplo de uma solicitação que pesquisa um testar o Mecanismo de Pesquisa Programável para palestras:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Parâmetros de consulta

Há dois tipos de parâmetros que você pode transmitir na solicitação:

  • Parâmetros específicos da API - defina as propriedades da sua pesquisa, como a expressão de pesquisa, o número de resultados, o idioma etc.
  • Parâmetros de consulta padrão - define aspectos técnicos da sua solicitação, como os Chave de API.

Todos os valores de parâmetros precisam ser codificados no URL.

Parâmetros de consulta específicos da API

Parâmetros de solicitação que se aplicam especificamente à API JSON da Pesquisa personalizada e definem solicitação de pesquisa são resumidos referência.

Parâmetros de consulta padrão

Os parâmetros de consulta que se aplicam a todas as operações da API JSON da Pesquisa personalizada do Google estão documentados em Parâmetros do sistema.

Dados de resposta

Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK. e os dados de resposta no formato JSON. É possível pesquisar os dados de resposta na referência.

Os dados de resposta são um objeto JSON que inclui três tipos de propriedades:

  • Metadados que descrevem a pesquisa solicitada (e possivelmente solicitações de pesquisas relacionadas)
  • Metadados que descrevem o Mecanismo de Pesquisa Programável
  • Resultados da pesquisa

Para uma descrição detalhada de cada propriedade, consulte a referência.

Pesquisar metadados da solicitação

Os metadados de pesquisa incluem:

  • url, que tem informações sobre o modelo do OpenSearch usado para os resultados retornados nessa solicitação.
  • queries, que é uma matriz de objetos que descrevem as características de possíveis pesquisas. O nome de cada na matriz é o nome de um Papel de consulta do OpenSearch ou um dos dois papéis personalizados definidos por esta API: previousPage e nextPage. Possíveis objetos de função da consulta incluem:
    • request: metadados que descrevem a consulta do conjunto atual de resultados.
      • Esta função está sempre presente na resposta.
      • Está sempre na matriz com apenas um elemento.
      • nextPage: metadados que descrevem a consulta a ser usada na próxima página de resultados.
        • Esta função não está presente na última página de resultados. Observação : essa API retorna apenas os 100 primeiros resultados.
        • Quando presente, é sempre uma matriz com apenas um elemento.
    • previousPage: metadados que descrevem a consulta a ser usada para o página de resultados anterior.
      • Não está presente na primeira página de resultados.
      • Quando presente, é sempre uma matriz com apenas um elemento.

Metadados do mecanismo de pesquisa

A propriedade context tem metadados que descrevem o mecanismo de pesquisa que realizou a consulta de pesquisa. inclui o nome do mecanismo de pesquisa e todos os objetos de atributo fornecidos para refinando uma pesquisa.

Resultados da pesquisa

A matriz items contém os resultados reais da pesquisa. A pesquisa resultados incluem o URL, título e snippets de texto que descrevem o resultado. Em Além disso, eles podem conter rich snippet se aplicável.

Se os resultados da pesquisa incluem uma propriedade promotions, ela contém um conjunto de promoções.

REST a partir de JavaScript

Você pode invocar a API JSON da Pesquisa personalizada do Google usando REST a partir de JavaScript, usando a parâmetro de consulta callback e uma função de callback. Isso permite que você para criar aplicativos avançados que mostram dados do Mecanismo de Pesquisa Programável sem gravar no código do lado do servidor.

O exemplo a seguir usa essa abordagem para mostrar a primeira página da pesquisa resultados para a consulta cars:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // Make sure HTML in item.htmlTitle is escaped.
        document.getElementById("content").append(
          document.createElement("br"),
          document.createTextNode(item.htmlTitle)
        );
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>