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 editEdit control icon for a control to change its settings and associated serving configs in the Edit control panel. Click the deleteDelete 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 editEdit control icon for a control to change its settings in the Edit control panel. Click the do_not_disturb_onRemove 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 pageIn the table row of the control you plan to remove, click deleteDelete.
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 pageOn 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 pageOn the Serving controls tab, click Import controls.
In the Import Serving Controls window:
Browse and select the Cloud Storage bucket and NDJSON file that contains the controls that you want to import.
Select the serving config that you want to associate the imported serving controls with.
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.