検索のサービス提供コントロールを構成する

サービス提供コントロール（コントロールとも呼ばれる）は、結果が返されたときにリクエストが処理されるデフォルトの動作を変更します。サービス提供制御はデータストア レベルで機能します。

たとえば、コントロールを使用して、結果のブーストと非表示、返された結果からのエントリのフィルタ、文字列の類義語としての関連付け、指定された URI への結果のリダイレクトを行うことができます。

このページでは、検索アプリのサービス提供コントロールについて説明します。メディア レコメンデーションでサービス提供コントロールを使用する方法については、メディア サービス提供構成の作成と管理をご覧ください。

サービス提供コントロールについて

リクエストの結果を変更するには、まずサービス提供コントロールを作成します。次に、そのコントロールを検索アプリのサービス提供構成に関連付けます。サービス提供構成は、検索結果や回答など、サービス提供時の結果の生成に使用されるメタデータを構成します。サービス提供コントロールは、コントロールがアプリのサービス提供構成に関連付けられている場合にのみ、アプリによって配信されるリクエストに影響します。

ブースト コントロールなどの一部のコントロールには、データストアへの依存関係があります。データストアがアプリから削除されると、データストアに依存するコントロールもアプリから削除され、非アクティブになりますが、削除はされません。

サービス提供コントロールのタイプ

次のタイプのサービス提供コントロールを使用できます。

コントロール 説明 対象
ブースト コントロール 結果が返される順序を変更します 構造化データを含むデータストア、構造化データを含むウェブサイト（ウェブサイトの高度なインデックス登録）、メタデータを含む非構造化データ、メディアデータなど、スキーマをサポートするデータストアを含むアプリを検索する
フィルタ コントロール 返された結果からエントリを削除する 構造化データを含むデータストア、ウェブサイト（ウェブサイトの高度なインデックス登録）、メタデータを含む非構造化データ、メディアデータなど、スキーマをサポートするデータストアを含むアプリを検索する
類義語コントロール クエリを相互に関連付ける ウェブサイト（高度なウェブサイト インデックス登録）、構造化データ、非構造化データ、メディア データストアを含むアプリを検索する
リダイレクト コントロール 指定された URI にリダイレクトする すべての検索アプリ
プロモート コントロール クエリの指定されたリンクをプロモートする すべての検索アプリ

条件について

コントロールを作成するときに、コントロールが適用されるタイミングを決定する条件を定義できます（省略可）。条件は条件フィールドを使用して定義されます。次の条件フィールドを使用できます。

  • クエリ キーワード（queryTerms）。特定のクエリが検索されたときに適用されるオプションのコントロール。queryTerms 条件を使用すると、queryTerms の値が SearchRequest.query の用語と一致した場合に、コントロールが適用されます。クエリ語句は、Control.searchUseCase が SOLUTION_TYPE_SEARCH として設定されている場合にのみ使用できます。1 つの Control.condition で最大 10 個の異なる queryTerms を指定できます。クエリ用語が指定されていない場合、queryTerms フィールドは無視されます。

    プロモート サービス提供コントロールの場合、queryRegex 条件を指定している場合は queryTerms を指定できません。この条件は、ベーシック ウェブサイト検索にのみ適用されます。また、queryTerms が指定されている場合は、基本的なウェブサイト検索の fullMatch フィールドを true に設定する必要があります。他のすべての検索アプリでは、queryTerms のみがサポートされ、fullMatch は true または false に設定できます。

  • 期間（activeTimeRange）。指定された期間内にリクエストが発生したときに適用されるオプションのコントロール。リクエストが受信された時刻が activeTimeRange.startTime と activeTimeRange.endTime の間であることを確認します。1 つの Control.condition で最大 10 個の activeTimeRange 範囲を指定できます。activeTimeRange フィールドが指定されていない場合、このフィールドは無視されます。

  • queryRegex。ベーシック ウェブサイト検索のプロモーション配信コントロールでのみ使用できます。これは、クエリが指定された正規表現と一致した場合にコントロールを適用するオプションの条件です。queryTerms 条件を指定している場合、この条件は指定できません。

コントロールに複数の条件が指定されている場合、両方の条件タイプが満たされたときに、コントロールが検索リクエストに適用されます。同じ条件に複数の値が指定されている場合、その条件を満たすには、いずれか 1 つの値が一致すれば十分です。

たとえば、次の 2 つのクエリ用語が指定された条件について考えてみましょう。

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

この条件は、SearchRequest.query="gShoe" を含むリクエストまたは SearchRequest.query="gBoot" を含むリクエストに対しては満たされますが、SearchRequest.query="gSandal" やその他の文字列を含むリクエストに対しては満たされません。

条件が指定されていない場合、コントロールは常に適用されます。

詳細については、API リファレンスの Condition フィールドをご覧ください。

ブースト サービス提供コントロールの作成と適用

ブースト サービス提供コントロールは、適用された条件に基づいて結果の順位を上げたり下げたりして、結果の順序を変更します。ブーストは、ブースト条件を満たすドキュメントのランキングに乗数を適用することで機能します。

ブースト サービス提供コントロールを作成するには、次の操作を行います。

コンソール

Google Cloud コンソールを使用してブースト制御を作成して関連付けるには、次の操作を行います。

  1. Google Cloud コンソールで、[AI Applications] ページに移動します。

    AI Applications

  2. ブースト コントロールを作成するアプリを選択します。

  3. アプリの概要ページで、[システムの概要] タブが表示されていることを確認します。

  4. [シグナル] ステージで、[Boost/Bury] タイルをクリックします。

  5. [コントロールを作成] をクリックします。

  6. [コントロールに名前を付ける] にブースト/ベリー コントロールの名前を入力し、[続行] をクリックします。

  7. [ルールの範囲と影響の程度を設定する] で、このコントロールを使用してトリガーするアクションを定義します。

    1. リストからデータストアを選択します。複数のデータストアにアクションを適用する場合は、データストアごとに制御を作成します。

    2. [フィルタ] で、フィルタを追加します。

      これは、ドキュメントが満たす必要がある要件を指定する文字列です。ドキュメントがすべての要件を満たしている場合にのみ、ブースト条件が適用されます。それ以外の場合は変更されません。フィルタを指定しない場合、ブーストはデータストア内のすべてのドキュメントに適用されます。

      フィルタ式の記述方法については、構造化データまたは非構造化データのカスタム検索をフィルタすると高度なウェブサイト インデックス登録の構文をご覧ください。

    3. [ブースト/埋め込み値] には、スライダーを使用して [-1, 1] の範囲でブースト/埋め込み値を選択します。スライダーは 0.01 刻みで移動します。

    4. [続行] をクリックします。

  8. [省略可: このルールが有効になる条件] で、制御をトリガーする次の条件を設定します。条件が構成されていない場合、コントロールは常に有効です。

    1. 部分一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が部分的に一致した場合に有効になります。

    2. 完全一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が完全に一致した場合に有効になります。

    3. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。

    4. [続行] をクリックします。

  9. [その他の設定] で、ルールを有効にするかどうかを選択します。

    1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。

    2. [続行] をクリックします。

  10. [送信] をクリックします。

REST

ブースト サービス提供コントロールは、boostAction を含むコントロールとして定義されます。

ブースト サービス提供コントロールを作成するには、次の操作を行います。

フィールドの詳細については、engines.controls API リファレンスと engines.controls.create API リファレンスをご覧ください。

  1. アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。

    1. Google Cloud コンソールで、[AI Applications] ページに移動します。

      [アプリ] に移動

    2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。

  2. 次の curl コマンドを実行して、コントロールを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの番号または ID。
    • APP_ID: エージェント検索アプリの ID。
    • CONTROL_ID: コントロールの固有識別子。ID は [1～63] 文字で、英字、数字、ハイフン、アンダースコアを使用できます。
    • DISPLAY_NAME: 人が読める形式のコントロール名。この名前は、コントロールを使用するタイミングや理由を示すものにすることをおすすめします。長さが [1,128] の UTF-8 でエンコードされた文字列にする必要があります。
    • USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用することはできません。
    • CONDITION: コントロールを適用するタイミングを定義するオプションのフィールド。次のフィールドを含めます。
      • VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。FULL_MATCH_1 が true の場合、このフィールドにはスペースで区切られた用語を最大 3 つまで含めることができます。
      • FULL_MATCH: 検索クエリがクエリ用語と完全に一致する必要があるかどうかを示すブール値。true に設定した場合、SearchRequest.query が queryTerm.value と完全に一致している必要があります。false に設定した場合、SearchRequest.query に queryTerm.value が部分文字列として含まれている必要があります。
      • START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
      • END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
    • BOOST_VALUE: [-1,1] の範囲の浮動小数点。値が負の場合、結果はデモートされます（結果の下位に表示されます）。値が正の場合、結果はプロモートされます（結果の上位に表示されます）。 詳細については、boostAction をご覧ください。
    • FILTER: ドキュメントが満たす必要がある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、ブーストが適用されます。それ以外の場合は変更はありません。このフィールドが空の場合、ブーストはデータストア内のすべてのドキュメントに適用されます。フィルタリング構文については、フィルタ式の構文と高度なウェブサイトのインデックス登録の構文をご覧ください。フィルタで使用できるリストキー プロパティ フィールドのリストについては、フィルタリングをサポートするキー プロパティをご覧ください。
    • DATA_STORE_RESOURCE_PATH: このコントロールでドキュメントをブーストするデータストアの完全なリソースパス。完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID です。このデータストアは、リクエストで指定されたエンジンに接続されている必要があります。

  3. engines.servingConfigs.patch メソッドを使用して、コントロールをアプリのサービス構成に適用します。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    BOOST_ID_N は、前の手順で作成したコントロール ID に置き換えます。

フィルタ サービス提供コントロールの作成と適用

フィルタ サービス提供コントロールは、指定された条件またはルールでフィルタします。たとえば、ホテルサイトの場合、1 泊あたり 175 米ドル以下のペット可のホテルのみを表示する (price < 175 AND petfriendly = "true") のフィルタを適用できます。

フィルタ サービス提供コントロールは、filterAction を含むコントロールとして定義されます。

フィルタ サービス提供コントロールを作成するには、次の操作を行います。

フィールドの詳細については、engines.controls API リファレンスと engines.controls.create API リファレンスをご覧ください。

コンソール

Google Cloud コンソールを使用してフィルタ コントロールを作成してアタッチする手順は次のとおりです。

  1. Google Cloud コンソールで、[AI Applications] ページに移動します。

    AI Applications

  2. プロモート コントロールを作成するアプリを選択します。

  3. アプリの概要ページで、[システムの概要] タブが表示されていることを確認します。

  4. [シグナル] ステージで、[フィルタ] タイルをクリックします。

  5. [コントロールを作成] をクリックします。

  6. [コントロールに名前を付ける] にフィルタ コントロールの名前を入力し、[続行] をクリックします。

  7. [ルールの範囲と影響] で、次のように設定します。

    1. このフィルタ コントロールを適用するリストからデータストアを選択します。複数のデータストアにアクションを適用する場合は、データストアごとにコントロールを作成します。

    2. [フィルタ] で、ルールで検索する具体的なアイテムを指定します。検索語句は AND、OR、NOT を使用して組み合わせることができ、語句は () を使用してグループ化できます。完全一致のフレーズの場合は、引用符 "" を使用します。例: status: "open" AND priority:"P1"

      フィルタ式の記述方法については、構造化データまたは非構造化データのカスタム検索をフィルタするとウェブサイトの高度なインデックス登録の構文をご覧ください。

    3. [続行] をクリックします。

  8. [省略可: このルールが有効になる条件] で、このコントロールを使用してトリガーするアクションを定義します。条件が構成されていない場合、コントロールは常に有効です。

    1. 部分一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が部分的に一致した場合に有効になります。

    2. 完全一致のクエリ語句を追加します。これらのクエリ語句が完全に一致した場合に、コントロールが有効になります。

    3. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。

    4. [続行] をクリックします。

  9. [その他の設定] で、ルールを有効にするかどうかを選択します。

    1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。

    2. [続行] をクリックします。

  10. [送信] をクリックします。

REST

  1. アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。

    1. Google Cloud コンソールで、[AI Applications] ページに移動します。

      [アプリ] に移動

    2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。

  2. 次の curl コマンドを実行して、コントロールを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの番号または ID。
    • APP_ID: エージェント検索アプリの ID。
    • CONTROL_ID: コントロールの固有識別子。ID は [1～63] 文字で、英字、数字、ハイフン、アンダースコアを使用できます。
    • DISPLAY_NAME: 人が読める形式のコントロール名。この名前は、コントロールを使用するタイミングや理由を示すものにすることをおすすめします。長さが [1,128] の UTF-8 でエンコードされた文字列にする必要があります。
    • USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用することはできません。
    • CONDITION: コントロールを適用するタイミングを定義するオプションのフィールド。次のフィールドを含めます。
      • VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。FULL_MATCH_1 が true の場合、このフィールドにはスペースで区切られた用語を最大 3 つまで含めることができます。
      • FULL_MATCH: 検索クエリがクエリ用語と完全に一致する必要があるかどうかを示すブール値。true に設定した場合、SearchRequest.query が queryTerm.value と完全に一致している必要があります。false に設定した場合、SearchRequest.query に queryTerm.value が部分文字列として含まれている必要があります。
      • START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
      • END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。

    • FILTER: ドキュメントが満たす必要がある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、そのドキュメントは結果として返されます。それ以外の場合、ドキュメントは結果に含まれません。

      詳細については、 filterAction をご覧ください。 フィルタリング構文については、フィルタ式の構文と高度なウェブサイトのインデックス登録の構文をご覧ください。

  3. engines.servingConfigs.patch メソッドを使用して、コントロールをアプリのサービス構成に適用します。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    FILTER_ID_N は、前の手順で作成したコントロール ID に置き換えます。

類義語のサービス提供コントロールの作成と適用

類義語サービス提供コントロールは、synonymsAction を含むコントロールとして定義されます。

類義語のサービング コントロールを作成する手順は次のとおりです。

フィールドの詳細については、engines.controls API リファレンスと engines.controls.create API リファレンスをご覧ください。

コンソール

Google Cloud コンソールを使用して同義語コントロールを作成して関連付けるには、次の操作を行います。

  1. Google Cloud コンソールで、[AI Applications] ページに移動します。

    AI Applications

  2. 同義語コントロールを作成するアプリを選択します。

  3. アプリの概要ページで、[システムの概要] タブが表示されていることを確認します。

  4. [準備] ステージで、[同義語] タイルをクリックします。

  5. [コントロールを作成] をクリックします。

  6. [コントロールに名前を付ける] に類義語コントロールの名前を入力し、[続行] をクリックします。

  7. [ルールの範囲と影響の程度] の場合:

    1. コントロールで考慮する同義語を入力します。たとえば、「cats」と入力して改行し（カンマは使用しない）、「feline」と入力します。

    2. 同義語の入力が終わったら、[続行] をクリックします。

  8. [省略可: このルールが有効になる条件] で、このコントロールを使用してトリガーするアクションを定義します。条件が構成されていない場合、コントロールは常に有効です。

    1. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。

    2. [続行] をクリックします。

  9. [その他の設定] で、ルールを有効にするかどうかを選択します。

    1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。

    2. [続行] をクリックします。

  10. [送信] をクリックします。

REST

  1. 次の curl コマンドを実行して、コントロールを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの番号または ID。
    • APP_ID: エージェント検索アプリの ID。
    • CONTROL_ID: コントロールの固有識別子。ID は [1～63] 文字で、英字、数字、ハイフン、アンダースコアを使用できます。
    • DISPLAY_NAME: 人が読める形式のコントロール名。この名前は、コントロールを使用するタイミングや理由を示すものにすることをおすすめします。長さが [1,128] の UTF-8 でエンコードされた文字列にする必要があります。
    • USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用することはできません。
    • CONDITION: コントロールを適用するタイミングを定義するオプションのフィールド。次のフィールドを含めます。
      • VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。FULL_MATCH_1 が true の場合、このフィールドにはスペースで区切られた用語を最大 3 つまで含めることができます。
      • FULL_MATCH: 検索クエリがクエリ用語と完全に一致する必要があるかどうかを示すブール値。true に設定した場合、SearchRequest.query が queryTerm.value と完全に一致している必要があります。false に設定した場合、SearchRequest.query に queryTerm.value が部分文字列として含まれている必要があります。
      • START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
      • END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
    • SYNONYMS_N: 互いに関連付けられている文字列のリスト。これにより、それぞれで同様の結果が表示される可能性が高くなります。同様の結果が得られる可能性は高くなりますが、類義語エントリごとに検索すると、関連付けられたすべての類義語に関連する結果がすべて返されるとは限りません。類義語は少なくとも 2 つ指定する必要があります。最大 100 個の類義語を指定できます。各類義語は UTF-8 でエンコードし、小文字にする必要があります。重複する文字列は許可されていません。たとえば、「Pixel」、「Android スマートフォン」、「Google スマートフォン」を類義語として追加できます。詳細については、synonymsAction をご覧ください。

  2. engines.servingConfigs.patch メソッドを使用して、コントロールをアプリのサービス構成に適用します。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    SYNONYMS_ID_N は、前の手順で作成したコントロール ID に置き換えます。

リダイレクト サービス提供コントロールの作成と適用

リダイレクト サービス提供コントロールを使用すると、指定した URI にユーザーをリダイレクトできます。 リダイレクト コントロールは、redirectAction を含むコントロールとして定義されます。

リダイレクト サービス提供コントロールを作成するには、次の操作を行います。

フィールドの詳細については、engines.controls API リファレンスと engines.controls.create API リファレンスをご覧ください。

  1. アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。

    1. Google Cloud コンソールで、[AI Applications] ページに移動します。

      [アプリ] に移動

    2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。

  2. 次の curl コマンドを実行して、コントロールを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの番号または ID。
    • APP_ID: エージェント検索アプリの ID。
    • CONTROL_ID: コントロールの固有識別子。ID は [1～63] 文字で、英字、数字、ハイフン、アンダースコアを使用できます。
    • DISPLAY_NAME: 人が読める形式のコントロール名。この名前は、コントロールを使用するタイミングや理由を示すものにすることをおすすめします。長さが [1,128] の UTF-8 でエンコードされた文字列にする必要があります。
    • USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用することはできません。
    • CONDITION: コントロールを適用するタイミングを定義するオプションのフィールド。次のフィールドを含めます。
      • VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。FULL_MATCH_1 が true の場合、このフィールドにはスペースで区切られた用語を最大 3 つまで含めることができます。
      • FULL_MATCH: 検索クエリがクエリ用語と完全に一致する必要があるかどうかを示すブール値。true に設定した場合、SearchRequest.query が queryTerm.value と完全に一致している必要があります。false に設定した場合、SearchRequest.query に queryTerm.value が部分文字列として含まれている必要があります。
      • START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
      • END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
    • REDIRECT_URI_N: リダイレクト先の URI。最大長は 2,000 文字です。たとえば、クエリ語句の値が「サポート」の場合、「サポート」の検索結果を返さない（または返すのに失敗した）代わりに、テクニカル サポート ページへのリダイレクトを設定できます。この例では、リダイレクト URI は "https://www.example.com/support" になります。詳細については、redirectAction をご覧ください。

  3. engines.servingConfigs.patch メソッドを使用して、コントロールをアプリのサービス構成に適用します。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    REDIRECT_ID_N は、前の手順で作成したコントロール ID に置き換えます。

プロモート サービス提供コントロールの作成と適用

プロモート サービス提供コントロールを使用すると、リンクをプロモーション結果として表示できます。このコントロールは、次のタイプの検索データストアで使用できます。

  • 基本的なウェブサイト検索を備えたウェブサイト データストア: このようなデータストアでは、アプリのサービング構成にプロモート コントロールを関連付ける必要はありません。プロモート コントロールを作成して有効にすると、プロモート コントロールが有効になります。昇格コントロールは、有効または無効にすることでオンまたはオフにできます。

  • 構造化データと非構造化データ、ウェブサイトの高度なインデックス登録を含むウェブサイト データ、統合検索アプリを含むデータストア: これらのデータストアでは、プロモート コントロールをサービング構成にアタッチする必要があります。

プロモート コントロールは、promoteAction を使用して定義されます。

プロモート コントロールを正常に作成するには、作成リクエストで次のいずれかのフィールドが必要です。

  • queryTerms: 基本的なウェブサイト検索にのみ適用される queryRegex 条件を指定している場合、この条件は指定できません。基本的なウェブサイト検索では、queryTerms が指定されている場合、fullMatch を true に設定する必要があります。他のすべての検索アプリでは、queryTerms のみがサポートされ、fullMatch は true または false に設定できます。
  • queryRegex。ベーシック ウェブサイト検索のプロモーション配信コントロールでのみ使用できます。この条件では、クエリが指定された正規表現と一致した場合にコントロールが適用されます。queryTerms 条件を指定している場合、この条件は指定できません。

つまり、基本的なウェブサイト検索では、fullMatch を true に設定した queryTerms フィールドを指定するか、queryRegex フィールドを指定する必要があります。他のすべてのタイプの検索では、fullMatch が true または false に設定された queryTerms フィールドを指定します。

プロモート サービス提供コントロールを作成するには、次の操作を行います。

フィールドの詳細については、engines.controls API リファレンスと engines.controls.create API リファレンスをご覧ください。

コンソール

Google Cloud コンソールを使用して基本的なウェブサイト検索アプリのプロモート コントロールを作成して関連付けるには、次の操作を行います。他のアプリタイプの昇格制御を作成するには、[REST] タブの手順に沿って操作します。

  1. Google Cloud コンソールで、[AI Applications] ページに移動します。

    AI Applications

  2. フィルタ コントロールを作成するアプリを選択します。

  3. アプリの概要ページで、[システムの概要] タブが表示されていることを確認します。

  4. [シグナル] ステージで、[プロモート] タイルをクリックします。

  5. [コントロールを作成] をクリックします。

  6. [コントロールに名前を付ける] に、プロモート コントロールの名前を入力し、[続行] をクリックします。

  7. [ルールの範囲と影響] で、次のように設定します。

    1. このフィルタ コントロールを関連付けるデータストアをリストから選択します。複数のデータストアにアクションを適用する場合は、データストアごとにコントロールを作成します。

    2. [プロモーションのタイトル] に「最新の動画を見る」などのタイトルを入力します。

    3. 宣伝する URL（動画の場所など）を入力します。

    4. サムネイルやスクリーンショットなど、プロモート画像の URL を入力します。

    5. 動画の内容など、簡単な宣伝文句を入力します。最大文字数は 250 文字です。

  8. [省略可: このルールが有効になる条件] で、このコントロールを使用してトリガーするアクションを定義します。条件が構成されていない場合、コントロールは常に有効です。

    1. 完全一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が完全に一致した場合に有効になります。

    2. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。

    3. [続行] をクリックします。

  9. [送信] をクリックします。

REST

  1. 次の curl コマンドを実行して、コントロールを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの番号または ID。
    • APP_ID: エージェント検索アプリの ID。
    • CONTROL_ID: コントロールの固有識別子。ID は [1～63] 文字で、英字、数字、ハイフン、アンダースコアを使用できます。
    • DISPLAY_NAME: 人が読める形式のコントロール名。この名前は、コントロールを使用するタイミングや理由を示すものにすることをおすすめします。長さが [1,128] の UTF-8 でエンコードされた文字列にする必要があります。
    • USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用することはできません。
    • Condition: コントロールを適用するタイミングを定義するオプションのオブジェクト。次のフィールドを含めます。
      • queryTerms: queryRegex フィールドと併用できません。
        • VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。
      • activeTimeRange:
        • START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
        • END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
      • queryRegex: 基本的なウェブサイト検索を備えたデータストアでのみ使用できます。このフィールドは queryTerms フィールドと併用できません。
        • VALUE_REGEX: クエリの照合に使用する正規表現。
    • DATA_STORE_RESOURCE_PATH: 検索結果にプロモーション対象の URL が含まれているデータストアの完全なリソースパス。完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID です。このデータストアは、リクエストで指定されたエンジンに接続されている必要があります。
    • DOCUMENT_RESOURCE_PATH: プロモートするドキュメントのドキュメント リソースパスを指定するフィールド。
      • 構造化データと非構造化データを含む検索データストアの場合は、DOCUMENT_RESOURCE_PATH フィールドにドキュメント リソースパスを指定するか、URI フィールドに URI を指定するか、またはその両方を行う必要があります。完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID です。
      • ウェブサイトのデータストアの場合、このフィールドは設定解除し、代わりに URI フィールドを設定する必要があります。
    • TITLE: プロモートするドキュメントまたはウェブページのタイトルを指定する必須フィールド。このタイトルは検索結果に表示されます。
    • URI: 検索結果でユーザーが移動する URI リンクを指定する必須フィールド。この URI はデータストアに含める必要はありません。
      • 構造化データと非構造化データを含む検索データストアの場合は、DOCUMENT_RESOURCE_PATH フィールドにドキュメント リソースパスを指定するか、URI フィールドに URI を指定するか、またはその両方を行う必要があります。
      • ウェブサイト データストアの場合、これは必須フィールドであり、設定する必要があります。
    • DESCRIPTION: プロモートするドキュメントまたはウェブページを説明する省略可能なフィールド。検索結果に表示されます。
    • ENABLED_TRUE|FALSE: 昇格コントロールがオンになっていて、アプリに接続されているかどうかを示すオプションのブール値フィールド。このフィールドは、基本的なウェブサイト検索のみを含むウェブサイト データストアに適用されます。このフィールドを false に設定すると、プロモート サービング コントロールが無効になります。コントロールを有効にするには、次の手順で説明するように、コントロールを更新して有効にする必要があります。詳細については、promoteAction をご覧ください。

  2. 基本的なウェブサイト検索を除くすべての検索アプリで、engines.servingConfigs.patch メソッドを使用して、コントロールをアプリのサービス構成に適用します。次のリクエストで promoteControlIds を適用する順序は、プロモーション結果が返される順序です。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    PROMOTE_ID_N は、前の手順で作成したコントロール ID に置き換えます。

  3. 省略可: 基本的なウェブサイト検索の場合、コントロールをアプリのサービス構成にアタッチする必要はありません。ただし、基本的なウェブサイト検索では、コントロールの作成後にプロモーション コントロールをオンまたはオフにして、engines.control.patch メソッドを呼び出すことができます。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

例

プロモート コントロールに指定されたクエリまたはクエリの正規表現に一致するクエリを含む検索リクエストをアプリに送信すると、プロモートされたリンクがレスポンスに表示されます。

たとえば、基本的なウェブサイト検索を備えたデータストアで、次の構成のプロモート コントロールを作成するとします。

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

次の 検索リクエストを送信します。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

次のような JSON レスポンスが返されます。レスポンスには、プロモーション リンクを含む searchLinkPromotions フィールドが含まれます。

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

サービス提供コントロールを変更する

コントロールの構成を変更するには、次の操作を行います。

  1. Google Cloud コンソールで、[AI Applications] ページに移動します。

    AI Applications

  2. コントロールを変更するアプリを選択します。

  3. [システム概要] タブで、コントロールが配置されている [準備] ステージまたは [シグナル] ステージを選択します。

  4. アプリのコントロールのリストで、変更するコントロールの をクリックし、[編集] をクリックします。

  5. [コントロールを編集] ペインでコントロールを編集します。

    1. コントロールを有効または無効にするには、アプリのフィルタ コントロールのリストで、有効または無効にするコントロールの をクリックし、[有効にする] または [無効にする] をクリックします。

    2. コントロールを削除するには、アプリのコントロールのリストで、削除するコントロールの をクリックし、[削除] をクリックします。

次のステップ

  • サービス提供コントロールがカスタム検索アプリの検索品質に与える影響を把握するために、検索品質を評価します。詳細については、検索品質を評価するをご覧ください。