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

資源：控制項

定義在服務期間採用的條件式行為。必須附加至 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

這是必要旗標，使用者可判讀的名稱。使用者介面檢視區塊中使用的 ID。

必須是 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)

定義篩選器類型控制項，目前建議功能不支援
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 最多 5000 個半形字元。否則會擲回 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 如果是新鮮度用途，屬性值會是目前時間與指定 datetime 欄位中日期之間的時間長度。這個值的格式必須為 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 長度不得超過 2,000 個字元。否則會擲回 INVALID ARGUMENT 錯誤。

SynonymsAction

建立一組互為同義詞的字詞。

舉例來說，「開心」也會視為「高興」，「高興」也會視為「開心」。

JSON 表示法 
{
  "synonyms": [
    string
  ]
}
欄位
synonyms[]

string

定義一組同義詞。最多可指定 100 個同義字。至少須指定 2 個同義詞。否則會擲回 INVALID ARGUMENT 錯誤。

PromoteAction

根據某些觸發查詢，宣傳特定連結。

範例：在搜尋 shoe 關鍵字時，宣傳鞋店連結。連結可以位於相關聯的資料儲存庫外部。

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

string

這是必要旗標，這個促銷活動所連結的資料儲存庫。

SearchLinkPromotion

宣傳活動原型包含 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 標準化，並使用 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 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

方法

create

 建立 Control。

delete

 刪除控制項。

get

 取得 Control。

list

 依上層 DataStore 列出所有控制項。

patch

 更新控制項。