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

# 设置 AWS IoT SiteWise 对象 ID
<a name="object-ids"></a>

 AWS IoT SiteWise 定义各种类型的持久对象，例如资产、资产模型、属性和层次结构。所有这些对象都有唯一的标识符，可用于对其进行检索、更新和删除。

 AWS IoT SiteWise 为客户创建 ID 提供了不同的选项。 AWS IoT SiteWise 默认情况下，在对象创建时为您生成一个。用户还可以向您的对象提供他们自己的 ID。

**Topics**
+ [使用对象 UUID](#object-uuids)
+ [使用外部 ID](#external-ids)

## 使用对象 UUID
<a name="object-uuids"></a>

 中的每个永久对象都 AWS IoT SiteWise 有一个 [ UUID ](https://en.wikipedia.org/wiki/Universally_unique_identifier) 来识别它。例如，资产模型具有资产模型 ID，资产具有资产 ID，依此类推。此 ID 是在您创建对象时分配的，并且在该对象的生命周期内保持不变。

 创建新对象时，默认情况下会为您 AWS IoT SiteWise 生成一个唯一 ID。您也可以在创建时以 UUID 格式提供您自己的 ID。

**注意**  
UUID 在创建它的 AWS 区域内****必须是全局唯一的，并且对象类型相同。当 AWS IoT SiteWise 自动为您生成 ID 时，它始终是唯一的。如果您自行选择 ID，请确保其唯一性。

例如，如果您通过调用创建新的资产模型 [ CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html)，则可以在请求的可选`assetModelId`字段中提供自己的 UUID。

相比之下，如果您在该请求中省略 `assetModelId`，则 AWS IoT SiteWise 会为新的资产模型生成一个 UUID。

## 使用外部 ID
<a name="external-ids"></a>

要以 UUID 以外的某种格式定义您自己的 ID，您可以分配一个*外部 ID*。例如，如果你重复使用在不是 ID 的系统中使用的 ID，或者为了提高人类可读性 AWS，你可以这样做。外部 ID 的格式更加灵活。您可以在 AWS IoT SiteWise API 操作中使用它们来引用您的对象，而不是使用 UUID。

 与 UUID 一样，每个外部 ID 在其上下文中都必须是唯一的。例如，您无法拥有具有同一外部 ID 的两个资产模型。此外，与 UUID 一样，一个对象在其生命周期中只能有一个外部 ID，并且该外部 ID 无法更改。

### 外部 ID 和 UUID 之间的区别
<a name="external-ids-differences-from-uuid"></a>

外部 ID 与 UUID 存在以下差异：
+ 每个对象都有一个 UUID，但外部 ID 是可选的。
+ AWS IoT SiteWise 永远不会生成外部 ID。这些都是您自己提供的。
+ 如果对象还没有外部 ID，您可以随时为其分配一个外部 ID。

### 外部 ID 的格式
<a name="external-id-format"></a>

有效的外部 ID 具有以下属性：
+ 介于 2 到 128 个字符之间。
+ 第一个和最后一个字符必须是字母数字（A-Z、a-z、0-9）。
+ 除第一个和最后一个以外的字符必须是字母数字，或者是以下形式之一：`_-.:`

例如，外部 ID 必须符合以下正则表达式：

`[a-zA-Z0-9][a-zA-Z0-9_\-.:]*[a-zA-Z0-9]+`

### 引用带外部 ID 的对象
<a name="external-id-references"></a>

在很多可以使用 UUID 来引用对象的场景中，如果对象拥有外部 ID，则您可以改用其外部 ID。为此，请将外部 ID 附加到字符串 `externalId:` 中。

例如，假设您有一个资产模型，其 UUID（资产模型 ID）为 `a1b2c3d4-5678-90ab-cdef-11111EXAMPLE`，并且还具有外部 ID `myExternalId`。[DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html)致电获取详细信息。您可以使用以下任意一项作为 `assetModelId` 的值：
+ 使用资产模型 ID（UUID）本身：`a1b2c3d4-5678-90ab-cdef-11111EXAMPLE`
+ 使用外部 ID：`externalId:myExternalId`

```
aws iotsitewise describe-asset-model --asset-model-id a1b2c3d4-5678-90ab-cdef-11111EXAMPLE
aws iotsitewise describe-asset-model --asset-model-id externalId:myExternalId
```

**注意**  
`externalId:` 前缀本身不是外部 ID 的一部分。只有在为接受 UUID 或外部 ID 的 API 操作提供外部 ID 时，才需要提供前缀。例如，在查询或更新现有对象时提供前缀。  
在为对象定义外部 ID 时（例如创建资产模型时），请不要包含前缀。

您可以通过这种方式使用外部 ID 代替 UUID 来执行中的许多 API 操作 AWS IoT SiteWise，但不是全部。例如 [ GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html)，**必须**使用 UUID；它不支持使用外部 ID。

要确定特定的 API 操作是否支持这种用法，请查阅 [API 参考](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Operations.html)。