REST Resource: projects.locations.collections.dataStores.controls

Resource: Control

Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on SolutionType.

JSON representation 
{
  "name": string,
  "displayName": string,
  "associatedServingConfigIds": [
    string
  ],
  "solutionType": enum (SolutionType),
  "useCases": [
    enum (SearchUseCase)
  ],
  "conditions": [
    {
      object (Condition)
    }
  ],

  // Union field action can be only one of the following:
  "boostAction": {
    object (BoostAction)
  },
  "filterAction": {
    object (FilterAction)
  },
  "redirectAction": {
    object (RedirectAction)
  },
  "synonymsAction": {
    object (SynonymsAction)
  },
  "promoteAction": {
    object (PromoteAction)
  }
  // End of list of possible types for union field action.
}
Fields
name

string

Immutable. Fully qualified name projects/*/locations/global/dataStore/*/controls/*
displayName

string

Required. Human readable name. The identifier used in UI views.

Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
associatedServingConfigIds[]

string

Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
solutionType

enum (SolutionType)

Required. Immutable. What solution the control belongs to.

Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
useCases[]

enum (SearchUseCase)

Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solutionType is SolutionType.SOLUTION_TYPE_SEARCH.
conditions[]

object (Condition)

Determines when the associated action will trigger.

Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.

Union field action. Actions are restricted by Vertical and Solution

Required. action can be only one of the following:
boostAction

object (BoostAction)

Defines a boost-type control
filterAction

object (FilterAction)

Defines a filter-type control Currently not supported by Recommendation
redirectAction

object (RedirectAction)

Defines a redirect-type control.
synonymsAction

object (SynonymsAction)

Treats a group of terms as synonyms of one another.
promoteAction

object (PromoteAction)

Promote certain links based on predefined trigger queries.

This now only supports basic site search.

BoostAction

Adjusts order of products in returned list.

JSON representation 
{
  "boost": number,
  "filter": string,
  "dataStore": string
}
Fields
boost

number

Required. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
filter

string

Required. Specifies which products to apply the boost to.

If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
dataStore

string

Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store

FilterAction

Specified which products may be included in results. Uses same filter as boost.

JSON representation 
{
  "filter": string,
  "dataStore": string
}
Fields
filter

string

Required. A filter to apply on the matching condition results.

Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
dataStore

string

Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store

RedirectAction

Redirects a shopper to the provided URI.

JSON representation 
{
  "redirectUri": string
}
Fields
redirectUri

string

Required. The URI to which the shopper will be redirected.

Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.

SynonymsAction

Creates a set of terms that will act as synonyms of one another.

Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy".

JSON representation 
{
  "synonyms": [
    string
  ]
}
Fields
synonyms[]

string

Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.

PromoteAction

Promote certain links based on some trigger queries.

Example: Promote shoe store link when searching for shoe keyword. The link can be outside of associated data store.

JSON representation 
{
  "dataStore": string,
  "searchLinkPromotion": {
    object (SearchLinkPromotion)
  }
}
Fields
dataStore

string

Required. data store with which this promotion is attached to.

SearchLinkPromotion

Promotion proto includes uri and other helping information to display the promotion.

JSON representation 
{
  "title": string,
  "uri": string,
  "imageUri": string,
  "description": string,
  "enabled": boolean
}
Fields
title

string

Required. The title of the promotion. Maximum length: 160 characters.
uri

string

Required. The URL for the page the user wants to promote.
imageUri

string

Optional. The promotion thumbnail image url.
description

string

Optional. The Promotion description. Maximum length: 200 characters.
enabled

boolean

Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to.

This flag is used for basic site search only.

SearchUseCase

Defines a further subdivision of SolutionType. Specifically applies to SOLUTION_TYPE_SEARCH.

Enums
SEARCH_USE_CASE_UNSPECIFIED Value used when unset. Will not occur in CSS.
SEARCH_USE_CASE_BROWSE Browse use case. Expects the traffic has an empty query.

Condition

Defines circumstances to be checked before allowing a behavior

JSON representation 
{
  "queryTerms": [
    {
      object (QueryTerm)
    }
  ],
  "activeTimeRange": [
    {
      object (TimeRange)
    }
  ],
  "queryRegex": string
}
Fields
queryTerms[]

object (QueryTerm)

Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set.

Maximum of 10 query terms.
activeTimeRange[]

object (TimeRange)

Range of time(s) specifying when condition is active.

Maximum of 10 time ranges.
queryRegex

string

Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. This is currently supporting promotion use case.

QueryTerm

Matcher for search request query

JSON representation 
{
  "value": string,
  "fullMatch": boolean
}
Fields
value

string

The specific query value to match against

Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if fullMatch is true. Cannot be an empty string. Maximum length of 5000 characters.
fullMatch

boolean

Whether the search query needs to exactly match the query term.

TimeRange

Used for time-dependent conditions.

JSON representation 
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

Start of time range.

Range is inclusive.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endTime

string (Timestamp format)

End of time range.

Range is inclusive. Must be in the future.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Methods

create

 Creates a Control.

delete

 Deletes a Control.

get

 Gets a Control.

list

 Lists all Controls by their parent DataStore.

patch

 Updates a Control.