Retail is being renamed to Vertex AI Search for retail. We are in the process of updating content to reflect the new branding.

Manage serving controls

This page describes how to view, edit, delete, export, and import serving controls.

For general information about serving controls and instructions on how to create serving controls, see About serving controls and Create serving controls.

View and edit serving controls

You can view serving controls for Vertex AI Search for retail using the console and the API.

View and edit serving controls in the console

The Serving Controls tab of the Controls page lists all of your serving controls and their associated serving configs. Click the Edit control icon for a control to change its settings and associated serving configs in the Edit control panel. Click the Delete control icon for a control to delete it, which also removes it from all serving configs.

You can also see and edit the controls for a specific serving config on the Serving Configs page. Click a serving config to see its Details page, which lists all serving controls for that configuration. Click the Edit control icon for a control to change its settings in the Edit control panel. Click the Remove control icon to dissociate the control from the serving config (this does not delete the control).

It takes a few minutes for newly created or updated controls to be ready to serve live traffic. You can test if your changes have been applied on the console Evaluate page.

View serving controls inline

To see a single serving control inline, use Control.get.

For more about this method, see the Control.get API reference.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID'

To list multiple serving controls inline, use Controls.list.

Optionally, you can use the parameter pageSize to set a maximum number of results to return. If more results are available, the list response includes a page token. You can pass a page token in the pageToken parameter of a list request to retrieve the next page of results.

To list only the controls associated with a certain serving config, use the filter query parameter to specify the serving config ID.

For more about this method, see the Control.list API reference.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=servingConfig=SERVING_CONFIG_ID

Patch serving controls inline

To update fields in a serving control, use Controls.patch and include an instance of Control in the request body. Specify the fields to update with the updateMask parameter, or leave it unset to update all supported fields.

For more about this method, see the Controls.patch API reference.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
      "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID",
      "FIELD_NAME_1": "NEW_FIELD_VALUE_1"
      "FIELD_NAME_2": "NEW_FIELD_VALUE_2"
    }' \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/CONTROL_ID?updateMask=FIELD_NAME_1,FIELD_NAME_2'

Add controls to serving configs inline

To add a control to a serving config, use ServingConfig.addControl.

For more about this method, see the ServingConfig.addControl API reference.

For an example of this method, see Manage serving configs.

Remove controls from serving configs inline

To remove a control from a serving config, use ServingConfig.removeControl.

For more about this method, see the ServingConfig.addControl API reference.

For an example of this method, see Manage serving configs.

Delete a serving control

You can delete a serving control from the console or inline using the Controls.delete method.

Delete a serving control in the console

Delete a serving control to remove that control from all serving configs that are using it.

Go to the Controls page in the Search for Retail console.

Go to the Controls page
In the table row of the control you plan to remove, click Delete.
In the confirmation window, click Delete to complete the deletion.

Delete a serving control inline

To delete serving controls inline, use Controls.delete.

For more about this method, see the Controls.delete API reference.

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
'https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/controls/SERVING_CONTROL_ID'

Export serving controls

You can export your serving controls to a file in a Cloud Storage bucket.

There are two reasons that you might want to export and import serving controls:

To move serving controls from one project to another.
To perform a bulk edit on all or some serving controls. Export the serving controls, edit the exported file, and then import the file to change or add serving controls.

You can export and import through the Search for Retail console. When you export serving controls, you export all the serving controls in the project.

To export serving controls, do the following:

Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Export controls.
In the Export Serving Controls window, select the Cloud Storage bucket to which you want to export the controls file.
Click Export.

The exported controls are saved to a NDJSON file in the selected bucket with a name in the following format:
```
projects_PROJECT_ID_TIMESTAMP_exported_controls.ndjson
```
After the export operation completes, you can see the operation status in the Bulk import, export, delete activities list in the Export activity window. Open the Export activity window by clicking Show in the message window or by following the instructions in See status for a specific integration operation.

Import serving controls

To add serving controls or modify existing ones in bulk, you can make your changes in an exported controls file. You can then import them into the original project or into a different project.

Things to know about importing serving controls:

You can't import a serving control file if it contains both search and recommendations serving controls.
When you import serving controls, all the serving controls in the file become associated with the serving config that you specify on import. If a serving control is already associated with another serving config in the project, that association is also maintained.

To import serving controls, do the following:

Edit and review an exported serving control file and place the file in a Cloud Storage bucket. (To export serving controls, see the preceding task Export serving controls.)

Ensure that the file contains only search serving controls or only recommendations serving controls. You cannot import a file that contains both types.
Go to the Controls page in the Search for Retail console.

Go to the Controls page
On the Serving controls tab, click Import controls.
In the Import Serving Controls window:
1. Browse and select the Cloud Storage bucket and NDJSON file that contains the controls that you want to import.
2. Select the serving config that you want to associate the imported serving controls with.
3. Review the Import Preview plan. The controls that will be created are displayed on the New tab and the controls that will be modified are displayed on the Modified tab.
Click Import.

A long-running operation is started to import the new and modified controls.
After the import operation completes, you can see the operation status in the Controls tab of the Activity status window. Open the Activity status window by clicking Show in the message window or by following the instructions in See status for a specific integration operation.