REST zum Aufrufen der API verwenden

In diesem Dokument wird die Verwendung der Custom Search JSON API beschrieben.

Anforderung senden

Representational State Transfer in der Custom Search JSON API unterscheidet sich etwas von der herkömmlichen REST. Anstatt Zugriff auf Ressourcen zu gewähren, bietet die API Zugriff auf einen Dienst. Daher stellt die API einen einzelnen URI bereit, der als Dienstendpunkt fungiert.

Sie können Ergebnisse für eine bestimmte Suche abrufen, indem Sie eine HTTP-GET-Anfrage senden -Anfrage an seinen URI. Sie geben die Details der Suchanfrage als Suchparametern. Das Format für den URI der Custom Search JSON API ist:

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

Für jede Suchanfrage sind drei Abfrage-[parameters] erforderlich:

  • API-Schlüssel: Verwenden Sie den Abfrageparameter key für Folgendes: Ihre Anwendung identifizieren.

  • Programmable Search Engine ID (Programmable Search Engine-ID): Verwenden Sie cx zur Angabe der Programmable Search Engine, die Sie für diese Suche verwenden möchten. Die Suchmaschine muss über das Steuerfeld erstellt werden. Hinweis: Die Suchmaschinen-ID (cx) kann ein anderes Format haben (z.B. 8ac1ab64606d234f1)

  • Suchanfrage: Verwenden Sie den Suchparameter q, um Ihren Suchausdruck anzugeben.

Alle anderen Abfrageparameter sind optional.

Hier ist ein Beispiel für eine Anfrage, bei der eine Sie können die Programmable Search Engine in Vorlesungen testen:

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

Abfrageparameter

Es gibt zwei Arten von Parametern, die Sie in Ihrer Anfrage übergeben können:

  • API-spezifische Parameter – definieren Sie die Eigenschaften Ihrer Suche, z. B. Suchausdruck, Anzahl der Ergebnisse, Sprache usw.
  • Standardabfrageparameter – definieren Sie die technischen Aspekte Ihrer Anfrage, z. B. die API-Schlüssel.

Alle Parameterwerte müssen URL-codiert sein.

API-spezifische Abfrageparameter

Fordern Sie Parameter an, die speziell für die Custom Search JSON API gelten, und definieren Ihre Suchanfragen werden in den reference beschrieben.

Standardabfrageparameter

Abfrageparameter, die für alle Vorgänge der Custom Search JSON API gelten, sind unter Systemparameter.

Antwortdaten

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und die Antwortdaten im JSON-Format. Sie können die Antwortdaten in der Referenz.

Die Antwortdaten sind ein JSON-Objekt, das drei Arten von Eigenschaften:

  • Metadaten, die die angefragte Suche beschreiben (und möglicherweise entsprechende Suchanfragen)
  • Metadaten zur Beschreibung der Programmable Search Engine
  • Suchergebnisse

Eine ausführliche Beschreibung der einzelnen Eigenschaften finden Sie in der reference beschrieben.

Metadaten der Suchanfrage

Die Metadaten der Suche enthalten Folgendes:

  • url-Property mit Informationen zur OpenSearch-Vorlage die für die in dieser Anfrage zurückgegebenen Ergebnisse verwendet werden.
  • Eigenschaft queries, die ein Array von -Objekte, die die Eigenschaften möglicher Suchvorgänge beschreiben. Die Namen der einzelnen im Array entweder der Name eines OpenSearch-Abfragerolle oder eine der beiden von dieser API definierten benutzerdefinierten Rollen: previousPage und nextPage. Mögliche Objekte der Abfragerolle umfassen: <ph type="x-smartling-placeholder">
      </ph>
    • request: Metadaten, die die Abfrage für den aktuellen Satz von beschreiben Ergebnisse.
      • Diese Rolle ist immer in der Antwort enthalten.
      • Es ist immer ein Array mit nur einem Element.
      • nextPage: Metadaten, die die Abfrage beschreiben, die für die nächste Seite mit Ergebnissen.
        • Diese Rolle ist nicht vorhanden, wenn die aktuellen Ergebnisse die letzte Seite sind. Hinweis : Diese API gibt nur maximal die ersten 100 Ergebnisse zurück.
        • Wenn er vorhanden ist, handelt es sich immer um ein Array mit nur einem Element.
    • previousPage: Metadaten, die die Abfrage beschreiben, die für den auf der vorherigen Ergebnisseite.
      • Nicht vorhanden, wenn die aktuellen Ergebnisse die erste Seite darstellen.
      • Wenn er vorhanden ist, handelt es sich immer um ein Array mit nur einem Element.

Metadaten der Suchmaschine

Das Attribut context enthält Metadaten, die die Suchmaschine beschreiben der die Suchanfrage ausgeführt hat. Sie enthält den Namen der Suchmaschine und Alle Facettenobjekte, die für die Verfeinern der Suche.

Suchergebnisse

Das Array items enthält die tatsächlichen Suchergebnisse. Die Suchanfrage -Ergebnisse enthalten die URL, den Titel und die Text-Snippets, die das Ergebnis beschreiben. In Außerdem können sie Rich Snippet-Erweiterungen enthalten, Informationen enthalten.

Wenn die Suchergebnisse eine promotions-Eigenschaft enthalten, enthält diese eine Reihe von Werbeaktionen.

REST aus JavaScript

Sie können die Custom Search JSON API mit REST aus JavaScript aufrufen, indem Sie die callback-Abfrageparameter und eine Callback-Funktion. So können Sie können Sie umfangreiche Anwendungen schreiben, die Daten von Programmable Search Engine anzeigen, ohne serverseitigen Code.

Im folgenden Beispiel wird dieser Ansatz verwendet, um die erste Seite der Suche anzuzeigen. der Abfrage 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>