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

サービス提供コントロール（コントロールとも呼ばれる）は、リクエストのデフォルトの動作を変更します。

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

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

リクエストの結果を変更するには、まずサービス提供コントロールを作成します。次に、そのコントロールをアプリにアタッチします。コントロールは、コントロールがアタッチされているアプリによって処理されるリクエストにのみ影響します。コントロールがアプリにアタッチされていない場合、効果はありません。

ブーストコントロールなど、一部のコントロールはデータストアに依存しています。データストアがアプリから削除されると、データストアに依存するコントロールもそのアプリから削除され、無効になりますが、削除されることはありません。

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

queryTerms。特定のクエリが検索されたときにコントロールが適用されます。
activeTimeRange。指定された期間内にリクエストが発生したときにコントロールが適用されます。

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

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

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

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

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

詳しくは、API リファレンスの servingConfigs.search をご覧ください。

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

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

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

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

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

boostAction の構文は次のとおりです。

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}

BOOST: -1～1 の浮動小数点数。値が負の場合、検索結果の下位に表示されるように結果が降格されます。値が正の値の場合、検索結果の上位に表示されるように結果が昇格されます。
FILTER: ドキュメントが満たす必要がある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、ブーストが適用されます。それ以外は変更はありません。このフィールドが空の場合、データストア内のすべてのドキュメントにブーストが適用されます。フィルタリング構文については、フィルタ式の構文をご覧ください。
DATA_STORE_RESOURCE_PATH: このコントロールによってドキュメントのブーストを適用するデータストアの完全なリソースパス。完全なリソースパスの形式は projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID です。このデータストアは、リクエストで指定されたエンジンにアタッチする必要があります。

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

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

filterAction の構文は次のとおりです。

{
    "filter": "FILTER"
}

FILTER: ドキュメントが満たす必要のある要件を指定する文字列。ドキュメントがすべての要件を満たしている場合、結果が結果リストに含まれます。そうでない場合、結果は結果リストから削除されます。フィルタリング構文については、フィルタ式の構文をご覧ください。

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

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

synonymsAction の構文は次のとおりです。

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: 互いに関連付けられる文字列。これにより、各文字列で類似した結果が表示されやすくなります。少なくとも 2 つの文字列を指定する必要があります。最大 100 個の文字列を指定できます。文字列は UTF-8 で小文字にする必要があります。重複する文字列は使用できません。

例:

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

リダイレクトサービス提供コントロールについて

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

リダイレクトコントロールは、redirectAction を含むコントロールとして定義されます。

redirectAction の構文は次のとおりです。

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: 最大 2,000 文字の URI。

たとえば、クエリ語句の値が「サポート」の場合、「サポート」の検索結果を返さない（または返すのに失敗した）代わりに、テクニカルサポートページへのリダイレクトを設定できます。

{
    "redirect_uri": ["https://www.example.com/support"]
}

`queryTerms` 条件について

queryTerms は任意です。特定のクエリが検索されたときにサービス提供コントロールを使用する場合にこれを使用します。queryTerms 条件を使用すると、queryTerms の値が SearchRequest.query のキーワードと一致すると、コントロールが適用されます。

クエリ語句は、Control.searchUseCase が SOLUTION_TYPE_SEARCH として設定されている場合にのみ使用できます。

1 つの Control.condition に最大 10 個の異なる queryTerms を指定できます。クエリ語句が指定されていない場合、フィールドは無視されます。

単一の queryTerm の構文は次のとおりです。

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1: 長さが [1, 5000] の小文字の UTF-8 文字列。FULL_MATCH_1 が true の場合、スペース区切りで最大 3 つのキーワードを含めることができます。
FULL_MATCH_1: ブール値。true に設定した場合、SearchRequest.query は queryTerm.value と完全に一致する必要があります。false に設定した場合、SearchRequest.query に queryTerm.value が部分文字列として含まれている必要があります。

`activeTimeRange` 条件について

activeTimeRange は任意です。リクエストを受信した時刻が activeTimeRange.startTime～activeTimeRange.endTime の範囲内であることを確認します。

1 つの Control.condition で最大 10 個の activeTimeRange 範囲を指定できます。activeTimeRange 範囲が指定されていない場合、このフィールドは無視されます。

単一の activeTimeRange の構文は次のとおりです。

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: コントロールが適用される最も早い時刻（この値を含む）を定義します。タイムスタンプは RFC 3339 UTC「Zulu」形式で、精度はナノ秒まで、小数点以下は最大 9 桁（例: "2023-10-02T15:01:23Z"）。
END_TIMESTAMP_1: コントロールが適用される最新の時刻（この値を含む）を定義します。この時刻は未来の時刻にする必要があります。

API の手順: サービス提供コントロールを使用してデフォルトの検索リクエストの動作を変更する

デフォルトの検索リクエストの動作を変更するには、サービス提供コントロールを作成し、デフォルトのサービス提供構成にアタッチします。

始める前に

サービス提供コントロールを作成する場合は、Google アカウントチームに連絡して、サービス提供コントロールの許可リストに追加するよう依頼してください。

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

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

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

データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。

コントロールの条件タイプとフィールド値を選択します。

短縮した条件の例を次に示します。

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

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

ブーストコントロール: クリックすると、ブーストコントロールを作成する curl コマンドが表示されます。

次の 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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

フィルタオプション: クリックすると、フィルタオプションを作成する curl コマンドが表示されます。

次の 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

類義語コントロール: クリックすると、類義語コントロールを作成する curl コマンドが表示されます。

次の 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

リダイレクトコントロール: クリックすると、リダイレクトコントロールを作成する curl コマンドが表示されます。

次の 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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID: Google Cloud プロジェクトのプロジェクト番号または ID。
DATA_STORE_ID: データストアの一意の ID。
CONTROL_ID: コントロールの固有識別子（データストア内）。ID には、小文字、数字、ハイフン、アンダースコアを使用できます。
DISPLAY_NAME: コントロールのわかりやすい名前。この名前には、コントロールを使用するタイミングや理由を示すことをおすすめします。長さが [1,128] の UTF-8 文字列にする必要があります。
USE_CASE: SEARCH_USE_CASE_SEARCH または SEARCH_USE_CASE_BROWSE のいずれかを指定する必要があります。SEARCH_USE_CASE_BROWSE が指定されている場合、条件で Condition.queryTerms を使用できません。
CONDITION:（省略可）コントロールを適用するタイミングを定義します。
BOOST_ACTION: ブーストコントロールの定義に使用されます。boostAction API リファレンスをご覧ください。
FILTER_ACTION: フィルタコントロールの定義に使用されます。filterAction API リファレンスをご覧ください。
SYNONYMS_ACTION: 類義語コントロールの定義に使用されます。synonymsAction API リファレンスをご覧ください。
REDIRECT_ACTION: リダイレクト URI の指定に使用されます。redirectAction API リファレンスをご覧ください。

コントロールをアプリにアタッチします。

ブーストコントロール: ブーストコントロールの curl コマンドについては、こちらをクリックします。

次の curl コマンドを実行して、ブーストコントロールをサービス提供構成にアタッチし、サービス提供リクエストでの使用を有効にします。

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 と BOOST_ID_2: 前の手順で作成したコントロール ID を表します。

フィルタオプション: フィルタコントロールの curl コマンドについては、こちらをクリックします。

次の curl コマンドを実行して、フィルタコントロールをサービス提供構成にアタッチし、サービス提供リクエストでの使用を有効にします。

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 と FILTER_ID_2: 前の手順で作成したコントロール ID を表します。

類義語コントロール: 類義語コントロールの curl コマンドについては、こちらをクリックします。

次の curl コマンドを実行して、類義語コントロールをアプリにアタッチし、サービス提供リクエストでの使用を有効にします。

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 と SYNONYM_ID_2: 前の手順で作成したコントロール ID を表します。

リダイレクトコントロール: リダイレクトコントロールの curl コマンドについては、こちらをクリックします。

次の curl コマンドを実行して、リダイレクトコントロールをアプリに接続し、サービス提供リクエストでの使用を有効にします。

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 と REDIRECT_ID_2: 前の手順で作成したコントロール ID を表します。

次のステップ

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

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

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

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

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

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

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

リダイレクト サービス提供コントロールについて

queryTerms 条件について

activeTimeRange 条件について

API の手順: サービス提供コントロールを使用してデフォルトの検索リクエストの動作を変更する

始める前に

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

次のステップ

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

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

リダイレクトサービス提供コントロールについて

`queryTerms` 条件について

`activeTimeRange` 条件について