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

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

たとえば、コントロールを使用して、結果のブーストと非表示、返された結果からのエントリのフィルタ、文字列の同義語としての関連付け、指定された 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 フィールドをご覧ください。

ブースト サービス提供コントロールを作成して関連付ける

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

ブースト コントロールを作成して関連付けるには、次の操作を行います。

コンソール

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

   AI Applications

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

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

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

5. [制御を作成] をクリックします。

6. [コントロールの作成] ペインで、次の操作を行います。

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

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

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

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

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

         フィルタ式の作成方法については、フィルタ式の構文とフィルタ式の例をご覧ください。

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

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

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

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

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

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

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

   4. このコントロールを作成してすぐに適用する場合は、[追加設定] で [このコントロールをすぐに公開する] をオンにして、[続行] をクリックします。

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

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: Vertex AI Search アプリの 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: ドキュメントが満たす必要がある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、ブーストが適用されます。それ以外の場合は変更はありません。このフィールドが空の場合、ブーストはデータストア内のすべてのドキュメントに適用されます。フィルタリング構文については、フィルタ式の構文をご覧ください。注: ドキュメント フィールド title はフィルタできません。
   • 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 リファレンスをご覧ください。

コンソール

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

   AI Applications

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

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

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

5. [制御を作成] をクリックします。

6. [コントロールの作成] ペインで、次の操作を行います。

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

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

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

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

         フィルタ式の作成方法については、フィルタ式の構文とフィルタ式の例をご覧ください。

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

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

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

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

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

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

   4. このコントロールを作成してすぐに適用する場合は、[追加設定] で [このコントロールをすぐに公開する] をオンにして、[続行] をクリックします。

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

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: Vertex AI Search アプリの 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 をご覧ください。注: ドキュメント フィールド title はフィルタできません。

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 リファレンスをご覧ください。

コンソール

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

   AI Applications

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

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

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

5. [制御を作成] をクリックします。

6. [コントロールの作成] ペインで、次の操作を行います。

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

   2. [ルールの範囲と影響の程度] で、次の操作を行います。

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

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

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

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

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

   4. このコントロールを作成してすぐに適用する場合は、[追加設定] で [このコントロールをすぐに公開する] をオンにして、[続行] をクリックします。

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

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: Vertex AI Search アプリの 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: Vertex AI Search アプリの 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 リファレンスをご覧ください。

コンソール

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

   AI Applications

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

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

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

5. [制御を作成] をクリックします。

6. [コントロールの作成] ペインで、次の操作を行います。

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

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

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

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

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

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

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

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

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

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

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

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

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: Vertex AI Search アプリの 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 をご覧ください。

   レスポンス

   次のような JSON レスポンスが返されます。

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

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
  }
 }
}

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

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. [コントロールを編集] ペインでコントロールを編集します。

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

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

次のステップ

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