本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon Connect 客户档案计算出的属性 APIs
<a name="customerprofiles-calculated-attributes-apis"></a>

您可以使用以下 “客户档案” 计算属性 APIs

------
#### [ CreateCalculatedAttributeDefinition ]

**CreateCalculatedAttributeDefinition**

创建新的计算的属性。这需要域中现有的对象类型。您可以定义要从单个源对象中提取的属性和要整体应用于这些属性的数学运算，以及时间范围和对象计数。

创建后，摄取到 Customer Profiles 中的新对象数据将包含在计算的属性中，可以使用 `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]*$`
  + 必需：否
+ **描述**

  计算的属性的描述。
  + 类型：字符串
  + 长度限制：最小长度为 1。最大长度为 1000。
  + 必需：否
+ **UseHistoricalData**

  计算中是否应包括在创建计算的属性之前摄取的历史数据。
  + 类型：布尔值
  + 必需：否
+ **AttributeDetails**

  定义中使用的属性的详细信息以及不同属性之间涉及的数学运算。请参阅以下组件：
  + **Attributes**

    在数学表达式中指定的属性项目列表。
    + **AttributeItem**

      在数学表达式中指定的单个属性项目的详细信息。
      + Name
        + 资料对象类型中定义的属性的名称。
        + 类型：字符串
  + **Expression**

    对属性列表中提供的属性项目执行的数学表达式。表达式中的每个元素都应遵循\$1 “\$1的结构ObjectTypeName。 AttributeName\$1\$1”。
    + 示例：`{ObjA.AttributeA} - {ObjA.AttributeB}`
    + 类型：字符串
    + 我们只支持以下数学运算：`+ - * /`
    + 一旦创建了计算的属性定义，就无法对表达式进行修改
+ **Conditions**

  定义计算的属性聚合标准和阈值。
  + 类型：条件对象
    + Range
    + ObjectCount
    + Threshold
+ **Range**

  数据包含在聚合中的相对时间段。
  + 类型：范围对象
    + Value：指定单位的时间长度。`ValueRange` 会覆盖 Value。
      + 类型：整数
      + 必需：否
    + ValueRange：一种结构，允许客户指定相对时间窗口，计算属性中包含该时间范围内的数据。使用正数表示终点在过去，使用负数表示它在未来。 ValueRange覆盖值。
      + 类型： ValueRange
      + 必需：否
        + 晚于
          + 包含对象时的开始时间。使用正数表示起点在过去，使用负数表示起点在将来。
          + 类型：整数
          + 是否必需：是 
        + 早于
          + 包含对象时的结束时间。使用正数表示起点在过去，使用负数表示起点在将来。
          + 类型：整数
          + 是否必需：是 
    + TimestampSource：一个表达式，用于指定 JSON 对象中应从中解析日期的字段。表达式应遵循\$1 “\$1的结构ObjectTypeName。 <Location of timestamp field in JSON pointer format>\$1\$1”。例如，如果您的对象类型为 MyType ，源 JSON 为`{"generatedAt": {"timestamp": "1737587945945"}}`，则 TimestampSource应为`"{MyType.generatedAt.timestamp}"`。
      + 长度约束：最小长度为 1。最大长度为 255。
      + 必需：否
    + TimestampFormat：指定您的 JSON 对象中时间戳字段的格式。此值应为 EPOCHMILLI（适用于具有 second/millisecond 等级精度的 Unix 纪元时间戳）或 ISO\$18601（遵循 ISO\$18601 格式，级别精度，可选偏移量为 Z 或者格式为 HH: MM 或 HHMM。）。 second/millisecond 例如，如果你的对象类型是， MyType而源 JSON 是`{"generatedAt": {"timestamp": "2001-07-04T12:08:56.235-0700"}},`，那么 TimestampFormat 应该是`"ISO_8601"`。
    + 单位：时间单位
      + 有效值：天
      + 是否必需：是
  + 是否必需：是
  + 初始范围：最长 366 天
+ **ObjectCount**

  用于计算的属性的资料对象的数量。
  + 类型：数字
  + 范围：1 到 100
  + 必需：否
+ **Threshold**

  生成 true/false 计算属性的比较逻辑。
  + 类型：阈值对象
    + Value
      + 阈值的值
      + 类型：字符串
      + 必需：否
    + Operator
      + 阈值的运算符
      + 类型：ENUM
      + 有效值：
        + GREATER\$1THAN
        + LESS\$1THAN
        + EQUAL\$1TO
        + NOT\$1EQUAL\$1TO
  + 必需：否
+ **Statistic**

  要对计算的属性执行的聚合操作。
  + 类型：ENUM
  + 有效值：
    + FIRST\$1OCCURRENCE
    + LAST\$1OCCURRENCE
    + COUNT
    + SUM
    + MINIMUM
    + MAXIMUM
    + AVERAGE
    + MAX\$1OCCURRENCE

------
#### [ 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]*$`
  + 必需：否
+ **描述**

  计算的属性的描述。
  + 类型：字符串
  + 长度限制：最小长度为 1。最大长度为 1000。
  + 必需：否
+ **Conditions**

  定义计算的属性聚合标准和阈值。
  + 类型：条件对象
    + Range
    + ObjectCount
    + Threshold
+ **Range**

  数据包含在聚合中的相对时间段。
  + 类型：范围对象
    + 值：指定单位的时间长度
      + 类型：整数
      + 必需：否
    + ValueRange：一种结构，允许客户指定相对时间窗口，计算属性中包含该时间范围内的数据。使用正数表示终点在过去，使用负数表示它在未来。 ValueRange覆盖值。
      + 类型： ValueRange
      + 必需：否
        + 晚于
          + 包含对象时的开始时间。使用正数表示起点在过去，使用负数表示起点在将来。
          + 类型：整数
          + 是否必需：是 
        + 早于
          + 包含对象时的结束时间。使用正数表示起点在过去，使用负数表示起点在将来。
          + 类型：整数
          + 是否必需：是 
    + 单位：时间单位
      + 有效值：天
      + 是否必需：是
  + 是否必需：是
  + 初始范围：最长 366 天
+ **ObjectCount**

  用于计算的属性的资料对象的数量。
  + 类型：数字
  + 范围：1 到 100
  + 必需：否
+ **Threshold**

  生成 true/false 计算属性的比较逻辑。
  + 类型：阈值对象
    + Value
      + 阈值的值
      + 类型：字符串
      + 必需：否
    + Operator
      + 阈值的运算符
      + 类型：ENUM
      + 有效值：
        + GREATER\$1THAN
        + LESS\$1THAN
        + EQUAL\$1TO
        + NOT\$1EQUAL\$1TO
  + 必需：否

------
#### [ 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

------