使用 REST 叫用 API

本文說明如何使用 Custom Search JSON API。

提出要求

Custom Search JSON API 中的 REST (或稱「具象狀態傳輸」) 與一般 RESTful API 有些不同。API 提供服務存取權，而非資源存取權。因此，API 會提供單一 URI，做為服務端點。

您可以將 HTTP GET 要求傳送至 URI，擷取特定搜尋結果。您可以將搜尋要求的詳細資料做為查詢參數傳入。Custom Search JSON API URI 的格式如下：

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

每項搜尋要求都需要三個查詢 [parameters]：

  • API 金鑰：使用 key 查詢參數識別應用程式。

    • 程式化搜尋引擎 ID：使用 cx 指定要用來執行這項搜尋的程式化搜尋引擎。搜尋引擎必須使用控制台建立。注意：搜尋引擎 ID (cx) 可以採用不同的格式 (例如 8ac1ab64606d234f1)

  • 搜尋查詢：使用 q 查詢參數指定搜尋運算式。

所有其他查詢參數皆為選用項目。

以下是搜尋測試版程式化搜尋引擎的講座的範例要求：

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

查詢參數

您可以在要求中傳遞兩種類型的參數：

  • API 專屬參數：定義搜尋的屬性，例如搜尋運算式、結果數量、語言等。
  • 標準查詢參數：定義要求的技術層面，例如 API 金鑰。

所有參數值都必須經過網址編碼。

API 專屬查詢參數

參考資料中列出專門適用於 Custom Search JSON API 並定義搜尋要求的參數。

標準查詢參數

適用於所有 Custom Search JSON API 作業的查詢參數，請參閱「系統參數」一文。

回應資料

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼，以及 JSON 格式的回應資料。您可以在參考資料中查詢回應資料結構。

回應資料是 JSON 物件，其中包含三種類型的屬性：

  • 描述要求搜尋 (以及可能的相關搜尋要求) 的中繼資料
  • 描述程式化搜尋引擎的中繼資料
  • 搜尋結果

如需各個屬性的詳細說明，請參閱參考資料。

搜尋要求中繼資料

搜尋中繼資料包括：

  • url 屬性，其中包含此要求中所傳回結果所使用的 OpenSearch 範本相關資訊。
  • queries 屬性，這是描述可能搜尋項目特性的物件陣列。陣列中的每個物件名稱，可能是 OpenSearch 查詢角色的名稱，或是此 API 定義的兩個自訂角色之一：previousPage 和 nextPage。可能的查詢角色物件包括：
    • request：描述目前結果集查詢的中繼資料。
    • 這個角色一律會出現在回應中。
      • 一律為只有一個元素的陣列。
      • nextPage：描述要用於下一頁搜尋結果的查詢的中繼資料。
        • 如果目前的結果是最後一頁，就不會顯示這個角色。注意： 這個 API 最多只會傳回前 100 個結果。
        • 如果存在，則一律為只有一個元素的陣列。
    • previousPage：描述要用於前一個結果頁面的查詢的中繼資料。
      • 如果目前的結果是第一頁，則不會顯示。
      • 如有此屬性，則一律為只有一個元素的陣列。

搜尋引擎中繼資料

context 屬性含有中繼資料，可說明執行搜尋查詢的搜尋引擎。其中包含搜尋引擎名稱，以及用於精細搜尋的任何切面物件。

搜尋結果

items 陣列包含實際的搜尋結果。搜尋結果會包含描述結果的網址、標題和文字片段。此外，視情況還可包含資訊卡資訊。

如果搜尋結果包含 promotions 資源，則會包含一組促銷活動。

使用 JavaScript 的 REST

您可以使用 callback 查詢參數和回呼函式，透過 JavaScript 使用 REST 呼叫 Custom Search JSON API。這樣一來，您就能編寫可顯示程式化搜尋引擎資料的豐富應用程式，而無須編寫任何伺服器端程式碼。

以下範例使用這種方法，顯示查詢「lecture」的第一頁搜尋結果：

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; 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=lecture&callback=hndlr">
    </script>
  </body>
</html>