プログラム可能検索エンジンのコンポーネント(検索ボックスと検索結果ページ)を ウェブページやその他のウェブ アプリケーションに HTML マークアップを適用できます。これらのプログラム可能検索エンジン 要素は、Google Cloud Storage バケットに保存された設定に基づいて 実行したカスタマイズに加え、プログラム可能な検索サーバーにもアクセスできます。
JavaScript はすべて非同期で読み込まれるため、ウェブページで次の処理が可能になります。 ブラウザがプログラム可能検索エンジンの JavaScript を取得している間、読み込みを続行します。
はじめに
このドキュメントでは、プログラム可能検索エンジンを追加するための基本モデルについて説明します。 要素の説明と、各要素の説明をウェブページに追加 構成可能なコンポーネントと柔軟な JavaScript API です。
範囲
このドキュメントでは、Terraform に固有の関数とプロパティを Programmable Search Engine Control API を使用します。
ブラウザの互換性
プログラム可能検索エンジンでサポートされているブラウザのリストは、 こちらをご覧ください。
視聴者
このドキュメントは、Google Programmable ページに検索機能を追加する。
プログラム可能検索の要素
HTML マークアップを使用して、プログラム可能検索要素をページに追加できます。各 要素は、少なくとも 1 つのコンポーネントで構成されます。具体的には、検索ボックス、検索ブロックです。 選択することもできます検索ボックスにユーザー入力として次のいずれかを入力できます。 方法:
- テキスト入力フィールドに入力された検索クエリ
- URL に埋め込まれたクエリ文字列
- プログラムによる実行
また、検索結果のブロックでは、 できます。
- URL に埋め込まれたクエリ文字列
- プログラムによる実行
以下のタイプのプログラム可能検索要素を使用できます。
要素の種類 | コンポーネント | 説明 |
---|---|---|
standard | <div class="gcse-search"> |
検索ボックスと検索結果
同じ <div> で表示されます。 |
2 列 | <div class="gcse-searchbox"> と <div class="gcse-searchresults"> |
片側に検索結果と検索ボックスがある 2 列のレイアウト
もう一方です複数の要素を 2 列モードで挿入する場合
では、gname 属性を使用して、
検索結果のブロックが表示されます。 |
検索ボックスのみ | <div class="gcse-searchbox-only"> |
独立した検索ボックス。 |
searchresults-only | <div class="gcse-searchresults-only"> |
独立した検索結果のブロック。 |
ウェブページには有効な検索要素をいくつでも追加できます。2 列の場合 すべての必須コンポーネント(検索ボックスと検索 結果ブロックなど)が存在する必要があります。
単純な検索要素の例を次に示します。
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
Programmable Search Elements を使用してさまざまなレイアウト オプションを作成する
プログラム可能検索エンジンのコントロール パネルの [外観] ページでは、以下のレイアウト オプションを使用できます。ここでは、プログラム可能な検索の要素を使用したレイアウト オプションの作成に関する一般的なガイドラインについて説明します。これらのオプションのデモを確認するには、リンクをクリックしてください。
オプション | コンポーネント |
---|---|
全幅 | <div class="gcse-search"> |
コンパクト | <div class="gcse-search"> |
2 列 | <div class="gcse-searchbox"> 、<div class="gcse-searchresults"> |
2 ページ
<ph type="x-smartling-placeholder">
|
最初のページには <div class="gcse-searchbox-only"> 、2 ページ目は <div class="gcse-searchresults-only"> (またはその他のコンポーネント)です。 |
結果のみ
<ph type="x-smartling-placeholder">
|
<div class="gcse-searchresults-only"> |
Google がホスト
<ph type="x-smartling-placeholder">
|
<div class="gcse-searchbox-only"> |
Programmable Search の要素のカスタマイズ
色、フォント、リンク スタイルをカスタマイズするには、プログラム可能な検索エンジンの [デザイン] ページに移動します。
オプションの属性を使用して、
プログラム可能検索エンジン
。これにより、ページ固有の検索機能を構築できます。
たとえば次のコードは、検索結果ページを開く検索ボックスを作成します。
(http://www.example.com?search=lady+gaga)を新しいウィンドウで表示。「
queryParameterName
属性とユーザーのクエリ文字列が
結果の URL を作成します。
queryParameterName
属性の先頭には data-
が付加されています。
この接頭辞はすべての属性で必須です。
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
プログラム可能検索エンジンのコントロール パネルを使用して、 予測入力や絞り込みなどで、属性を使用して カスタマイズが可能です。これらの属性を使用して指定したカスタマイズ コントロール パネルでの設定が上書きされます。次のサンプルでは、 次の機能を備えた 2 列の検索要素:
- 履歴管理が有効です
- 表示される予測入力の最大数は 5 に設定されています
- 絞り込みはリンクとして表示されます。
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
サポートされている属性
属性 | 型 | 説明 | コンポーネント |
---|---|---|---|
全般 | |||
gname |
文字列 | (省略可)検索要素オブジェクトの名前。名前は、名前を使用して、
関連するコンポーネントの名前を指定するか、searchbox
コンポーネントを searchresults コンポーネントに置き換えます。指定しない場合、
プログラム可能検索エンジンは、gname
ウェブページ上のコンポーネントの順序です。たとえば、最初の名前のない
searchbox-only には gname "searchbox-only0" が設定されています
2 つ目は gname "seachbox-only1" というように続きます。
コンポーネント用に自動生成された gname は、
2 列のレイアウトは two-column になります。次の例をご覧ください。
gname storesearch を使用して searchbox をリンクします。
次のサンプルを searchresults コンポーネントに置き換えます。
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> オブジェクトを取得するときに、複数のコンポーネントに同じ
|
すべて |
autoSearchOnLoad |
ブール値 | URL に埋め込まれたクエリによる検索を実行するかどうかを指定します
表示されます。クエリ文字列は URL に存在する必要があります
自動検索が実行されます。デフォルト: true 。 |
すべて |
enableHistory |
ブール値 | true の場合、ブラウザの「戻る」の履歴管理が有効になります。
[進む]ボタンがありますデモを見る |
検索ボックス 検索ボックスのみ |
queryParameterName |
文字列 | クエリ パラメータ名。例: q (デフォルト)
または query 。これは URL に埋め込まれます(例:
http://www.example.com?q=lady+gaga など)。なお、
クエリ パラメータ名だけでは、読み込み時に自動検索がトリガーされません。クエリ
自動検索を実行するには、URL に文字列が必要です。 |
すべて |
resultsUrl |
URL | 検索結果ページの URL。(デフォルトは Google がホストするページです)。 | 検索ボックスのみ |
newWindow |
ブール値 | 検索結果ページを新しいウィンドウで開くかどうかを指定します。
デフォルト: false 。 |
検索ボックスのみ |
ivt |
ブール値 |
このパラメータを使用すると、許可することを Google に伝えるブール値を指定できます。 無効なトラフィック検出専用の Cookie を使用する広告ローカル ストレージの ブロックします。
デフォルト: 使用例: |
検索結果 searchresults-only |
mobileLayout |
文字列 |
モバイル レイアウト スタイルをモバイル デバイスで使用するかどうかを指定します。
デフォルト: 使用例: |
すべて |
予測入力 | |||
enableAutoComplete |
ブール値 | プログラム可能検索エンジンのコントロール パネルで予測入力が有効になっている場合にのみ使用できます。
true は予測入力を有効にします。 |
すべて |
autoCompleteMaxCompletions |
Integer | 表示する予測入力の最大数。 | 検索ボックス 検索ボックスのみ |
autoCompleteMaxPromotions |
Integer | 予測入力に表示されるプロモーションの最大数。 | 検索ボックス 検索ボックスのみ |
autoCompleteValidLanguages |
文字列 | 予測入力の対象となる言語のカンマ区切りのリスト 有効にします。<ph type="x-smartling-placeholder"></ph> サポートされている言語。 | 検索ボックス 検索ボックスのみ |
絞り込み | |||
defaultToRefinement |
文字列 | 絞り込みが作成されている場合にのみ使用できます。 プログラム可能検索エンジンのコントロール パネル。デフォルトの絞り込みラベルを指定します。 display.注: この属性は、Google がホストするレイアウトではサポートされていません。 | すべて |
refinementStyle |
文字列 | 有効な値は tab (デフォルト)と link です。
link は、画像検索が無効になっている場合、または次の場合にのみサポートされます。
画像検索は有効になっていますが、ウェブ検索は無効になっています。 |
検索結果 searchresults-only |
画像検索 | |||
enableImageSearch |
ブール値 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
|
検索結果 searchresults-only |
defaultToImageSearch |
ブール値 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
|
すべて |
imageSearchLayout |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
画像検索結果ページのレイアウトを指定します。使用できる値
|
検索結果 searchresults-only |
imageSearchResultSetSize |
整数、文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
画像検索の結果セットの最大サイズを指定します。
例: |
すべて |
image_as_filetype |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
結果を指定した拡張子のファイルのみに制限します。 サポートされている拡張機能は | すべて |
image_as_oq |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
論理 OR を使用して検索結果をフィルタします。 「term1」のどちらかを含む検索結果を表示する場合の使用例または "term2": | すべて |
image_as_rights |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
ライセンスに基づくフィルタ。 サポートされている値は、 一般的な組み合わせをご覧ください。 | すべて |
image_as_sitesearch |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索結果を特定サイトのページに限定します。 使用例: | すべて |
image_colortype |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索をモノクロ(モノラル)、グレースケール、カラーの画像に限定します。サポートされる値は | すべて |
image_cr |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索結果を、特定の国で作成されたドキュメントに限定します。 | すべて |
image_dominantcolor |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索を特定のドミナント カラーの画像に制限します。
サポートされている値は | すべて |
image_filter |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索結果の自動フィルタリング。 サポートされている値: 0/1 使用例: | すべて |
image_gl |
文字列 | の場合のみ使用可能 画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。 検索元の国がパラメータ値と一致する検索結果を優先します。 | すべて |
image_size |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
指定されたサイズの画像を返します。サイズは、 | すべて |
image_sort_by |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
日付または他の構造化コンテンツを使用して結果を並べ替えます。 関連性で並べ替えるには、空の文字列(image_sort_by="")を使用します。 使用例: | すべて |
image_type |
文字列 | の場合のみ使用可能
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。
検索を特定タイプの画像に限定します。
サポートされている値は、 | すべて |
ウェブ検索 | |||
disableWebSearch |
ブール値 | true の場合、ウェブ検索を無効にします。通常、次の場合にのみ使用されます。
<ph type="x-smartling-placeholder"></ph>
画像検索がプログラム可能検索エンジンのコントロール パネルで有効になっていること。 |
検索結果 searchresults-only |
webSearchQueryAddition |
文字列 | 論理 OR を使用して検索クエリに余分な用語が追加されました。
使用例: |
すべて |
webSearchResultSetSize |
整数、文字列 | 結果セットの最大サイズ。対象
画像検索とウェブ検索の両方に対応しますデフォルトは、レイアウトと
プログラム可能検索エンジンがウェブ全体を検索するように設定されているか、特定のファイルのみを検索するように設定されているか
できます。指定できる値は次のとおりです。
<ph type="x-smartling-placeholder">
|
すべて |
webSearchSafesearch |
文字列 |
指定するかどうか
SafeSearch:
ウェブ検索の検索結果に対して
有効にする必要があります指定できる値は off と active です。
|
すべて |
as_filetype |
文字列 | 結果を指定した拡張子のファイルのみに制限します。Google がインデックス登録できるファイル形式の一覧については、Search Console のヘルプセンターをご覧ください。 | すべて |
as_oq |
文字列 | 論理 OR を使用して検索結果をフィルタします。
「term1」のどちらかを含む検索結果を表示する場合の使用例または "term2": |
すべて |
as_rights |
文字列 | ライセンスに基づくフィルタ。
サポートされている値は、 一般的な組み合わせについては、https://wiki.creativecommons.org/wiki/CC_Search_integration をご覧ください。 | すべて |
as_sitesearch |
文字列 | 検索結果を特定サイトのページに限定します。
使用例: |
すべて |
cr |
文字列 | 検索結果を、特定の国で作成されたドキュメントに限定します。
使用例: |
すべて |
filter |
文字列 | 検索結果の自動フィルタリング。
サポートされている値: 0/1 使用例: |
すべて |
gl |
文字列 | 検索元の国がパラメータ値と一致する検索結果を優先します。
これは、言語の値を設定している場合のみ使用できます。 使用例: |
すべて |
lr |
文字列 | 検索結果を特定の言語のドキュメントに限定します。
使用例: |
すべて |
sort_by |
文字列 | 日付または他の構造化コンテンツを使用して結果を並べ替えます。属性値は、プログラム可能な検索の [結果の並べ替え] 設定で指定されたオプションのいずれかである必要があります。
関連性で並べ替えるには、空の文字列(sort_by="")を使用します。 使用例: |
すべて |
検索結果 | |||
enableOrderBy |
ブール値 | 関連性、日付、ラベルによる結果の並べ替えを有効にします。 | すべて |
linkTarget |
文字列 | リンク ターゲットを設定します。デフォルト: _blank 。 |
検索結果 searchresults-only |
noResultsString |
文字列 | クエリに一致する結果がない場合に表示するデフォルトのテキストを指定します。 デフォルトの結果文字列を使用すると、ローカライズされた文字列をすべての カスタム言語はサポートされていません。 | 検索結果 searchresults-only |
resultSetSize |
整数、文字列 | 結果セットの最大サイズ。例: large
small 、filtered_cse 、10 。「
のデフォルト値は、レイアウトと、エンジンが
ウェブ全体または特定のサイトのみ
を対象に指定できます |
すべて |
safeSearch |
文字列 | 次の場合に指定します。
セーフサーチは、ウェブ検索と画像検索の両方で有効になっています。指定できる値は off です
および active 。 |
すべて |
コールバック
<ph type="x-smartling-placeholder">コールバックは、検索要素の初期化と検索プロセスの詳細な制御をサポートします。
これらは、グローバル __gcse
を介して検索要素 JavaScript に登録されます。
渡されます。Register Callbacks は、
コールバック関数を呼び出します。
初期化コールバック
検索要素の JavaScript が検索をレンダリングする前に初期化コールバックが呼び出される
参照できます。parsetags
が explicit
に設定されている場合:
__gcse
の場合、検索要素 JavaScript はレンダリング検索要素を
初期化コールバックを使用します(コールバックの登録を参照)。
これを使用して、レンダリングする要素を選択したり、要素がアップロードされるまでレンダリングを延期したりできます。
必要ありません。要素の属性をオーバーライドすることもできます。たとえば、
コントロール パネルまたは HTML 属性によってデフォルトでウェブに設定される検索ボックス
画像検索の検索ボックスで検索するか、プログラム可能検索エンジンのフォームで送信したクエリに対して
searchresults-only 要素内で実行される必要があります。
<ph type="x-smartling-placeholder"></ph>
デモをご覧ください。
初期化コールバックのロールは、parsetags
の値によって制御されます。
__gcse
のプロパティです。
- 値が
onload
の場合、検索要素 JavaScript により、ページ上のすべての検索要素が自動的にレンダリングされます。初期化コールバックは、 は引き続き呼び出されますが、検索要素のレンダリングは担いません。 - 値が
explicit
の場合、検索要素の JavaScript はレンダリングされません。 要素を検索します。コールバックは、render()
関数を使用すると、go()
関数ですべての検索要素をレンダリングする
次のコードは、検索結果とともに検索ボックスを
div
(explicit
解析タグと初期化コールバックを使用):
検索コールバック
検索要素 JavaScript は、 検索制御フローについて説明します 検索コールバックは、ウェブ検索コールバックとそれに対応する画像検索コールバックのペアで提供されます。
- 検索を開始しています
<ph type="x-smartling-placeholder">
- </ph>
- 画像検索の場合
- ウェブ検索用
- 結果の準備が完了しました
<ph type="x-smartling-placeholder">
- </ph>
- 画像検索の場合
- ウェブ検索用
- レンダリングされた結果
<ph type="x-smartling-placeholder">
- </ph>
- 画像検索の場合
- ウェブ検索用
初期化コールバックと同様に、検索コールバックは
__gcse
オブジェクトのエントリを使用して構成します。これは検索要素として
JavaScript が開始されます。起動後の __gcse
の変更は無視されます。
これらの各コールバックには、それぞれのサービスの gName
が
Search Element を引数として指定します。
gname
は、ページに複数の検索が含まれている場合に役立ちます。検索する
data-gname
属性を使用して gname
要素を指定します。
<div class="gcse-searchbox" data-gname="storesearch"></div>
HTML で gname が識別されない場合、検索要素の JavaScript は、 HTML が変更されるまで一貫性が維持されます。
画像検索/ウェブ検索開始コールバック
検索要素 JavaScript リクエストの直前に検索開始コールバックが呼び出される 受信します。ユースケースの例として、ローカル時刻を使用して、 クエリの変更を制御できます。
searchStartingCallback(gname, query)
gname
- 検索要素の識別文字列
query
- ユーザーが入力した値(検索によって変更される可能性がある) 渡します。
このコールバックは、この検索のクエリとして使用する値を返します。レスポンスで 空の文字列の場合、戻り値は無視され、呼び出し元は変更されていないクエリを使用します。
または、コールバック関数を __gcse
オブジェクトに配置するか、
JavaScript を使用して、このコールバックをオブジェクトに動的に追加します。
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
検索開始コールバックの例
次の検索開始コールバックの例は、
検索開始コールバックの例: morning
のいずれかを追加する
または afternoon
をクエリに追加できます。
このコールバックを window.__gcse:
にインストールします。
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
画像/ウェブ検索結果準備完了コールバック
これらのコールバックは、検索要素 JavaScript がプロモーションをレンダリングし、 表示されます。ユースケースの例として、プロモーションをレンダリングし、 通常のカスタマイズでは指定できません。
resultsReadyCallback(gname, query, promos, results, div)
gname
- 検索要素の識別文字列
query
- これらの結果を生成したクエリ
promos
- 一致したプロモーション オブジェクトの配列 のプロモーション 表示されます。詳しくは、プロモーション オブジェクトの定義をご覧ください。
results
- 結果オブジェクトの配列。詳しくは、 結果オブジェクトの定義。
div
- 検索要素が通常配置される DOM 内の HTML div
場所、プロモーション、検索結果。通常、Search Element JavaScript は、
表示されますが、このコールバックによって結果の自動レンダリングが停止されることもあります。
この
div
を使用して結果自体をレンダリングします。 で確認できます。
このコールバックが true
値を返す場合、検索要素の JavaScript は
ページフッターが機能します。
Results Ready コールバックの例
resultsReady
コールバックの例
Example Results Ready Callback によってデフォルトの表示方法をオーバーライドする
非常にシンプルな置き換えで、さまざまなプロモーションと結果を
画像/ウェブ検索結果としてレンダリングされたコールバック
これらのコールバックは、検索要素 JavaScript がページをレンダリングする直前に呼び出されます 追加できます。ユースケースの例として、検索対象の検索結果コンテンツを追加するコールバック [save this] チェックボックスや、 または [詳細情報を表示] ボタンを追加するコールバックを使用します。
結果レンダリングされたコールバックが、promos
に含まれていた情報を必要としている場合は、
results
結果準備完了コールバックのパラメータは、次のように指定し、結果を相互に渡すことができます。
callback(gname, query, promoElts, resultElts);
gname
- 検索要素の識別文字列
query
- 検索文字列。
promoElts
- プロモーションを含む DOM 要素の配列。
resultElts
- 結果を含む DOM 要素の配列。
戻り値はありません。
結果レンダリングされたコールバックの例
resultsRendered
コールバックの例
結果レンダリングされたコールバックの例: ダミーの Keep を追加します。
チェックボックスをオンにできます
結果レンダリングされたコールバックが
結果準備完了コールバックに渡された情報が渡され、
あります。次の例は、評価値を渡すさまざまな方法の 1 つを示しています。
結果準備完了コールバックから結果レンダリングへの richSnippet
あります。
その他のコールバックの例
その他のコールバックの例については、このモジュールの その他のコールバックの例のドキュメントをご覧ください。
プロモーション プロパティと結果プロパティ
JSDoc 表記を使用すると、次のプロパティになります。 promotion オブジェクトと result オブジェクト。 ここでは、存在する可能性のあるすべてのプロパティをリストしています。多数の宿泊施設が存在すること プロモーションや検索結果の詳細によって異なります。
<ph type="x-smartling-placeholder"> <ph type="x-smartling-placeholder">結果の richSnippet
は、配列の緩い型です。
説明します。この配列内のエントリの値は、
構造化データ
各検索結果のウェブページに表示されますたとえば、レビューのウェブサイトには
この配列エントリを richSnippet
に追加する構造化データ:
'review': { 'ratingstars': '3.0', 'ratingcount': '1024', },
Programmable Search Element Control API(V2)
google.search.cse.element
オブジェクトは以下を公開します。
静的関数:
機能 | 説明 | ||||||
---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
検索要素をレンダリングします。
パラメータ
|
||||||
.go(opt_container) |
指定されたコンテナ内のすべての検索要素タグやクラスをレンダリングします。
パラメータ
|
||||||
.getElement(gname) |
gname で要素オブジェクトを取得します。見つからなかった場合は null を返します。
返される
次のコードは、「news」というクエリを実行します。検索要素 "element1": var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
gname をキーとして、正常に作成されたすべての要素オブジェクトのマップを返します。 |