「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

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

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

このページでは、サービス提供コントロールの作成方法について説明します。

サービス提供コントロールは、個々のサービス構成を定義して適用するルールです。サービス構成について詳しくは、サービス構成についてをご覧ください。

サービス提供コントロールを使用すると、結果でのサービス提供構成をカスタマイズするルールを作成できます。

サービス提供コントロールは、コントロールをトリガーする条件と、条件によってトリガーされるときに発生するアクションで構成される Search for Retail コンソールで作成できます。その後、新しいサービス提供コントロールをサービス構成に関連付けることができます。

サービス構成は、コントロールと多対多の関係を持ちます。1 つのサービス構成に複数のコントロールを追加でき、1 つのコントロールを複数のサービス構成に関連付けることができます。

サービス提供コントロールとサービス構成を作成するときに、それを使用できるプロダクト（レコメンデーションまたは Retail Search）を選択します。サービス提供コントロールを関連付けできるのは、同じプロダクトタイプのサービス構成のみです。たとえば、レコメンデーション用に作成されたサービス提供コントロールを、Retail Search 用に作成されたサービス構成に関連付けることはできません。

サービス構成は、検索リクエストまたは予測リクエスト時に適用されるコントロールを管理します。リクエストの有効なサービス構成のコントロールだけが、サービス提供時に考慮されます。たとえば、「シューズ」が検索されたときに、gShoe のブランドの結果をブーストする「gShoe Sale」というコントールと、用語「ランニングシューズ」を使用して「スポーツシューズ」を含めるようクエリを拡張する「More Shoes」というコントロールを 2 つ作成したとします。サービス提供構成に「gShoe Sale」コントロールのみを関連付けた場合、そのサービス提供を使用して検索リクエストを行うと、用語「シューズ」を使用したクエリに対する gShoe の結果はブーストされますが、「More Shoes」コントロールは使用しているサービス提供構成に関連付けられていないため影響がありません。

コントロールを作成し、ライブサービス提供構成に追加または入れ替えることができます。

サービス提供コントロールは、[コントロール] ページまたは Controls.create メソッドを使用してインラインでいつでも作成または変更できます。コンソールでは、オプションでサービス構成の作成プロセス中にコントロールを作成できます。

最大 100 個のサービス提供コントロールを作成できます。さらにサービス提供コントロールが必要な場合は、追加の割り当てをリクエストしてください。追加の割り当てをリクエストする方法については、割り当てを増やすをご覧ください。サービス提供構成には、リダイレクトコントロール以外の最大 100 個のサービス提供コントロールを含めることができます。サービス提供構成ごとの上限は 1,000 個です。

サービス提供コントロールでは次の設定を使用できます。

ブースト / 埋め込み: 返される結果リスト内の検索結果のランキングと順序に影響します。 Retail Search とレコメンデーションで使用できます。
フィルタ: 返された結果リストからフィルタを通過しない結果を削除します。Retail Search でのみ利用できます。
リダイレクト: 検索クエリに応じてユーザーを特定のページにリダイレクトします。Retail Search でのみ利用できます。
言語: 検索クエリの言語をカスタマイズします。Retail Search でのみ使用できます。数種類の言語制御を使用できます。
- 類義語: 検索クエリの類義語と考えられるものを拡張します。
- 一方向の類義語: 特定のキーワードの類義語と考えられるものを一方向に拡張します。
- 関連付けない: 特定のキーワードが表示されたときに、あるキーワードグループが検索で使用されないようにします。
- 無視: 検索に特定のキーワードが使用されないようにします。
- 置換: 検索クエリのキーワードを置き換えます。
固定: 検索結果の並べ替えに影響し、検索結果を特定の位置（4 番目など）に配置します。検索とブラウジングで使用できます。

これらのコントロールの例については、サービス提供コントロールをご覧ください。

リダイレクト制御のチュートリアル

このチュートリアルでは、リダイレクト制御の使用方法について説明します。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

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

Google Cloud コンソールの [コントロール] ページで、または Controls.create メソッドを使用してインラインで新しいサービス提供コントロールを作成します。

コントロールの要件は、タイプによって異なります。作成するコントロールの種類の作成手順に進みます。

ブースト / 埋め込みコントロールを作成する
フィルタオプションを作成する
リダイレクトコントロールを作成する
固定コントロールを作成する
双方向の類義語コントロールを作成する
一方向の類義語コントロールを作成する
「関連付けなし」のコントロールを作成する
取り消しコントロールを作成する
代替コントロールを作成する

ブースト / 埋め込みコントロールを作成する

このコントロールタイプの詳細については、ブースト / 埋め込みコントロールをご覧ください。

このコントロールタイプは、Retail Search とレコメンデーションで利用できます。

検索のブースト/埋め込みコントロールを作成する
レコメンデーションのブースト / 埋め込みコントロールを作成する

検索のブースト/埋め込みコントロールを作成する

Retail Search のブースト / 埋め込みコントロールを作成するには:

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[コントロール] ページに移動
[サービス提供コントロール] タブで、 [コントロールを作成] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
[プロダクトの選択] セクションで、[検索] を選択します。
コントロールタイプとして [ブースト/埋め込みコントロール] を選択します。[続行] をクリックします。
[トリガー] セクションで、このコントロールをトリガーするユーザーの行動のタイプを選択します。
- カテゴリを閲覧する: ユーザーがサイトのカテゴリを閲覧したときにルールがトリガーされます（search.request.query は空です）。
- 検索: ユーザーがサイトで検索したときにルールがトリガーされます（search.request.query は空ではありません）。カテゴリが閲覧されたとき、またはクエリが検索されたときに、このコントロールを設定してトリガーするには、次の手順をスキップします。
省略可: 特定のカテゴリが閲覧されたか、特定のクエリが検索されたかに応じて、このコントロールをトリガーできる特定のカテゴリまたはクエリを設定します。
- [カテゴリを閲覧] を選択した場合: [カテゴリ] フィールドに、閲覧時にこのコントロールをトリガーするカテゴリを入力します。
- [検索] を選択した場合: [クエリを追加] ボタンをクリックし、フィルタするクエリ用語（running shoes など）を追加します。キーワードごとに、[部分一致] または [完全一致] を選択します。
注: 時間範囲条件に加えてカテゴリまたはクエリの利用条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。

注: このタイプの条件に加えて、時間範囲の条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
[続行] をクリックして [アクション] セクションに進みます。
[ブースト / 埋め込み商品] フィールドに商品属性のフィルタを追加します。

フィルタリングと並べ替えで記載されているフィルタ式の構文を使用してください。たとえば、「product1」と「product2」の赤と青のバージョンを指定するには: (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
[ブースト / 埋め込み値] には、スライダーを使用してブーストの強さを設定します。正の値は結果をブーストし、負の値は結果を埋め込みます。[続行] をクリックします。
[サービス提供構成] セクションで、コントロールを適用するサービス提供構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [Serving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

ユーザーがサイトのカテゴリを閲覧した場合（search.request.query が空）、またはユーザーがサイトを検索した場合（search.request.query が空でない）、ブースト / 埋め込みコントロールをトリガーできます。

次の例は、閲覧でトリガーされるコントロールのフィールドを示しています。ここで、searchSolutionUseCase は SEARCH_SOLUTION_USE_CASE_BROWSE に設定されています。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

次の例は、検索でトリガーされるコントロールのフィールドを示しています（searchSolutionUseCase は SEARCH_SOLUTION_USE_CASE_SEARCH に設定されています）。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

レコメンデーションのブースト / 埋め込みコントロールを作成する

レコメンデーションのブースト/埋め込みコントロールを作成するには:

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
[プロダクトの選択] セクションで、[レコメンデーション] を選択します。
コントロールタイプとして [ブースト / 埋め込みコントロール] を選択します。
[続行] をクリックして [アクション] セクションに進みます。
[ブースト / 埋め込み商品] フィールドに商品属性のフィルタを追加します。

レコメンデーションのフィルタのドキュメントに記載されているフィルタ式の構文を使用します。

たとえば、「product1」と「product2」の赤と青のバージョンを指定するには: (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
[ブースト / 埋め込み値] には、スライダーを使用してブーストの強さを設定します。正の値は結果をブーストし、負の値は結果を埋め込みます。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[コントロール] ページの [サービス提供コントロール] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

フィルタ式を作成するには、レコメンデーションのフィルタに記載されているフィルタ式の構文を使用します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_RECOMMENDATION" ],
                "boostAction": {
                  "boost": BOOST_NUMBER,
                  "productsFilter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

フィルタオプションを作成する

このコントロールタイプの詳細については、フィルタオプションをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [フィルタオプション] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
このコントロールをトリガーするユーザーの行動のタイプを選択します。
- カテゴリを閲覧する: ユーザーがサイトのカテゴリを閲覧したときにルールがトリガーされます（search.request.query は空です）。
- 検索: ユーザーがサイトで検索したときにルールがトリガーされます（search.request.query は空ではありません）。
省略可: 閲覧されるカテゴリまたは検索されるクエリに基づいてルールをトリガーするコントロール条件を設定します。使用可能なオプションは、[カテゴリを閲覧] か [検索] のどちらを選択するかによって異なります。
- [カテゴリを閲覧] を選択した場合: [カテゴリ] フィールドに、閲覧時にこのコントロールをトリガーするカテゴリを入力します。
- [検索] を選択した場合: [クエリを追加] ボタンをクリックし、フィルタするクエリ用語（running shoes など）を追加して、次の各用語のいずれかを選択します。
  - 部分一致: このコントロールは、クエリ語句に部分一致が含まれている場合に適用されます。
  - 完全一致: このコントロールは、クエリ語句に完全に一致する語句がクエリに含まれている場合にのみ適用されます。
  これらの語句の 1 つがクエリに含まれている場合にコントロールが適用されます。
注: この条件に加えて、時間範囲の条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。

注: この期間条件に加えて、カテゴリまたはクエリの利用条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
[続行] をクリックして [アクション] セクションに進みます。
[フィルタアクション] フィールドに、商品属性のフィルタを追加します。

フィルタリングと並べ替えで記載されているフィルタ式の構文を使用してください。

たとえば、「product1」と「product2」の赤と青のバージョンを指定するには: (id: ANY("product1","product2")) AND (colorFamily: ANY("Red","Blue"))
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[コントロール] ページの [サービス提供コントロール] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

ユーザーがサイトのカテゴリを閲覧した場合（search.request.queryが空）、またはユーザーがサイトを検索した場合（search.request.queryが空でない）、フィルタオプションをトリガーできます。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "filterAction": {
                  "filter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "pageCategories": [
                      "CATEGORY_ABC",
                      "CATEGORY_XYZ"
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "filterAction": {
                  "filter": "FILTER_EXPRESSION"
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

リダイレクトコントロールを作成する

このコントロールタイプの詳細については、リダイレクトコントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [リダイレクトコントロール] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
検索語句または期間トリガーを 1 つ以上作成します。リダイレクトコントロールには、少なくとも 1 つのトリガーが必要です。
このコントロールをトリガーするユーザーの行動のタイプを選択します。
- カテゴリを閲覧する: ユーザーがサイトのカテゴリを閲覧したときにルールがトリガーされます（search.request.query は空です）。
- 検索: ユーザーがサイトで検索したときにルールがトリガーされます（search.request.query は空ではありません）。
閲覧されるカテゴリまたは検索されるクエリに基づいてルールをトリガーするコントロール条件を設定します。使用可能なオプションは、[カテゴリを閲覧] か [検索] のどちらを選択するかによって異なります。
- [カテゴリを閲覧] を選択した場合: [カテゴリ] フィールドに、閲覧時にこのコントロールをトリガーするカテゴリを入力します。
- [検索] を選択した場合: [クエリを追加] ボタンをクリックし、フィルタするクエリ用語（running shoes など）を追加して、次の各用語のいずれかを選択します。
  - 部分一致: このコントロールは、クエリ語句に部分一致が含まれている場合に適用されます。
  - 完全一致: このコントロールは、クエリ語句に完全に一致する語句がクエリに含まれている場合にのみ適用されます。
  これらの語句の 1 つがクエリに含まれている場合にコントロールが適用されます。
注: この条件に加えて、時間範囲の条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
[時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。

注: この期間条件に加えて、カテゴリまたはクエリの利用条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
[続行] をクリックして [アクション] セクションに進みます。
このコントロールがトリガーされたときにリダイレクト先となる URI を入力します。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

ユーザーがサイトのカテゴリを閲覧した場合（search.request.queryが空）、またはユーザーがサイトを検索した場合（search.request.queryが空でない）、リダイレクトコントロールをトリガーできます。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_BROWSE"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "redirectAction": {
                  "redirectUri": "REDIRECT_URI",
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "searchSolutionUseCase": [
                "SEARCH_SOLUTION_USE_CASE_SEARCH"
              ],
              "rule": {
                "condition": {
                  "queryTerms": [
                    {
                      "value": "VALUE_1",
                      "fullMatch": "FULLMATCH_BOOLEAN_1"
                    },
                    {
                      "value": "VALUE_2",
                      "fullMatch": "FULLMATCH_BOOLEAN_2"
                    }
                  ],
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "redirectAction": {
                  "redirectUri": "REDIRECT_URI",
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

双方向の類義語コントロールを作成する

このコントロールタイプの詳細については、双方向の類義語コントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。
[コントロール名] フィールドに新しいコントロールの名前を入力します。

[コントロールを作成する] ペインが開きます。
[設定] セクションが表示されます。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [双方向の類義語コントロール] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。
[続行] をクリックして [アクション] セクションに進みます。
[類義語] フィールドに、互いに類義語であるクエリキーワード（shirt と top など）を 2 ～ 100 個入力します。

これらの語句のいずれかがクエリに含まれている場合、検索ではその他のクエリ語句は含まれている語句の類義語と見なされます。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                    ]
                },
                "twoWaySynonymAction": {
                  "synonyms": [
                    "SYNONYM_1",
                    "SYNONYM_2"
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。サービス構成にインラインでコントロールを追加するをご覧ください。

一方向の類義語コントロールを作成する

このコントロールタイプの詳細については、一方向の類義語コントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [一方向の類義語コントロール] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。
[続行] をクリックして [アクション] セクションに進みます。
[クエリキーワード] フィールドに、いずれかがクエリに含まれるときに類義語を関連付ける必要のある用語（shoes など）を入力します。
[類義語] フィールドに、指定したクエリキーワードの類義語として使用するキーワードを入力します（例: クエリキーワード shoes の一方向の類義語としての sneakers と sandals）。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "oneWaySynonymAction": {
                  "synonyms": [
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "synonyms": [
                      "SYNONYM_1",
                      "SYNONYM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

「関連付けなし」のコントロールを作成する

このコントロールタイプの詳細については、非関連付けコントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [Do not associate control] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。
[続行] をクリックして [アクション] セクションに進みます。
[クエリキーワード] フィールドに、他のクエリと明確に区別するキーワード（gShoe など）を入力します。
[関連付けられていないキーワード] フィールドに、指定したクエリキーワードに関連付けないようにするキーワードを入力します。

たとえば、クエリキーワード gShoe とキーワード cheap の関連付けを解除できます。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "doNotAssociateAction": {
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "doNotAssociateTerms": [
                      "DISSOCIATED_TERM_1",
                      "DISSOCIATED_TERM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

取り消しコントロールを作成する

このコントロールタイプの詳細については、取り消しコントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [Do not associate control] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。
[続行] をクリックして [アクション] セクションに進みます。
[キーワードを無視] フィールドに、クエリキーワードで入力するときに検索が無視するキーワード（shoddy など）を入力します。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "ignoreAction": {
                  "ignoreTerms": [
                      "IGNORE_TERM_1",
                      "IGNORE_TERM_2"
                    ]
                  ]
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

代替コントロールを作成する

このコントロールタイプの詳細については、代替コントロールをご覧ください。

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
コントロールタイプとして [代替コントロール] を選択します。
[続行]をクリックして [トリガー] セクションに進みます。
省略可: [時間範囲を追加] ボタンをクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。
[続行] をクリックして [アクション] セクションに進みます。
[クエリキーワード] フィールドに、代替キーワードで置き換えるクエリキーワード（gShoe など）を入力します。
[代替キーワード] フィールドに、指定したクエリキーワードを置き換えるキーワードを入力します。

たとえば、クエリキーワード gShoe を代替キーワード Google Shoe に置き換えることができます。
[続行] をクリックして [サービス提供構成] セクションに進みます。
コントロールを適用するサービス構成を選択します。
コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[Controls] ページの [erving controls] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "displayName": "DISPLAY_NAME",
              "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ],
              "rule": {
                "condition": {
                  "activeTimeRange": [
                    {
                      "startTime": "START_TIMESTAMP_1",
                      "endTime": "END_TIMESTAMP_1"
                    },
                    {
                      "startTime": "START_TIMESTAMP_2",
                      "endTime": "END_TIMESTAMP_2"
                    }
                  ]
                },
                "replacementAction": {
                    "queryTerms": [
                      "QUERY_TERM_1",
                      "QUERY_TERM_2"
                    ],
                    "replacementTerm": "REPLACEMENT_TERM"
                  }
                }
              }
    }' \
    "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?controlId=CONTROL_ID"

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

固定コントロールを作成する

固定コントロールを作成するには:

コンソール

Search for Retail コンソールの [コントロール] ページに移動します。

[Controls] ページに移動
[Serving controls] タブで、 [Create control] をクリックします。

[コントロールを作成する] ペインが開きます。
[設定] セクションの [コントロール名] フィールドに、新しいコントロールの名前を入力します。
省略可: 自動的に作成されたコントロール ID を変更するには、[編集] をクリックして新しいコントロール ID を入力します。
[プロダクトの選択] セクションで、[検索または参照] を選択します。
コントロールタイプとして [固定コントロール] を選択します。[続行] をクリックします。
[トリガー] セクションで、このコントロールをトリガーするユーザーの行動を選択します。
- カテゴリをブラウジングする: ブラウジングリクエストでは、search.request.query が空であるだけでなく、page_categories フィールドに値を入力する必要があります。
- 検索: 検索リクエストでは、search.request.query のみを入力する必要があります。
  
  デフォルトでは、閲覧されたすべてのカテゴリと検索されたすべてのクエリがこのコントロールをトリガーします。
省略可: 閲覧された特定のカテゴリまたは検索されたクエリに基づいてルールをトリガーする条件を設定します。
- カテゴリを閲覧: [カテゴリ] フィールドに、コントロールをトリガーするカテゴリを入力します。
- 検索: フィルタするクエリキーワード（running shoes など）を追加するには、[クエリを追加] をクリックします。キーワードごとに、[部分一致] または [完全一致] を選択します。
省略可: [時間範囲を追加] または [期間を追加] をクリックして、このコントロールを適用する時間範囲を 1 つ以上追加します。

注: カテゴリまたはクエリの利用条件と期間条件または日付範囲条件を指定すると、両方の条件が満たされた場合にのみコントロールが適用されます。
[続行] をクリックして [アクション] セクションに進みます。[固定する位置] で、商品を固定する位置をスライダーで指定します。ピンの値スライダーでは、0、負の数、整数以外の値は使用できません。

小売業向け Vertex AI Search では、1 つのコントロールのピンマップ内に 10 個のピンを配置できます。位置は 1 ～ 120（最大リクエストページサイズ）の任意の値に設定できます。

注: 2 ページ目への固定は、位置がリクエストページサイズより大きい場合、適用されません。たとえば、検索クエリでページサイズが 50 とリクエストされているにもかかわらず、固定ページが 75 ページに設定されている場合、検索結果ではその検索項目は無視されます。
[続行] をクリックして [サービス提供構成] セクションに進みます。コントロールを適用するサービス構成を選択し、コントロール設定を送信します。

新規作成または更新されたコントロールがライブトラフィックを提供できるようになるまでに、数分かかります。変更が適用されたかどうかは、コンソールの [評価] ページでテストできます。

新しいコントロールは、[コントロール] ページの [サービス提供コントロール] タブに表示されます。

curl

リクエスト本文に含まれる Control のコントロール ID とインスタンスを使用して、Control.create リクエストを行います。

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

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 --data '{
          "displayName": "DisplayName",
          "solutionTypes": "SOLUTION_TYPE_SEARCH",
          "searchSolutionUseCase": ["SEARCH_SOLUTION_USE_CASE_SEARCH"],
     "rule": {
            "condition": {
 "queryTerms": [
                {
                  "value": "Term1",
                  "fullMatch": "boolean: true / false"
                },
                {
                  "value": "Term2",
                  "fullMatch": "boolean: true / false"
                },
             ],
             "activeTimeRange": [
               {
                 "startTime": timestamp1,
                 "endTime": timestamp2
               },
               {
                 "startTime": timestamp3,
                 "endTime": timestamp4
               }
             ]
            },
            "pinAction": {
               "pinMap" :  {
                        "pin_position1": "product_id",
                      "pin_position2": "product_id>"
                    }
            }
              }
}' \
"https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/LOCATION/catalogs/default_catalog/controls?controlId=CONTROL_ID"

pin_position は 1 ～ 10 の整数にする必要があります。また、product_id はカタログに存在している必要があります。ピンマップ内で許可される要素の最大数は、コントロールごとに 10 個です。

次に、固定コントロールをサービス構成にアタッチします。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
-d '{
      "controlId": "CONTROL_ID"
  }' \
'https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/LOCATION/catalogs/default_catalog/servingConfigs/SERVING_CONFIG_ID:addControl'

この場合、CONTROL_ID は、前のセクションで作成した固定コントロール id にする必要があります。

サービス構成にコントロールを追加するには、ServingConfig.addControl メソッドを使用します。

このメソッドの詳細については、ServingConfig.addControl API リファレンスをご覧ください。
このメソッドの例については、サービス構成を管理をご覧ください。

最後に、設定をテストするために検索リクエストを行います。リクエストに固定コントロールが正常に適用されるようにするには、前の手順で作成したコントロールで指定したキーワードまたはカテゴリと一致するクエリキーワード（検索の場合）またはページカテゴリ（ブラウジングの場合）を使用します。

コンソール

Search for Retail コンソールの [評価] ページに移動します。

[評価] ページに移動
[検索] タブに移動します。
検索クエリフィールドにテストクエリを入力します。
[検索プレビュー] をクリックします。
結果を表示して、選択した商品が固定されていることを確認します。

curl

curl -s -X POST -H "Authorization: Bearer " -H "Content-Type: application/json"
--data "{'query': '','visitorId': ''}" \ "https://retail.googleapis.com/v2/projects/PROJECT/locations/global/catalogs/CATALOG/placements/default_search:search"

エラーチェックの制約

エラーチェックでは、次の制約に注意してください。

2 つの商品を同じ位置に固定することはできません。つまり、商品「a」と商品「b」の両方を位置 2 に配置することはできません。
一方、1 つの商品を複数の位置に固定することはできません。つまり、同じクエリで商品「a」を位置 #2 と #3 に同時に固定することはできません。
フィルタや並べ替えが適用されていないことを前提として、product_id はカタログに商品として存在している必要があります。

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

リダイレクト制御のチュートリアル

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

ブースト / 埋め込みコントロールを作成する

検索のブースト/埋め込みコントロールを作成する

コンソール

curl

レコメンデーションのブースト / 埋め込みコントロールを作成する

コンソール

curl

フィルタ オプションを作成する

コンソール

curl

リダイレクト コントロールを作成する

コンソール

curl

双方向の類義語コントロールを作成する

コンソール

curl

一方向の類義語コントロールを作成する

コンソール

curl

「関連付けなし」のコントロールを作成する

コンソール

curl

取り消しコントロールを作成する

コンソール

curl

代替コントロールを作成する

コンソール

curl

固定コントロールを作成する

コンソール

curl

コンソール

curl

エラーチェックの制約

フィルタオプションを作成する

リダイレクトコントロールを作成する