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

资源：Control

定义在提供服务期间采用的条件行为。必须附加到 ServingConfig 才能在投放时考虑。允许的操作取决于 SolutionType。

JSON 表示法 
{
  "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.
}
字段
name

string

不可变。完全限定名称 projects/*/locations/global/dataStore/*/controls/*
displayName

string

必需。直观易懂的名称。界面视图中使用的标识符。

必须是 UTF-8 编码的字符串。长度限制为 128 个字符。否则，系统会抛出 INVALID ARGUMENT 错误。
associatedServingConfigIds[]

string

仅限输出。此控件所附加到的所有 ServingConfig ID 的列表。更改后，最多可能需要 10 分钟才能更新。
solutionType

enum (SolutionType)

必需。不可变。控制变量所属的解决方案。

必须与资源的垂直行业兼容。否则，系统会抛出 INVALID ARGUMENT 错误。
useCases[]

enum (SearchUseCase)

指定控制变量的应用场景。影响可设置哪些条件字段。仅适用于 SOLUTION_TYPE_SEARCH。目前，每个控制变量只允许一个用例。当 solutionType 为 SolutionType.SOLUTION_TYPE_SEARCH 时，必须设置此字段。
conditions[]

object (Condition)

确定关联操作的触发时间。

省略此属性可始终应用相应操作。目前，只能指定一个条件。否则，系统会抛出 INVALID ARGUMENT 错误。

联合字段 action。操作受行业和解决方案限制

必需。action 只能是下列其中一项：
boostAction

object (BoostAction)

定义了提升型控制变量
filterAction

object (FilterAction)

定义了过滤类型的控件，目前不受 Recommendation 支持
redirectAction

object (RedirectAction)

定义重定向类型的控制变量。
synonymsAction

object (SynonymsAction)

将一组字词视为彼此的同义词。
promoteAction

object (PromoteAction)

根据预定义的触发查询来推广特定链接。

BoostAction

调整返回列表中的商品顺序。

JSON 表示法 
{
  "boost": number,
  "filter": string,
  "dataStore": string,

  // Union field boost_spec can be only one of the following:
  "fixedBoost": number,
  "interpolationBoostSpec": {
    object (InterpolationBoostSpec)
  }
  // End of list of possible types for union field boost_spec.
}
字段
boost
(deprecated)

number

升位的强度，应介于 [-1, 1] 之间。设为负值代表降位。默认值为 0.0（无操作）。
filter

string

必需。指定要对哪些商品应用加推。

如果未提供过滤条件，系统将提升所有产品（无操作）。语法文档：https://cloud.google.com/retail/docs/filter-and-order。长度上限为 5,000 个字符。否则，系统会抛出 INVALID ARGUMENT 错误。
dataStore

string

必需。指定可以使用该控件增强哪些数据存储区的文档。完整的数据存储区名称，例如 projects/123/locations/global/collections/default_collection/dataStores/default_data_store
联合字段 boost_spec。基于常量值提升或自定义排名的提升规范。boost_spec 只能是下列其中一项：
fixedBoost

number

可选。升位的强度，应介于 [-1, 1] 之间。设为负值代表降位。默认值为 0.0（无操作）。
interpolationBoostSpec

object (InterpolationBoostSpec)

可选。基于客户定义的属性值的自定义排名的复杂规范。

InterpolationBoostSpec

基于客户指定属性值的自定义排名规范。与上述简单的（条件、提升）组合相比，它可提供更多用于自定义排名的控制变量。

JSON 表示法 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
字段
fieldName

string

可选。将用于确定加权幅度的字段的名称。
attributeType

enum (AttributeType)

可选。用于确定加推幅度的属性类型。属性值可以从指定 fieldName 的字段值派生而来。对于数值型，则很简单，即 attributeValue = numerical_field_value。不过，对于新鲜度，attributeValue = (time.now() - datetime_field_value)。
interpolationType

enum (InterpolationType)

可选。要应用于连接下列控制点的插值类型。
controlPoints[]

object (ControlPoint)

可选。用于定义曲线的控制点。单调函数（通过上面的 interpolationType 定义）会通过此处列出的控制点。

AttributeType

要应用自定义排名的属性（或函数）。

枚举
ATTRIBUTE_TYPE_UNSPECIFIED 未指定 AttributeType。
NUMERICAL 数值字段的值将用于动态更新加推量。在这种情况下，控制点的 attributeValue（即 x 值）将是指定了 boostAmount 的数值字段的实际值。
FRESHNESS 对于新鲜度使用情形，属性值将是当前时间与指定日期时间字段中的日期之间的时长。该值必须采用 XSD dayTimeDuration 值（ISO 8601 时长值的受限子集）的格式。此格式的模式为：[nD][T[nH][nM][nS]]。例如，5D、3DT12H30M、T24H。

InterpolationType

要应用的插值类型。默认值为线性（分段线性）。

枚举
INTERPOLATION_TYPE_UNSPECIFIED 未指定插值类型。在这种情况下，它会默认设置为线性。
LINEAR 系统将应用分段线性插值。

ControlPoint

用于定义曲线的控制点。通过这些控制点定义的曲线只能单调递增或递减（可以包含常量值）。

JSON 表示法 
{
  "attributeValue": string,
  "boostAmount": number
}
字段
attributeValue

string

可选。可以是以下值之一：1. 数值字段值。2. 新鲜度时长规范：该值必须采用 XSD dayTimeDuration 值（ISO 8601 时长值的受限子集）的格式。此格式的模式为：[nD][T[nH][nM][nS]]。
boostAmount

number

可选。如果 attributeValue 的评估结果为上述指定的值，则用于提升得分的值（介于 -1 到 1 之间）。

FilterAction

指定哪些商品可包含在结果中。使用与提升相同的过滤条件。

JSON 表示法 
{
  "filter": string,
  "dataStore": string
}
字段
filter

string

必需。要应用于匹配条件结果的过滤条件。

必需的语法文档：https://cloud.google.com/retail/docs/filter-and-order。长度上限为 5,000 个字符。否则，系统会抛出 INVALID ARGUMENT 错误。
dataStore

string

必需。指定可以使用该控件过滤哪些数据存储区的文档。完整的数据存储区名称，例如 projects/123/locations/global/collections/default_collection/dataStores/default_data_store

RedirectAction

将买家重定向到所提供的 URI。

JSON 表示法 
{
  "redirectUri": string
}
字段
redirectUri

string

必需。买家将被重定向到的 URI。

必需。URI 的长度必须小于或等于 2000 个字符。否则，系统会抛出 INVALID ARGUMENT 错误。

SynonymsAction

创建一组将互为同义词的字词。

示例：“happy”也会被视为“glad”，“glad”也会被视为“happy”。

JSON 表示法 
{
  "synonyms": [
    string
  ]
}
字段
synonyms[]

string

定义一组同义词。最多可以指定 100 个同义词。必须指定至少 2 个同义词。否则，系统会抛出 INVALID ARGUMENT 错误。

PromoteAction

根据某些触发查询来推广特定链接。

示例：当用户搜索 shoe 关键字时，宣传鞋店链接。链接可以位于关联的数据存储区之外。

JSON 表示法 
{
  "dataStore": string,
  "searchLinkPromotion": {
    object (SearchLinkPromotion)
  }
}
字段
dataStore

string

必需。相应促销活动所关联的数据存储区。

SearchLinkPromotion

促销活动 proto 包含用于显示促销活动的 URI 和其他帮助信息。

JSON 表示法 
{
  "title": string,
  "uri": string,
  "document": string,
  "imageUri": string,
  "description": string,
  "enabled": boolean
}
字段
title

string

必需。促销活动的标题。长度上限：160 个字符。
uri

string

可选。用户想要推广的网页的网址。必须为网站搜索设置。对于其他垂直行业，此属性是可选的。
document

string

可选。用户想要推广的 Document。对于网站搜索，请保持未设置状态，仅填充 URI。可与 URI 一起设置。
imageUri

string

可选。促销缩略图网址。
description

string

可选。宣传广告的内容描述。长度上限：200 个字符。
enabled

boolean

可选。对于与附加了相应促销活动的服务控件的父级相关联的任何服务配置，系统都会返回已启用的促销活动。

此标志仅用于基本网站搜索。

SearchUseCase

定义 SolutionType 的进一步细分。专门适用于 SOLUTION_TYPE_SEARCH。

枚举
SEARCH_USE_CASE_UNSPECIFIED 未设置时使用的值。不会在 CSS 中发生。
SEARCH_USE_CASE_BROWSE 浏览使用情形。预期流量具有空的 query。

条件

定义在允许某种行为之前要检查的情况

JSON 表示法 
{
  "queryTerms": [
    {
      object (QueryTerm)
    }
  ],
  "activeTimeRange": [
    {
      object (TimeRange)
    }
  ],
  "queryRegex": string
}
字段
queryTerms[]

object (QueryTerm)

仅搜索要与查询匹配的字词列表。如果已设置 Condition.query_regex，则无法设置此字段。

最多 10 个查询字词。
activeTimeRange[]

object (TimeRange)

指定条件处于有效状态的时间范围。

最多 10 个时间范围。
queryRegex

string

可选。用于匹配整个搜索查询的查询正则表达式。如果已设置 Condition.query_terms，则无法设置此字段。仅支持基本网站搜索广告投放控制。

QueryTerm

搜索请求查询的匹配器

JSON 表示法 
{
  "value": string,
  "fullMatch": boolean
}
字段
value

string

要匹配的具体查询值

必须采用小写形式，必须采用 UTF-8 编码。如果 fullMatch 为 true，则最多可以包含 3 个以空格分隔的字词。不得为空字符串。长度上限为 5,000 个字符。
fullMatch

boolean

搜索查询是否需要与查询字词完全匹配。

TimeRange

用于时间相关条件。

JSON 表示法 
{
  "startTime": string,
  "endTime": string
}
字段
startTime

string (Timestamp format)

时间范围的开始时间。

范围包含边界值。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

时间范围的结束时间。

范围包含边界值。必须是将来的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

方法

create

 创建控制变量。

delete

 删除控制变量。

get

 获取控件。

list

 按父级 DataStore 列出所有控制变量。

patch

 更新控制变量。