本頁面由 Cloud Translation API 翻譯而成。

使用 REST 叫用 API

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

提出請求

REST 或 Representational State Transfer (具象狀態傳輸) 中的自訂搜尋 JSON API 與傳統的 REST 稍有不同。 API 會提供服務的存取權，而不是提供資源的存取權。因此，該 API 提供了單一的 URI，用來當做服務端點。

您可以傳送 HTTP GET 來擷取特定搜尋的結果要求。您要將搜尋要求的詳細資料傳入為查詢參數。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 的要求參數，並定義您的請參閱 reference：

標準查詢參數

如需適用於所有 Custom Search JSON API 作業的查詢參數，請參閱系統參數：

回應資料

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

回應資料是一個 JSON 物件，其中包含三種屬性：

說明要求搜尋 (及可能相關搜尋要求) 的中繼資料
說明程式化搜尋引擎的中繼資料
搜尋結果

如需每個屬性的詳細說明，請參閱 reference：

搜尋要求中繼資料

搜尋中繼資料包括：

url 屬性，當中 OpenSearch 範本的相關資訊。
queries 屬性，也就是物件，說明可能搜尋的特性。每個 Pod 的名稱陣列中的物件是 OpenSearch 查詢角色或是此 API 定義的兩種自訂角色之一： previousPage和nextPage。可能的查詢角色物件包括：
- request：描述目前集合查詢的中繼資料也就是預測結果
  - 回應中一律會顯示這個角色。
  - 它一律是一個只包含一個元素的陣列。
  - nextPage：說明要用於下一個查詢作業的中繼資料的結果。
    - 如果目前的結果為最後一頁，就不會顯示這個角色。 注意： 這個 API 最多只傳回前 100 筆結果。
    - 如果存在，則一律為只包含一個元素的陣列。
- previousPage：描述要用於上一頁的結果
  - 如果目前的結果是第一頁，就不會顯示。
  - 如果存在，則一律為只包含一個元素的陣列。

搜尋引擎中繼資料

context 屬性具有說明搜尋引擎的中繼資料所執行搜尋查詢其中包含搜尋引擎的名稱；提供給 Pod 的任何facet 物件修正搜尋

搜尋結果

items 陣列包含實際搜尋結果。搜尋搜尋結果會包含描述該結果的網址、標題和文字片段。於而且可以包含複合式摘要相關資訊 (如適用)。

如果搜尋結果包含 promotions 屬性，表示該屬性包含一組促銷活動。

JavaScript 提供的 REST

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

以下範例會使用這個方法顯示第一頁的搜尋「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>