Utilizzo di REST per richiamare l'API

Questo documento descrive come utilizzare l'API JSON Ricerca personalizzata.

Invio di una richiesta

REST o Representational State Transfer, nell'API JSON Custom Search è in qualche modo diverso dal tradizionale REST. Anziché fornire l'accesso alle risorse, l'API fornisce l'accesso a un servizio. Di conseguenza, l'API fornisce un singolo URI che funge da endpoint di servizio.

Puoi recuperare i risultati per una determinata ricerca inviando un'istruzione HTTP GET al suo URI. I dettagli della richiesta di ricerca vengono trasmessi come parametri di ricerca. Il formato dell'URI dell'API JSON di Ricerca personalizzata è:

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

Per ogni richiesta di ricerca sono necessarie tre query [parameters]:

  • Chiave API. Utilizza il parametro di query key per identificare la tua applicazione.

  • ID Motore di ricerca programmabile: utilizza cx per specificare il Motore di ricerca programmabile che vuoi utilizzare per eseguire questa ricerca. Il motore di ricerca deve essere creato con il pannello di controllo Nota: l'ID del motore di ricerca (cx) può essere in un formato diverso (ad es. 8ac1ab64606d234f1)

  • Query di ricerca: utilizza il parametro di query q per specificare l'espressione di ricerca.

Tutti gli altri parametri di query sono facoltativi.

Ecco un esempio di richiesta che cerca un Testa Motore di ricerca programmabile per lezioni:

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

Parametri di query

Nella richiesta puoi trasferire due tipi di parametri:

  • Parametri specifici delle API: definisci le proprietà della ricerca, ad esempio l'espressione di ricerca, il numero di risultati, la lingua ecc.
  • Parametri di ricerca standard: definisci gli aspetti tecnici della richiesta, come chiave API.

Tutti i valori dei parametri devono essere codificati nell'URL.

Parametri di query specifici dell'API

Richiedi i parametri che si applicano specificamente all'API JSON Ricerca personalizzata e definisci il tuo richieste di ricerca sono riassunte nel riferimento.

Parametri di query standard

I parametri di query che si applicano a tutte le operazioni dell'API JSON Ricerca personalizzata sono documentati in Parametri di sistema.

Dati di risposta

Se la richiesta ha esito positivo, il server risponde con un codice di stato HTTP 200 OK e i dati di risposta in formato JSON. Puoi cercare i dati della risposta nel riferimento.

I dati di risposta sono un oggetto JSON che include tre tipi di proprietà:

  • Metadati che descrivono la ricerca richiesta (ed eventualmente le richieste di ricerca correlata)
  • Metadati che descrivono il Motore di ricerca programmabile
  • Risultati di ricerca

Per una descrizione dettagliata di ogni proprietà, consulta riferimento.

Cerca metadati della richiesta

I metadati della ricerca includono:

  • url, che ha informazioni sul modello OpenSearch utilizzato per i risultati restituiti in questa richiesta.
  • queries, che è un array di che descrivono le caratteristiche delle possibili ricerche. Il nome di ogni oggetto nell'array è o il nome di un Ruolo Query OpenSearch o uno dei due ruoli personalizzati definiti da questa API: previousPage e nextPage. Possibili oggetti ruolo query include:
    • request: metadati che descrivono la query per l'insieme attuale di che consentono di analizzare i dati e visualizzare i risultati.
      • Questo ruolo è sempre presente nella risposta.
      • È sempre un array con un solo elemento.
      • nextPage: metadati che descrivono la query da utilizzare per la successiva pagina dei risultati.
        • Questo ruolo non è presente se i risultati correnti sono l'ultima pagina. Nota : questa API restituisce solo i primi 100 risultati.
        • Se presente, è sempre un array con un solo elemento.
    • previousPage: metadati che descrivono la query da utilizzare per l'elemento pagina dei risultati precedente.
      • Non presente se i risultati correnti sono la prima pagina.
      • Se presente, è sempre un array con un solo elemento.

Metadati del motore di ricerca

La proprietà context include metadati che descrivono il motore di ricerca che ha eseguito la query di ricerca. Include il nome del motore di ricerca e qualsiasi oggetto facet fornito perfezionare una ricerca.

Risultati di ricerca

L'array items contiene i risultati di ricerca effettivi. La ricerca includono l'URL, il titolo e gli snippet di testo che descrivono il risultato. Nella Inoltre, possono contenere rich snippet informazioni, se applicabile.

Se i risultati di ricerca includono una proprietà promotions, questa contiene un insieme di promozioni.

REST da JavaScript

Puoi richiamare l'API JSON Custom Search utilizzando REST da JavaScript, utilizzando callback e una funzione di callback. Questo consente di scrivere applicazioni avanzate che mostrino dati del Motore di ricerca programmabile senza scrivere nulla il codice lato server.

L'esempio seguente utilizza questo approccio per visualizzare la prima pagina di ricerca risultati per la query 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>