本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon Connect Customer Profiles 計算屬性 API 您可以使用下列客戶設定檔計算屬性 API ------ #### [ CreateCalculatedAttributeDefinition ] **CreateCalculatedAttributeDefinition** 建立新的計算屬性。這需要網域中的現有物件類型。您可以定義要從單一來源物件中提取的屬性，以及要套用至彙總的數學運算，以及時間範圍和物件計數。 建立之後，擷取至客戶設定檔的新物件資料將包含在計算屬性中，您可以使用 `GetCalculatedAttributeForProfile` API 針對設定檔擷取該屬性。若要使用歷史資料，請指定 `UseHistoricalData` 為 true。API 回應上的 `Readiness` 和 `Status` 欄位將提供計算屬性所含歷史資料的狀態資訊。 定義計算屬性可讓網域內的所有設定檔使用該屬性。每個計算屬性只能參照一個 ObjectType，以及該 ObjectType 中的最多兩個欄位。 **請求** ``` POST /domains/{{DomainName}}/calculated-attributes/{{CalculatedAttributeName}} ``` ``` { "CalculatedAttributeName": "string", "DisplayName": "string", "Description": "string", "AttributeDetails": { "Attributes": [ { "Name": "string" } ... ], "Expression": "string", }, "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE", "Conditions": { "Range": { "Value": "number", "Units": "string" }, "ObjectCount": "number", "Threshold": { "Value": "string", "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO" } }, "Tags": {} } ``` **回應** ``` { "CalculatedAttributeName": "string", "DisplayName": "string", "Description": "string", "AttributeDetails": { "Attributes": [ { "Name": "string" } ... ], "Expression": "string", }, "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE" "Conditions": { "Range": { "Value": "number", "Units": "string" }, "ObjectCount": "number", "Threshold": { "Value": "string", "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO" } }, "CreatedAt": number, "LastUpdatedAt": number, "Tags": {} } ``` **請求內文** + **CalculatedAttributeName** 計算屬性的唯一 (每個網域) 名稱。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **DisplayName** 計算屬性的顯示名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z_][a-zA-Z_0-9-\s]*$` + 必要：否 + **Description** 計算屬性的描述。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 1000。 + 必要：否 + **UseHistoricalData** 建立計算屬性前擷取的歷史資料是否應包含在計算中。 + 類型：布林值 + 必要：否 + **AttributeDetails** 定義中使用的屬性詳細資訊，以及屬性之間涉及的數學運算。參閱以下元件： + **Attributes** 在數學運算式中指定的屬性項目清單。 + **AttributeItem** 在數學運算式中指定的單一屬性項目的詳細資訊。 + 名稱 + 設定檔物件類型中定義的屬性名稱。 + 類型：字串 + **運算式** 針對屬性清單中所提供屬性項目執行的數學運算式。運算式中的每個元素應遵循 \\"{ObjectTypeName.AttributeName}\\" 的結構。 + 範例：`{ObjA.AttributeA} - {ObjA.AttributeB}` + 類型：字串 + 我們只支援以下數學運算：`+ - * /` + 計算屬性定義建立後，您就無法修改「運算式」 + **條件** 定義計算屬性彙總條件和閾值。 + 類型：條件物件 + 範圍 + ObjectCount + Threshold + **範圍** 資料包含在彙總中的相對期間。 + 類型：範圍物件 + 值：指定單位的時間長度。`ValueRange` 會覆寫 Value。 + 類型：整數 + 必要：否 + ValueRange：可讓客戶指定相對時間範圍的結構，其中的資料會包含在計算屬性中。使用正數表示結束時間在過去時間，負數表示在未來時間。ValueRange 會覆寫 Value。 + 類型：ValueRange + 必要：否 + Start + 應開始包含物件的時間。使用正數表示開始時間在過去時間，負數表示在未來時間。 + 類型：整數 + 必要：是 + 結束 + 應不再包含物件的時間。使用正數表示開始時間在過去時間，負數表示在未來時間。 + 類型：整數 + 必要：是 + TimestampSource：指定 JSON 物件中應剖析日期欄位的運算式。運算式應遵循以下結構：\\"{ObjectTypeName.}\\"。例如，如果您的物件類型是 MyType，而來源 JSON 為 `{"generatedAt": {"timestamp": "1737587945945"}}`，則 TimestampSource 應為 `"{MyType.generatedAt.timestamp}"`。 + 長度限制：長度下限為 1。長度上限為 255。 + 必要：否 + TimestampFormat：指定 JSON 物件中時間戳記欄位的格式。此值應為 EPOCHMILLI (適用於具秒/毫秒精確度的 Unix epoch 時間戳記) 或 ISO\_8601 (遵循 ISO\_8601 格式，具秒/毫秒精確度，可選偏移 Z 或格式 HH:MM 或 HHMM)。例如，如果您的物件類型是 MyType，而來源 JSON 為 `{"generatedAt": {"timestamp": "2001-07-04T12:08:56.235-0700"}},`，則 TimestampFormat 應為 `"ISO_8601"`。 + 單位：時間單位 + 有效值：天 + 必要：是 + 必要：是 + 初始範圍：最多 366 天 + **ObjectCount** 用於計算屬性的設定檔物件數目。 + 類型：數字 + 範圍：1 至 100 + 必要：否 + **Threshold** 用來產生真/假計算屬性的比較邏輯。 + 類型：臨界值物件 + Value + 閾值的值 + 類型：字串 + 必要：否 + 運算子 + 閾值的運算子 + 類型：ENUM + 有效值： + GREATER\_THAN + LESS\_THAN + EQUAL\_TO + NOT\_EQUAL\_TO + 必要：否 + **統計數字** 要針對計算屬性執行的彙總作業。 + 類型：ENUM + 有效值： + FIRST\_OCCURRENCE + LAST\_OCCURRENCE + COUNT + SUM + MINIMUM + MAXIMUM + AVERAGE + MAX\_OCCURRENCE ------ #### [ UpdateCalculatedAttributeDefinition ] **UpdateCalculatedAttributeDefinition** 更新計算屬性定義。更新僅限於顯示名稱、描述、時間範圍、物件計數和閾值。此 API 支援部分更新，因此只需要包含需要更新的參數。 **注意** 更新條件時： 增加計算屬性的日期範圍並不會觸發將大於目前日期範圍的歷史資料納入。 建立計算屬性定義後，就無法更新 TimestampSource 和 TimestampFormat。 **請求** ``` PUT /domains/{{DomainName}}/calculated-attributes/{{CalculatedAttributeName}} ``` ``` { "DisplayName": "string", "Description": "string", "Conditions": { "Range": { "Value": "number", "Units": "string" }, "ObjectCount": "number", "Threshold": { "Value": "string", "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO" } } } ``` **回應** ``` { "CalculatedAttributeName": "string", "DisplayName": "string", "Description": "string", "AttributeDetails": { "Attributes": [ { "Name": "string" } ... ], "Expression": "string", }, "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE" "Conditions": { "Range": { "Value": "number", "Units": "string" }, "ObjectCount": "number", "Threshold": { "Value": "string", "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO" } }, "CreatedAt": number, "LastUpdatedAt": number, "Tags": {} } ``` **請求內文** + **DisplayName** 計算屬性的顯示名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z_][a-zA-Z_0-9-\s]*$` + 必要：否 + **Description** 計算屬性的描述。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 1000。 + 必要：否 + **條件** 定義計算屬性彙總條件和閾值。 + 類型：條件物件 + 範圍 + ObjectCount + Threshold + **範圍** 資料包含在彙總中的相對期間。 + 類型：範圍物件 + 值：指定單位的時間長度 + 類型：整數 + 必要：否 + ValueRange：可讓客戶指定相對時間範圍的結構，其中的資料會包含在計算屬性中。使用正數表示結束時間在過去時間，負數表示在未來時間。ValueRange 會覆寫 Value。 + 類型：ValueRange + 必要：否 + Start + 應開始包含物件的時間。使用正數表示開始時間在過去時間，負數表示在未來時間。 + 類型：整數 + 必要：是 + 結束 + 應不再包含物件的時間。使用正數表示開始時間在過去時間，負數表示在未來時間。 + 類型：整數 + 必要：是 + 單位：時間單位 + 有效值：天 + 必要：是 + 必要：是 + 初始範圍：最多 366 天 + **ObjectCount** 用於計算屬性的設定檔物件數目。 + 類型：數字 + 範圍：1 至 100 + 必要：否 + **Threshold** 用來產生真/假計算屬性的比較邏輯。 + 類型：臨界值物件 + Value + 閾值的值 + 類型：字串 + 必要：否 + 運算子 + 閾值的運算子 + 類型：ENUM + 有效值： + GREATER\_THAN + LESS\_THAN + EQUAL\_TO + NOT\_EQUAL\_TO + 必要：否 ------ #### [ GetCalculatedAttributeDefinition ] **GetCalculatedAttributeDefinition** 擷取計算屬性定義。 **請求** ``` GET /domains/{{DomainName}}/calculated-attributes/{{CalculatedAttributeName}} ``` **請求內文** ``` The request does not have a request body. ``` **回應** ``` { "CalculatedAttributeName": "string", "DisplayName": "string", "Description": "string", "AttributeDetails": { "Attributes": [ { "Name": "string" } ... ], "Expression": "string", }, "Statistic": "AVERAGE" | "COUNT" | "SUM" | "FIRST_OCCURRENCE" | "LAST_OCCURRENCE" | "MINIMUM" | "MAXIMUM" | "MAX_OCCURRENCE" "Conditions": { "Range": { "Unit": "string", "Value": number "ValueRange" { "Start": number "End": number }, "TimestampFormat": "string", "TimestampSource": "string" }, "ObjectCount": "number", "Threshold": { "Value": "string", "Operator": "EQUAL_TO" | "GREATER_THAN" | "LESS_THAN" | "NOT_EQUAL_TO" } }, "UseHistoricalData" boolean, "Status": "PREPARING" | "IN_PROGRESS" | "COMPLETED" | "FAILED", "Readiness": { "ProgressPercentage": number, "Message": "string", }, "CreatedAt": number, "LastUpdatedAt": number, "Tags": {} } ``` **URI 請求參數** + **DomainName** 網域的唯一名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **CalculatedAttributeName** 計算屬性的唯一 (每個網域) 名稱。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 ------ #### [ DeleteCalculatedAttributeDefinition ] **DeleteCalculatedAttributeDefinition** 刪除現有的計算屬性定義。請注意，您可以刪除預設的計算屬性，但是一旦刪除，您將無法復原該動作，如果您想要還原，則需要使用 `CreateCalculatedAttributeDefinition` API 自行重新建立該屬性。 **請求** ``` DELETE /domains/{{DomainName}}/calculated-attributes/{{CalculatedAttributeName}} ``` **請求內文** ``` The request does not have a request body. ``` **回應** ``` The response does not have a response body. ``` **URI 請求參數** + **DomainName** 網域的唯一名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **CalculatedAttributeName** 計算屬性的唯一 (每個網域) 名稱。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 ------ #### [ ListCalculatedAttributeDefinitions ] **ListCalculatedAttributeDefinitions** 擷取網域的所有計算屬性定義。 **請求** ``` GET /domains/{{DomainName}}/calculated-attributes?max-results=MaxResults&next-token=NextToken ``` **請求內文** ``` The request does not have a request body. ``` **回應** ``` { "Items": [ { "UseHistoricalData": boolean, "ReadinessStatus": PREPARING | IN_PROGRESS | COMPLETED | FAILED, "CalculatedAttributeName": "string", "CreatedAt": number, "Description": "string", "DisplayName": "string", "LastUpdatedAt": number, "Tags": { "string" : "string" } } ], "NextToken": "string" } ``` **URI 請求參數** + **DomainName** 網域的唯一名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **MaxResults** 每頁傳回的物件數量上限。 + 有效範圍：最小值為 1。最大值為 100。 + **NextToken** 先前 ListCalculatedAttributeDefinition API 呼叫的分頁字符。 + 長度限制：長度下限為 1。長度上限為 1024。 ------ #### [ GetCalculatedAttributeForProfile ] **GetCalculatedAttributeForProfile** 啟動計算並擷取單一設定檔中單一計算屬性的結果。 **請求** ``` GET /domains/{{DomainName}}/profile/{{ProfileId}}/calculated-attributes/{{CalculatedAttributeName}} ``` **請求內文** ``` The request does not have a request body. ``` **回應** ``` { "Name": "string", "DisplayName": "string", "Value": "string", "IsDataPartial": "string", "LastObjectTimestamp" : number } ``` **URI 請求參數** + **DomainName** 網域的唯一名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **CalculatedAttributeName** 計算屬性的唯一 (每個網域) 名稱。 + 類型：字串 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 ------ #### [ ListCalculatedAttributesForProfile ] **ListCalculatedAttributesForProfile** 啟動計算並擷取單一設定檔所有計算屬性的結果。 **請求** ``` GET /domains/{{DomainName}}/profile/{{ProfileId}}/calculated-attributes?max-results=MaxResults&next-token=NextToken ``` **請求內文** ``` The request does not have a request body. ``` **回應** ``` { "Items": [ { "CalculatedAttributeName": "string", "DisplayName": "string", "Value": "string", "IsDataPartial" : "string", "LastObjectTimestamp" : number }, ... ], "NextToken": "string" } ``` **URI 請求參數** + **DomainName** 網域的唯一名稱。 + 長度限制：長度下限為 1。長度上限為 64。 + 模式：`^[a-zA-Z0-9_-]+$` + 必要：是 + **ProfileId** + 模式：`[a-f0-9]{32}` + 必要：是 + **MaxResults** 每頁傳回的物件數量上限。 + 有效範圍：最小值為 1。最大值為 100。 + **NextToken** 先前 ListCalculatedAttributeDefinition API 呼叫的分頁字符。 + 長度限制：長度下限為 1。長度上限為 1024。 ------