Console
Start free

Configure serving controls for search

Serving controls (also called controls) change the default behavior of how a request is served when results are returned. Serving controls act at a data-store level.

For example, controls can boost and bury results, filter entries from returned results, associate strings with each other as synonyms, or redirect results to specified URIs.

This page describes serving controls for search apps. For information about using serving controls with media recommendations, see Create and manage media serving configs.

About serving controls

To change the results of a request, first create a serving control. Then, attach that control to the serving config of a search app. A serving config configures metadata that's used to generate serving time results, such as search results or answers. A serving control only affects requests served by the app if the control is attached to the app's serving config.

Some controls, such as boost controls, have dependencies on data stores. If a data store is removed from an app, then any data store-dependent controls are also removed from that app and become inactive, but are not deleted.

Serving control types

The following types of serving controls are available:

Control Description Available for
Boost control Changes the returned order of results Search apps with data stores that support a schema, such as data stores that contain structured data, websites with structured data (advanced website indexing), unstructured data with metadata, or media data
Filter control Removes entries from returned results Search apps with data stores that support a schema, such as data stores that contain structured data, websites (advanced website indexing), unstructured data with metadata, or media data
Synonyms control Associates queries with each other Search apps with website (advanced website indexing), structured, unstructured, or media data stores
Redirect control Redirects to a specified URI All search apps
Promote control Promotes a specified link for a query All search apps

About conditions

When creating a control, you can optionally define a condition that determines when the control is applied. Conditions are defined using condition fields. The following condition fields are available:

If multiple conditions are specified for a control, the control is applied to the search request when both condition types are satisfied. If multiple values for the same condition are specified, only one of the values needs to match for that condition to be satisfied.

For example, consider the following condition with two query terms specified:

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

The condition will be satisfied for a request with SearchRequest.query="gShoe" or a request with SearchRequest.query="gBoot", but won't be satisfied with SearchRequest.query="gSandal" or any other string.

If no conditions are specified, the control is always applied.

For more information, see the Condition field in the API reference.

Create and attach boost serving controls

A boost serving control reorders the results by promoting or demoting them based on the applied conditions. Boost works by applying a multiplying factor to the ranking of a document that meets the boost conditions.

Use the following instructions to create a boost serving control.

Console

To create and attach a boost control using the Google Cloud console, do the following:

  1. In the Google Cloud console, go to the AI Applications page.

    AI Applications

  2. Select the app for which you want to create the boost control.

  3. On your app's overview page, make sure you are on the System overview tab.

  4. In the Signal stage, click the Boost/Bury tile.

  5. Click Create control.

  6. For Name Your Control, enter a name for your boost/bury control and click Continue.

  7. For Set Rule Scope & Impact, define the actions that you want to trigger with this control:

    1. Select a data store from the list. If you want the action to be applied to multiple data stores, create a control for each data store.

    2. For Filter, add a filter.

      This is a string specifying requirements that must be met by the document. Only if the document matches all the requirements, the boost condition is applied. Otherwise, there is no change. If you don't specify a filter, then the boost is applied to all documents in the data store.

      To understand how to write filter expressions, see Filter custom search for structured or unstructured data and Syntax for advanced website indexing.

    3. For Boost/bury value, select a boost/bury value in the range [-1, 1] using the slider. The slider moves in steps of 0.01.

    4. Click Continue.

  8. For Optional: When This Rule Activates, set the following conditions that trigger the control. If no conditions are configured, the control is always in effect:

    1. Add Partial match query terms. The control takes effect when these query terms match partially.

    2. Add Exact match query terms. The control takes effect when these query terms match exactly.

    3. To add an active time range, click Add time range and set Start Time 1 and End Time 1. This defines the window when the condition is active. You can add a maximum of 10 time ranges.

    4. Click Continue.

  9. For Additional settings, choose if you want to activate the rule:

    1. If you don't want to activate this control as soon as it's created, turn off Publish this control immediately.

    2. Click Continue.

  10. Click Submit.

REST

A boost serving control is defined as a control with a boostAction.

Use the following instructions to create a boost serving control.

For field details, see the engines.controls API reference and the engines.controls.create API reference.

  1. Find your app ID. If you already have your app ID, skip to the next step.

    1. In the Google Cloud console, go to the AI Applications page.

      Go to Apps

    2. On the Apps page, find the name of your app and get the app's ID from the ID column.

  2. Run the following curl commands to create your controls.

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

    Replace the following:

  3. Attach the control to the app's serving config using the engines.servingConfigs.patch method.

    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"]
}'

    Replace BOOST_ID_N with the control IDs that you created in the previous step.

Create and attach filter serving controls

A filter serving control filters by a given criteria or rule. For example, for hotel site, you can apply a filter for (price < 175 AND petfriendly = "true") that only shows pet-friendly hotels under the price of $175 USD per night.

A filter serving control is defined as a control with a filterAction.

Use the following instructions to create a filter serving control.

For field details, see the engines.controls API reference and the engines.controls.create API reference.

Console

To create and attach a filter control using the Google Cloud console, do the following:

  1. In the Google Cloud console, go to the AI Applications page.

    AI Applications

  2. Select the app for which you want to create the promote control.

  3. On your app's overview page, make sure you are on the System overview tab.

  4. In the Signal stage, click the Filter tile.

  5. Click Create control.

  6. For Name Your Control, enter a name for your filter control and click Continue.

  7. For Rule Scope & Impact, set the following:

    1. Select a data store from the list that you want to attach this filter control to. If you want the action to be applied to multiple data stores, create a control for each data store.

    2. For Filter, tell the rule which specific items to look for. You can combine search terms using AND, OR, NOT, and group terms with (). For exact phrases, use quotes "". For example: status: "open" AND priority:"P1".

      To understand how to write filter expressions, see Filter custom search for structured or unstructured data and Syntax for advanced website indexing.

    3. Click Continue.

  8. For Optional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:

    1. Add Partial match query terms. The control takes effect when these query terms match partially.

    2. Add Exact match query terms. The control takes effect when these query terms match exactly.

    3. To add an active time range, click Add time range and set Start Time 1 and End Time 1. This defines the window when the condition is active. You can add a maximum of 10 time ranges.

    4. Click Continue.

  9. For Additional settings, choose if you want to activate the rule:

    1. If you don't want to activate this control as soon as it's created, turn off Publish this control immediately.

    2. Click Continue.

  10. Click Submit.

REST

  1. Find your app ID. If you already have your app ID, skip to the next step.

    1. In the Google Cloud console, go to the AI Applications page.

      Go to Apps

    2. On the Apps page, find the name of your app and get the app's ID from the ID column.

  2. Run the following curl commands to create your controls.

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

    Replace the following:

    • PROJECT_ID: the number or ID of your Google Cloud project.
    • APP_ID: the ID of the Agent Search app.
    • CONTROL_ID: a unique identifier for the control. The ID can contain [1-63] characters that can be letters, digits, hyphens, and underscores.
    • DISPLAY_NAME: the human-readable name for the control. Google recommends that this name provide an indication of when or why to use the control. Must be a UTF-8 encoded string with length [1,128].
    • USE_CASE: must be either SEARCH_USE_CASE_SEARCH or SEARCH_USE_CASE_BROWSE. If SEARCH_USE_CASE_BROWSE is specified, then Condition.queryTerms can't be used in the condition.
    • CONDITION: an optional field that defines when the control should be applied. Contains the following fields:
      • VALUE: the specific query value to match against. It's a lowercase UTF-8 string with length [1, 5000]. If FULL_MATCH_1 is true, this field can have at most three space-separated terms.
      • FULL_MATCH: a boolean that indicates whether the search query needs to exactly match the query term. When set to true, it requires SearchRequest.query to completely match the queryTerm.value. When set to false, it requires SearchRequest.query to contain queryTerm.value as a substring.
      • START_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the start of a time range.
      • END_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the end of a time range.

    • FILTER: a string specifying requirements that must be met by the document. If the document matches all the requirements, the document is returned in the results. Otherwise, the document is not in the results.

      For more information, see filterAction. For information about the filtering syntax, see Filter expression syntax and Syntax for advanced website indexing.

  3. Attach the control to the app's serving config using the engines.servingConfigs.patch method.

    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"]
}'

    Replace FILTER_ID_N with the control IDs that you created in the previous step.

Create and attach synonyms serving controls

A synonyms serving control is defined as a control with a synonymsAction.

Use the following instructions to create a synonyms serving control.

For field details, see the engines.controls API reference and the engines.controls.create API reference.

Console

To create and attach a synonmys control using the Google Cloud console, do the following:

  1. In the Google Cloud console, go to the AI Applications page.

    AI Applications

  2. Select the app for which you want to create the synonyms control.

  3. On your app's overview page, make sure you are on the System overview tab.

  4. In the Prepare stage, click the Synonyms tile.

  5. Click Create control.

  6. For Name Your Control, enter a name for your synonyms control and click Continue.

  7. For Rule Scope & Impact:

    1. Enter the synonyms you want to have considered in the control. For example, enter cats followed by a return (not comma), then feline.

    2. When you are finished entering synonyms, click Continue.

  8. For Optional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:

    1. To add an active time range, click Add time range and set Start Time 1 and End Time 1. This defines the window when the condition is active. You can add a maximum of 10 time ranges.

    2. Click Continue.

  9. For Additional settings, choose if you want to activate the rule:

    1. If you don't want to activate this control as soon as it's created, turn off Publish this control immediately.

    2. Click Continue.

  10. Click Submit.

REST

  1. Run the following curl commands to create your controls.

    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"]
 }
}'

    Replace the following:

    • PROJECT_ID: the number or ID of your Google Cloud project.
    • APP_ID: the ID of the Agent Search app.
    • CONTROL_ID: a unique identifier for the control. The ID can contain [1-63] characters that can be letters, digits, hyphens, and underscores.
    • DISPLAY_NAME: the human-readable name for the control. Google recommends that this name provide an indication of when or why to use the control. Must be a UTF-8 encoded string with length [1,128].
    • USE_CASE: must be either SEARCH_USE_CASE_SEARCH or SEARCH_USE_CASE_BROWSE. If SEARCH_USE_CASE_BROWSE is specified, then Condition.queryTerms can't be used in the condition.
    • CONDITION: an optional field that defines when the control should be applied. Contains the following fields:
      • VALUE: the specific query value to match against. It's a lowercase UTF-8 string with length [1, 5000]. If FULL_MATCH_1 is true, this field can have at most three space-separated terms.
      • FULL_MATCH: a boolean that indicates whether the search query needs to exactly match the query term. When set to true, it requires SearchRequest.query to completely match the queryTerm.value. When set to false, it requires SearchRequest.query to contain queryTerm.value as a substring.
      • START_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the start of a time range.
      • END_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the end of a time range.
    • SYNONYMS_N: a list of strings that are associated with each other, making it more likely for each to show similar results. While it's more likely that you get similar results, when you search for each of the synonym entries, you might not receive all the relevant results for all the associated synonyms. You must specify at least two synonyms and you can specify up to 100 synonyms. Each synonym must be UTF-8 encoded and in lowercase. No duplicate strings are allowed. For example, you can add "pixel", "android phone", and "google phone" as synonyms. For more information, see synonymsAction.

  2. Attach the control to the app's serving config using the engines.servingConfigs.patch method.

    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"]
}'

    Replace SYNONYMS_ID_N with the control IDs that you created in the previous step.

Create and attach redirect serving controls

A redirect serving control allows redirecting users to a provided URI. Redirect controls are defined as a control with a redirectAction.

Use the following instructions to create a redirect serving control.

For field details, see the engines.controls API reference and the engines.controls.create API reference.

  1. Find your app ID. If you already have your app ID, skip to the next step.

    1. In the Google Cloud console, go to the AI Applications page.

      Go to Apps

    2. On the Apps page, find the name of your app and get the app's ID from the ID column.

  2. Run the following curl commands to create your controls.

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

    Replace the following:

    • PROJECT_ID: the number or ID of your Google Cloud project.
    • APP_ID: the ID of the Agent Search app.
    • CONTROL_ID: a unique identifier for the control. The ID can contain [1-63] characters that can be letters, digits, hyphens, and underscores.
    • DISPLAY_NAME: the human-readable name for the control. Google recommends that this name provide an indication of when or why to use the control. Must be a UTF-8 encoded string with length [1,128].
    • USE_CASE: must be either SEARCH_USE_CASE_SEARCH or SEARCH_USE_CASE_BROWSE. If SEARCH_USE_CASE_BROWSE is specified, then Condition.queryTerms can't be used in the condition.
    • CONDITION: an optional field that defines when the control should be applied. Contains the following fields:
      • VALUE: the specific query value to match against. It's a lowercase UTF-8 string with length [1, 5000]. If FULL_MATCH_1 is true, this field can have at most three space-separated terms.
      • FULL_MATCH: a boolean that indicates whether the search query needs to exactly match the query term. When set to true, it requires SearchRequest.query to completely match the queryTerm.value. When set to false, it requires SearchRequest.query to contain queryTerm.value as a substring.
      • START_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the start of a time range.
      • END_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the end of a time range.
    • REDIRECT_URI_N: a URI where you are redirected. Can have a maximum length of 2000 characters. For example, if the value of the query term is "support", you can set a redirect to your technical support page instead of returning (or failing to return) search results for "support". In this example, the redirect URI becomes "https://www.example.com/support". For more information, see redirectAction.

  3. Attach the control to the app's serving config using the engines.servingConfigs.patch method.

    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"]
}'

    Replace REDIRECT_ID_N with the control IDs that you created in the previous step.

Create and attach promote serving controls

A promote serving control lets you display a link as a promoted result and is available for the following types of search data stores:

Promote controls are defined using a promoteAction.

To successfully create a promote control, one of the following fields is required in the creation request:

That is, for basic website search, you must either specify the queryTerms field with fullMatch set to true or specify the queryRegex field. For all other types of search, specify the queryTerms field with fullMatch set to true or false.

Use the following instructions to create a promote serving control.

For field details, see the engines.controls API reference and the engines.controls.create API reference.

Console

To create and attach a promote control for a basic website search app using the Google Cloud console, do the following. To create a promote control for other app types, follow the instructions on the REST tab.

  1. In the Google Cloud console, go to the AI Applications page.

    AI Applications

  2. Select the app for which you want to create the filter control.

  3. On your app's overview page, make sure you are on the System overview tab.

  4. In the Signal stage, click the Promote tile.

  5. Click Create control.

  6. For Name Your Control, enter a name for your promote control and click Continue.

  7. For Rule Scope & Impact, set the following:

    1. Select a data store from the list that you want to attach this filter control to. If you want the action to be applied to multiple data stores, create a control for each data store.

    2. Enter the Promote title, such as View latest video.

    3. Enter the Promote URL, such as the location of the video.

    4. Enter the Promote image URL, such as a thumbnail or screenshot.

    5. Enter a brief Promote description, such as what the video is about. The maximum is 250 characters.

  8. For Optional: When This Rule Activates, define the actions that you want to trigger with this control. If no conditions are configured, the control is always in effect:

    1. Add Exact match query terms. The control takes effect when these query terms match exactly.

    2. To add an active time range, click Add time range and set Start Time 1 and End Time 1. This defines the window when the condition is active. You can add a maximum of 10 time ranges.

    3. Click Continue.

  9. Click Submit.

REST

  1. Run the following curl commands to create your controls.

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

    Replace the following:

    • PROJECT_ID: the number or ID of your Google Cloud project.
    • APP_ID: the ID of the Agent Search app.
    • CONTROL_ID: a unique identifier for the control. The ID can contain [1-63] characters that can be letters, digits, hyphens, and underscores.
    • DISPLAY_NAME: the human-readable name for the control. Google recommends that this name provide an indication of when or why to use the control. Must be a UTF-8 encoded string with length [1,128].
    • USE_CASE: must be either SEARCH_USE_CASE_SEARCH or SEARCH_USE_CASE_BROWSE. If SEARCH_USE_CASE_BROWSE is specified, then Condition.queryTerms can't be used in the condition.
    • Condition: an optional object that defines when the control should be applied. Contains the following fields:
      • queryTerms: It can't be used with the queryRegex field.
        • VALUE: the specific query value to match against. It's a lowercase UTF-8 string with length [1, 5000].
      • activeTimeRange:
        • START_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the start of a time range.
        • END_TIMESTAMP: a timestamp in RFC 3339 UTC "Zulu" format to indicate the end of a time range.
      • queryRegex: only available for data stores with basic website search. This field can't be used with the queryTerms field.
        • VALUE_REGEX: a regular expression to match the query against.
    • DATA_STORE_RESOURCE_PATH: the full resource path of the data store whose search results contain the promoted URL. The format of the full resource path is projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. This data store must be attached to the engine specified in the request.
    • DOCUMENT_RESOURCE_PATH: a field to specify the document resource path of the document to be promoted:
      • For search data stores with structured and unstructured data, you must provide either the document resource path in the DOCUMENT_RESOURCE_PATH field, the URI in the URI field, or both. The format of the full resource path is projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
      • For website data stores, this field must be unset and set the URI field instead.
    • TITLE: a required field to specify the title of the document or the web page to be promoted. This title is displayed in the search result.
    • URI: a required field to specify the URI link where the search result leads the user. This URI need not be included in the data store.
      • For search data stores with structured and unstructured data, you must provide either the document resource path in the DOCUMENT_RESOURCE_PATH field, the URI in the URI field, or both.
      • For website data stores, this is a required field and you must set it.
    • DESCRIPTION: an optional field to describe the document or web page to be promoted, which is displayed in the search result.
    • ENABLED_TRUE|FALSE: an optional boolean field to indicate whether the promote control is turned on and attached to the app. This field is applicable to website data stores with basic website search only. When you set this field to false, the promote serving control is turned off and for the control to take effect, you must update the control by enabling it, as explained in the next step. For more information, see promoteAction.

  2. For all search apps except for basic website search, attach the control to the app's serving config using the engines.servingConfigs.patch method. The order in which the promoteControlIds are attached in the following request is the order in which the promoted results are returned.

    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"]
}'

    Replace PROMOTE_ID_N with the control IDs that you created in the previous step.

  3. Optional: For basic website search, you need not attach the control to the app's serving config. However, for basic website search you can turn a promote control on or off after the control is created, call the engines.control.patch method.

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

Example

When you send a search request to the app with a query that matches the query or query regular expression specified for the promote control, the promoted link appears in the response.

For example, suppose that you create a promote control with the following configuration in a data store with basic website search:

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

Then, you send the following search request:

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

You should receive a JSON response similar to the following truncated response. The response contains the searchLinkPromotions field that contains the promoted link.

{
 "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"
    }
  ]
}

Modify serving controls

To modify a control's configuration, do the following:

  1. In the Google Cloud console, go to the AI Applications page.

    AI Applications

  2. Select the app for which you want to modify controls.

  3. In the System overview tab, select either the Prepare or Signal stage where your control is located.

  4. In the list of the app's controls, click for a control that you want to modify and click Edit.

  5. Edit the control in the Edit control pane:

    1. To enable or disable a control, in the list of the app's filter controls, click for a control that you want to enable or disable and click Enable or Disable, respectively.

    2. To delete a control, in the list of the app's controls, click for a control that you want to delete and click Delete.

What's next