このページは Cloud Translation API によって翻訳されました。

REST を使用して API を呼び出す

このドキュメントでは、Custom Search JSON API の使用方法について説明します。

リクエストを作成する

Custom Search JSON API の REST（Representational State Transfer）は、通常の RESTful API とは若干異なります。API は、リソースへのアクセス権ではなく、サービスへのアクセス権を提供します。その結果、API はサービスエンドポイントとして機能する単一の URI を提供します。

特定の検索の結果を取得するには、その URI に HTTP GET リクエストを送信します。検索リクエストの詳細は、クエリパラメータとして渡します。Custom Search JSON API URI の形式は次のとおりです。

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

各検索リクエストで、次の 3 つのクエリ [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

クエリパラメータ

リクエストで渡すパラメータには次の 2 種類があります。

API 固有のパラメータ - 検索式、検索結果の表示件数、言語などの検索プロパティを定義します。
標準のクエリパラメータ - API キーなど、リクエストの技術的な側面を定義します。

パラメータの値はすべて URL エンコードする必要があります。

API 固有のクエリパラメータ

Custom Search JSON API に固有で、検索リクエストを定義するリクエストパラメータの概要については、リファレンスをご覧ください。

標準のクエリパラメータ

すべての Custom Search JSON API オペレーションに適用されるクエリパラメータは、システムパラメータに記載されています。

Response data

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードと JSON 形式のレスポンスデータを返します。レスポンスデータ構造については、リファレンスをご覧ください。

レスポンスデータは、次の 3 種類のプロパティを含む JSON オブジェクトです。

リクエストされた検索（および関連する検索リクエスト）を記述するメタデータ
プログラム可能検索エンジンを記述するメタデータ
検索結果

各プロパティの詳細な説明については、リファレンスをご覧ください。

検索リクエストのメタデータ

検索メタデータには次のものが含まれます。

url プロパティ。このリクエストで返される結果に使用される OpenSearch テンプレートに関する情報があります。
queries プロパティ。検索の候補の特性を表すオブジェクトの配列です。配列内の各オブジェクトの名前は、OpenSearch クエリロールの名前、またはこの API で定義された 2 つのカスタムロール（previousPage と nextPage）のいずれかです。使用できるクエリロールオブジェクトには次のようなものがあります。
- request: 現在の結果セットのクエリを記述するメタデータ。
- このロールはレスポンスに常に存在します。
  - 常に 1 つの要素のみを含む配列です。
  - nextPage: 次のページの結果に使用するクエリを記述するメタデータ。
    - 現在の結果が最後のページの場合、このロールは存在しません。注: この API は、最初の 100 件の結果のみを返します。
    - 存在する場合は、常に 1 つの要素を持つ配列です。
- previousPage: 結果の前のページに使用するクエリを記述するメタデータ。
  - 現在の結果が最初のページの場合は表示されません。
  - 指定されている場合、常に 1 つの要素のみを含む配列です。

検索エンジンのメタデータ

context プロパティには、検索クエリを実行した検索エンジンを記述するメタデータが含まれています。これには、検索エンジンの名前と、検索の絞り込み用に提供されるファセットオブジェクトが含まれます。

検索結果

items 配列には、実際の検索結果が含まれます。検索結果には、結果を説明する URL、タイトル、テキストスニペットが含まれます。また、該当する場合はリッチスニペット情報を含めることができます。

検索結果に 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>