検索ウィジェットは、ウェブ アプリケーション用のカスタマイズ可能な検索インターフェースを提供します。 このウィジェットで必要なのは、少量の HTML と JavaScript だけです。 ファセットやページ分けなどの一般的な検索機能を実装して有効にします。CSS や JavaScript を使用してインターフェースの一部をカスタマイズすることもできます。
ウィジェットで提供される以上の柔軟性が必要な場合は、Query API の使用を検討してください。Query API を使用して検索インターフェースを作成する方法については、Query API を使用した検索インターフェースの作成をご覧ください。
検索インターフェースを作成する
検索インターフェースを作成するには、いくつかの手順が必要です。
- 検索アプリケーションを構成する
- アプリケーションのクライアント ID を生成する
- 検索ボックスと結果用の HTML マークアップを追加する
- ページにウィジェットを読み込む
- ウィジェットを初期化する
検索アプリケーションを構成する
各検索インターフェースには、管理コンソールで定義された検索アプリケーションが必要です。検索アプリケーションでは、その他の データソース、ファセット、クエリに関する情報が 検索品質の設定です
検索アプリケーションを作成するには、 カスタム検索エクスペリエンスを作成します。
アプリケーションのクライアント ID を生成する
この専門講座の Google Cloud Search API へのアクセスを構成する ウェブ アプリケーションのクライアント ID も生成する必要があります。
プロジェクトを構成するには:
- ウェブブラウザのクライアント タイプを選択します。
- アプリの生成元 URI を指定します。
- 作成されたクライアント ID をメモします。次の手順を完了するには、クライアント ID が必要です。ウィジェットにはクライアント シークレットは必要ありません。
詳細については、クライアント側ウェブ アプリケーションの OAuth 2.0 をご覧ください。
HTML マークアップを追加する
ウィジェットが機能するには、少量の HTML が必要です。次の情報を指定する必要があります。
- 検索ボックスの
input
要素。 - 候補ポップアップを固定するための要素。
- 検索結果を格納する要素。
- (省略可)ファセット コントロールを格納する要素を指定します。
次の HTML スニペットは、検索ウィジェットの HTML を示しています。
バインドされる要素は、id
属性で識別されます。
ウィジェットを読み込む
ウィジェットは、ローダー スクリプトを介して動的に読み込まれます。対象者
次のように <script>
タグを使用します。
スクリプトタグで onload
コールバックを指定する必要があります。この関数は、ローダーの準備ができると呼び出されます。ローダの準備ができたら、ウィジェットの読み込みを続けます。
gapi.load()
を呼び出して、API クライアント、Google ログイン、Cloud Search の各モジュールを読み込みます。
すべてのモジュールが更新された後に initializeApp()
関数が呼び出される
確認できます。
ウィジェットを初期化する
まず、以下の関数を呼び出してクライアント ライブラリを初期化します。
gapi.client.init()
または gapi.auth2.init()
は、生成されたクライアント ID に置き換えます
https://www.googleapis.com/auth/cloud_search.query
スコープの 2 つがあります。次に
gapi.cloudsearch.widget.resultscontainer.Builder
と
ウィジェットを構成する gapi.cloudsearch.widget.searchbox.Builder
クラス
HTML 要素にバインドします。
次の例は、ウィジェットを初期化する方法を示しています。
上記の例では、次のように定義された 2 つの変数を構成のために参照しています。
ログイン エクスペリエンスをカスタマイズする
デフォルトでは、ウィジェットはユーザーがクエリの入力を開始した際に、ログインしてアプリを承認するように求めます。ウェブサイト用の Google ログインを使用すると、ユーザーに合わせてカスタマイズしたログイン方式を提供できます。
ユーザーを直接承認する
Google でログインを使用して、
必要に応じてユーザーをログインまたはログアウトできます。たとえば、次のようになります。
この例では、isSignedIn
ログインの変更とモニタリングを
GoogleAuth.signIn()
を使用
方法を使用して、ボタンからログインを開始します。
次をクリックします。
詳しくは、Google でログインをご覧ください。
ユーザーを自動的にログインさせる
組織内のユーザーに代わってアプリケーションを事前に承認することで、ログイン方式をさらに簡素化できます。この手法は、Cloud Identity Aware Proxy を使用してアプリケーションを保護する場合にも役立ちます。
詳細については、IT アプリで Google ログインを使用するをご覧ください。
インターフェースをカスタマイズする
検索インターフェースの外観は、複数の手法を組み合わせて変更できます。
- CSS でスタイルをオーバーライドする
- 要素をアダプタで修飾する
- アダプタを使用してカスタム要素を作成する
CSS でスタイルをオーバーライドする
検索ウィジェットには、候補と結果の要素をスタイル設定する独自の CSS と、ページ分割のコントロールが用意されています。これらの要素は必要に応じてスタイルを変更できます。
読み込み中に、検索ウィジェットはデフォルトのスタイルシートを動的に読み込みます。 これはアプリケーションのスタイルシートが読み込まれた後に発生し、優先度が 構成されます。独自のスタイルをデフォルト スタイルよりも優先させるには、祖先セレクタを使用してデフォルト ルールの特異性を高めます。
たとえば、次のルールは、静的な
ドキュメント内の link
タグまたは style
タグ。
.cloudsearch_suggestion_container {
font-size: 14px;
}
代わりに、ページで宣言されている祖先コンテナの ID またはクラスでルールを修飾します。
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
サポートクラスのリストとウィジェットによって生成される HTML の例については、サポートされる CSS クラス リファレンスをご覧ください。
要素をアダプタで修飾する
レンダリングの前に要素を装飾するには、
などのデコレーション メソッドを実装するアダプターを
decorateSuggestionElement
または decorateSearchResultElement.
たとえば、次のアダプタは、候補要素と結果要素にカスタムクラスを追加します。
ウィジェットの初期化時にアダプターを登録するには、setAdapter()
を使用します。
それぞれの Builder
クラスのメソッドを使用します。
デコレータは、コンテナ要素といずれかの子要素の属性を変更できます。子要素は装飾中に追加または削除される場合があります。 ただし、要素に構造的な変更を加える場合は、 要素を直接デコレートするのではなく、
アダプタを使用してカスタム要素を作成する
候補、ファセット コンテナ、検索結果のカスタム要素を作成するには:
実装するアダプタを作成して登録する
createSuggestionElement
createFacetResultElement
、
または createSearchResultElement
表示されます。
次のアダプタは、カスタム候補と検索結果の作成を示しています。
HTML の <template>
タグを使用して要素を作成します。
ウィジェットの初期化時にアダプターを登録するには、setAdapter()
を使用します。
それぞれの Builder
クラスのメソッドを使用します。
createFacetResultElement
を使用してカスタム ファセット要素を作成する
次のようないくつかの制約があります。
- CSS クラス
cloudsearch_facet_bucket_clickable
を ユーザーがクリックするとバケットが切り替わります。 - 含まれる要素内の各バケットを CSS でラップする必要があります。
クラス
cloudsearch_facet_bucket_container
。 - バケットをレスポンスに表示される順序と異なる順序でレンダリングすることはできません。
たとえば、次のスニペットは、チェックボックスの代わりにリンクを使用してファセットをレンダリングします。
検索動作をカスタマイズする
検索アプリケーションの設定は、検索インターフェースのデフォルト構成を表し、静的です。ユーザーにデータソースの切り替えを許可するような動的なフィルタやファセットを実装する場合、アダプタで検索リクエストをインターセプトすることにより、検索アプリケーションの設定をオーバーライドできます。
次のようにしてアダプタを実装します。
interceptSearchRequest
メソッドを呼び出し、
Search API
確認できます。
たとえば、次のアダプタはリクエストをインターセプトして、クエリをユーザーが選択したソースに限定します。
ウィジェットの初期化時にアダプターを登録するには、
setAdapter()
メソッド(ResultsContainer
のビルド時)
次の HTML は、ソースでフィルタリングするために選択ボックスを表示する目的で使用されます。
次のコードは、変更をリッスンし、選択を設定し、必要に応じてクエリを再実行します。
次のようにして、検索レスポンスをインターセプトすることもできます。
interceptSearchResponse
渡します。
API バージョンを固定する
デフォルトでは、ウィジェットは最新の安定版 API を使用します。ロックインするには
特定のバージョンの場合は、cloudsearch.config/apiVersion
構成パラメータを設定します。
ウィジェットを初期化する前に、優先するバージョンに更新します。
API のバージョンは、省略するか無効な値を指定した場合、デフォルトの 1.0 になります。
ウィジェットのバージョンを固定する
検索インターフェースの予期しない変更を回避するには、
次に示すように、cloudsearch.config/clientVersion
構成パラメータを使用します。
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
ウィジェットのバージョンは、省略するか無効な値を指定した場合、デフォルトの 1.0 になります。
検索インターフェースを保護する
検索結果には非常に機密性の高い情報が含まれます。おすすめの方法に沿ってウェブ アプリケーションを(特にクリックジャッキング攻撃に対して)保護します。
詳細については、OWASP Guide Project をご覧ください。
デバッグを有効にする
interceptSearchRequest
を使用する
して、検索ウィジェットのデバッグを有効にします。例:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;