このページは Cloud Translation API によって翻訳されました。

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

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

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

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

ブーストサービス提供コントロールは、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 を含むコントロールとして定義されます。

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

フィールドの詳細については、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 を含むコントロールとして定義されます。

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

フィールドの詳細については、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 に設定する必要があります。

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

フィールドの詳細については、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_TRUE|FALSE
    }
  ],
  "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: コントロールを適用するタイミングを定義する省略可能なオブジェクト。次のフィールドが含まれています。
  - queryTerms:
    - VALUE: 照合する特定のクエリ値。長さ [1, 5000] の小文字の UTF-8 文字列です。
    - FULL_MATCH_TRUE|FALSE: クエリ用語を完全に一致させる必要があるかどうかを示すブール値。
  - activeTimeRange:
    - 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 に置き換えます。

次のステップ

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

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

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

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

条件について

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

フィルタ サービス提供コントロールを作成して接続する

類義語のサービング コントロールを作成して関連付ける

リダイレクト サービス提供コントロールを作成して接続する

プロモーション サービス提供コントロールを作成して接続する

レスポンス

次のステップ

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

フィルタサービス提供コントロールを作成して接続する

類義語のサービングコントロールを作成して関連付ける

リダイレクトサービス提供コントロールを作成して接続する

プロモーションサービス提供コントロールを作成して接続する