注: このドキュメントセットは、Gemini Enterprise の Standard、Plus、従量課金、Frontline エディションを対象としています。Business エディションのドキュメントについては、Gemini Enterprise - Business エディションのヘルプセンターをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

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

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

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

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

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

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

条件について

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

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

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

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

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

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

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

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

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

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

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

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

コンソール

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

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
ブーストコントロールを作成するアプリを選択します。
[構成] をクリックし、[制御] タブをクリックします。
[コントロールを作成] をクリックします。
[What do you want to do?] で、コントロールの名前とタイプを指定します。
1. [コントロール名] に、ブースト/埋め込みコントロールの名前を入力します。
2. [コントロールタイプ] で [ブースト/ベリー] を選択します。
3. [続行] をクリックします。
[ルールの範囲と影響の程度を設定する] で、このコントロールを使用してトリガーするアクションを定義します。
1. リストからデータストアを選択します。複数のデータストアにアクションを適用する場合は、データストアごとにコントロールを作成します。
2. [フィルタ] で、フィルタを追加します。
  
  これは、ドキュメントが満たす必要がある要件を指定する文字列です。ドキュメントがすべての要件を満たしている場合にのみ、ブースト条件が適用されます。それ以外の場合は変更されません。フィルタを指定しない場合、ブーストはデータストア内のすべてのドキュメントに適用されます。
  
  フィルタリング構文については、フィルタ式の構文をご覧ください。
3. [ブースト/埋め込み値] には、スライダーを使用して [-1, 1] の範囲でブースト/埋め込み値を選択します。スライダーは 0.01 刻みで移動します。
4. [続行] をクリックします。
[省略可: このルールが有効になる条件] で、制御をトリガーする次の条件を設定します。条件が構成されていない場合、コントロールは常に有効です。
1. 部分一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が部分一致した場合に有効になります。
2. 完全一致のクエリ語句を追加します。このコントロールは、これらのクエリ用語が完全に一致した場合に有効になります。
3. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。
4. [続行] をクリックします。
[その他の設定] で、ルールを有効にするかどうかを選択します。
1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。
2. [続行] をクリックします。
[送信] をクリックします。

REST

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

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

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

アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。
1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の 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: ドキュメントが満たす必要がある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、ブーストが適用されます。それ以外の場合は変更はありません。このフィールドが空の場合、ブーストはデータストア内のすべてのドキュメントに適用されます。フィルタリング構文については、フィルタ式の構文をご覧ください。注: ドキュメントフィールド title はフィルタできません。
- DATA_STORE_RESOURCE_PATH: このコントロールでドキュメントをブーストするデータストアの完全なリソースパス。完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID です。このデータストアは、リクエストで指定されたエンジンに接続されている必要があります。

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 に置き換えます。

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

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

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

コンソール

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

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
フィルタコントロールを作成するアプリを選択します。
[構成] をクリックし、[制御] タブをクリックします。
[コントロールを作成] をクリックします。
[What do you want to do?] で、コントロールの名前とタイプを指定します。
1. [コントロール名] に、フィルタコントロールの名前を入力します。
2. [コントロールタイプ] で [フィルタ] を選択します。
3. [続行] をクリックします。
[ルールの範囲と影響の程度を設定する] で、このコントロールを使用してトリガーするアクションを定義します。
1. リストからデータストアを選択します。複数のデータストアにアクションを適用する場合は、データストアごとに制御を作成します。
2. [フィルタ] で、ルールで検索する具体的なアイテムを指定します。AND、OR、NOT を使用して検索語句を組み合わせ、() を使用して語句をグループ化できます。完全一致のフレーズを指定する場合は、引用符（""）を使用します。例: category: "electronics" AND price < 500, status: "open" AND priority:"P1"。
  
  フィルタリング構文については、フィルタ式の構文をご覧ください。
3. [続行] をクリックします。
[省略可: このルールが有効になる条件] で、制御をトリガーする次の条件を設定します。条件が構成されていない場合、コントロールは常に有効です。
1. 部分一致のクエリ語句を追加します。このコントロールは、これらのクエリ語句が部分一致した場合に有効になります。
2. 完全一致のクエリ語句を追加します。このコントロールは、これらのクエリ用語が完全に一致した場合に有効になります。
3. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。
4. [続行] をクリックします。
[その他の設定] で、ルールを有効にするかどうかを選択します。
1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。
2. [続行] をクリックします。
[送信] をクリックします。

REST

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

アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。
1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の 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 をご覧ください。注: ドキュメントフィールド title はフィルタできません。

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 を含むコントロールとして定義されます。

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

コンソール

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

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
同義語コントロールを作成するアプリを選択します。
[構成] をクリックし、[制御] タブをクリックします。
[コントロールを作成] をクリックします。
[What do you want to do?] で、コントロールの名前とタイプを指定します。
1. [コントロールに名前を付ける] に、同義語コントロールの名前を入力します。
2. [コントロールタイプ] で [類義語] を選択します。
3. [続行] をクリックします。
[ルールの範囲と影響の程度を設定する] で、このコントロールを使用してトリガーするアクションを定義します。
1. コントロールで考慮する同義語を入力します。たとえば、「cats」と入力して改行し（カンマは使用しない）、「feline」と入力します。
2. [続行] をクリックします。
[省略可: このルールが有効になる条件] で、制御をトリガーする次の条件を設定します。条件が構成されていない場合、コントロールは常に有効です。
1. 配信時間帯を追加するには、[時間帯を追加] をクリックして、[開始時間 1] と [終了時間 1] を設定します。これは、条件が有効になる期間を定義します。追加できる期間は最大 10 個です。
2. [続行] をクリックします。
[その他の設定] で、ルールを有効にするかどうかを選択します。
1. 作成したコントロールをすぐに有効にしない場合は、[このコントロールをすぐにパブリッシュする] をオフにします。
2. [続行] をクリックします。
[送信] をクリックします。

REST

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

アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。
1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の 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 をご覧ください。

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

アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。
1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の 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 をご覧ください。

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 フィールドで fullMatch を true または false に設定する必要があります。

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

コンソール

プロモートサービス提供コントロールを作成するには、[REST] タブの手順に沿って操作します。

REST

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

アプリ ID を調べます。アプリ ID をすでに保有している場合は、次のステップに進みます。
1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
次の 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"
    }
  ]
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION"
  }
 }
}'
```
次のように置き換えます。
- 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: クエリ用語を完全に一致させる必要があるかどうかを示すブール値。
  - START_TIMESTAMP: 期間の開始を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
  - END_TIMESTAMP: 期間の終了を示す RFC 3339 UTC「Zulu」形式のタイムスタンプ。
- DATA_STORE_RESOURCE_PATH: 検索結果にプロモーション対象の URL が含まれているデータストアの完全なリソースパス。完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID です。このデータストアは、リクエストで指定されたエンジンに接続されている必要があります。
- DOCUMENT_RESOURCE_PATH: プロモートするドキュメントのリソースパスを指定するフィールド。DOCUMENT_RESOURCE_PATH フィールドにドキュメント ID を指定するか、URI フィールドに URI を指定するか、またはその両方を行う必要があります。
  
  完全なリソースパスの形式は projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID です。
- TITLE: プロモートするドキュメントまたはウェブページのタイトルを指定する必須フィールド。このタイトルは検索結果に表示されます。
- URI: 検索結果でユーザーが移動する URI を指定するフィールド。DOCUMENT_RESOURCE_PATH フィールドにドキュメント ID を指定するか、URI フィールドに URI を指定するか、またはその両方を行う必要があります。
- URI_DESCRIPTION: URI を説明する省略可能なフィールド。検索結果に表示されます。
レスポンス

次のような 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
  }
 }
}
```
レスポンスには、検索アプリにプロモートコントロールを関連付けるために必要なプロモートコントロール ID が含まれています。

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 に置き換えます。

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

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

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
コントロールを変更するアプリを選択します。
[構成] をクリックし、[制御] タブをクリックします。
アプリのコントロールのリストで、変更するコントロールのをクリックし、[編集] をクリックします。
[コントロールを編集] ペインでコントロールを編集します。
1. コントロールを有効または無効にするには、アプリのフィルタコントロールのリストで、有効または無効にするコントロールのをクリックし、[有効にする] または [無効にする] をクリックします。
2. コントロールを削除するには、アプリのコントロールのリストで、削除するコントロールのをクリックし、[削除] をクリックします。

次のステップ

サービス提供コントロールがアプリの検索品質に与える影響を把握するには、検索品質を評価します。

サービス提供コントロールを構成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

条件について

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

コンソール

REST

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

コンソール

REST

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

コンソール

REST

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

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

コンソール

REST

レスポンス

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

次のステップ

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

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

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

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

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