本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 管理中的数据存储 AWS IoT SiteWise
您可以配置 AWS IoT SiteWise 为将数据保存在以下存储层中：
**热层**
热存储层是 AWS IoT SiteWise 托管的时间序列存储。Hot tier 对频繁访问的数据最有效， write-to-read延迟时间很短。存储在热层中的数据供需要快速访问设备中最新测量值的工业应用程序使用。这包括使用交互式控制面板可视化实时指标的应用程序，或监控操作并启动警报来识别性能问题的应用程序。
默认情况下，采集到的数据存储 AWS IoT SiteWise 在热门层中。您可以为热层定义保留期，之后根据您的配置将热层中的数据 AWS IoT SiteWise 移动到温层或冷层存储。为了获得最佳性能和成本效益，请将热层保留期设置为比经常检索数据所需的时间更长。这用于实时指标、警报和监控场景。如果未设置保留期，则数据将无限期存储在热层中。
**温层**
温存储层是一个 AWS IoT SiteWise 托管层，可以有效地经济高效地存储历史数据。它最适合用于检索具有中等 write-to-read延迟特征的大量数据。使用温层来存储大型工作负载所需的历史数据。例如，它用于分析、商业智能应用程序（BI）、报告工具和机器学习（ML）模型训练的数据检索。如果您启用冷存储层，则可以定义温层保留期。保留期结束后，从温层中 AWS IoT SiteWise 删除数据。
**冷层**
冷存储层使用 Amazon S3 存储桶来存储很少使用的数据。启用冷层后， AWS IoT SiteWise 每 6 小时复制一次时间序列，包括测量值、指标、转换和聚合，以及资产模型定义。冷层用于存储可容忍历史报告和备份高读取延迟的数据。
**Topics**
+ [在中配置存储设置 AWS IoT SiteWise](configure-storage.md)
+ [对存储设置进行故障排除 AWS IoT SiteWise](troubleshoot-storage-configuration.md)
+ [冷层中保存的数据的文件路径和架构](file-path-and-schema.md)
# 在中配置存储设置 AWS IoT SiteWise
您可以配置存储设置，以启用服务托管的温层存储，并将数据复制到冷层。要详细了解温层和热层的保留期，请参阅[数据留存的影响](#retention-period)。配置存储设置时，请执行以下操作：
+ **热层保留** — 设置保留期，规定数据在删除之前在热层中存储多长时间，然后根据您的存储设置将其移至服务托管的温层存储或冷层存储。 AWS IoT SiteWise 将删除在保留期结束之前存在的热门层中的所有数据。如果未设置保留期，则数据将无限期存储在热层中。
+ **热层保留** — 设置保留期，规定您的数据在从存储中删除并移至客户管理的冷层 AWS IoT SiteWise 存储之前在温层中存储多长时间。 AWS IoT SiteWise 从保留期结束之前存在的暖层中删除所有数据。如果未设置保留期，则数据将无限期存储在温层中。
**注意**
要提高查询性能，请使用温层存储设置热层保留期。
## 数据留存在热层和温层存储中的影响
+ 缩短热层存储的保留期时，数据将从热层永久迁移到温层或冷层。缩短温层的保留期时，数据将移至冷层，并从温层中永久删除。
+ 当您延长热层或温层存储的保留期时，更改会影响 AWS IoT SiteWise 从那时起发送到的数据。 AWS IoT SiteWise 不会从温存储或冷存储中检索数据以填充热层。例如，如果热层存储的保留期最初设置为 30 天，然后增加到 60 天，则热层存储需要 30 天才能包含 60 天的数据。
**Topics**
+ [数据留存在热层和温层存储中的影响](#retention-period)
+ [为温层配置存储设置（控制台）](#configure-storage-console-warm)
+ [为温层配置存储设置（AWS CLI）](#configure-storage-cli-warm)
+ [配置冷层的存储设置（控制台）](#configure-storage-console)
+ [为冷层配置存储设置（AWS CLI）](#configure-storage-cli)
## 为温层配置存储设置（控制台）
以下过程向您展示如何在 AWS IoT SiteWise 控制台中配置存储设置以将数据复制到温层。
**若要配置控制台中的存储设置**
1. 导航至 [AWS IoT SiteWise 控制台](https://console.aws.amazon.com/iotsitewise/)。
1. 在导航窗格中的**设置**下，选择**存储**。
1. 在右上角，选择 **编辑**。
1. 在**编辑存储**页面中，执行以下操作：
1. 对于**热层设置**，执行以下操作：
+ 如果要在数据被删除并迁移至服务托管的温层存储中前，为数据在热层中的存储时间设置保留期，请选择**启用保留期**。
+ 要配置保留期，请输入整数并选择单位。保留期必须大于或等于 30 天。
AWS IoT SiteWise 删除热门层中所有早于保留期的数据。如果未设置保留期，则数据将无限期存储。
1. （推荐）对于**温层设置**，请执行以下操作：
+ 要选择加入温层存储，请选择**我确认选择加入温层存储**，选择加入温层存储。
+ （可选）要配置保留期，请输入一个整数并选择单位。保留期必须大于或等于 365 天。
AWS IoT SiteWise 删除在保留期之前存在的温层中的数据。如果未设置保留期，则数据将无限期存储。
**注意**
当您选择使用温层时，配置仅显示一次。
要设置热层保留期，您必须有温层或冷层存储。为了提高成本效益和检索历史数据， AWS IoT SiteWise 建议您将长期数据存储在温层。
要设置温层保留，您必须有冷层存储。
1. 选择**保存**以保存您的存储设置。
在 **AWS IoT SiteWise 存储**部分中，**温层存储**处于以下状态之一：
+ **已启用** - 如果您的数据在热层保留期之前就已存在，则 AWS IoT SiteWise 会将数据移至温层。
+ **已禁用** – 温层存储已禁用。
## 为温层配置存储设置（AWS CLI）
您可以使用 AWS CLI 和以下命令配置存储设置以将数据移动到温层。
为防止覆盖现有配置，请运行以下命令来检索当前的存储配置信息：
```
aws iotsitewise describe-storage-configuration
```
**Example 无现有冷层配置的响应**
```
{
"storageType": "SITEWISE_DEFAULT_STORAGE",
"disassociatedDataStorage": "ENABLED",
"configurationStatus": {
"state": "ACTIVE"
},
"lastUpdateDate": "2021-10-14T15:53:35-07:00",
"warmTier": "DISABLED"
}
```
**Example 包含现有冷层配置的响应**
```
{
"storageType": "MULTI_LAYER_STORAGE",
"multiLayerStorage": {
"customerManagedS3Storage": {
"s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
"roleArn": "arn:aws:iam::aws-account-id:role/role-name"
}
},
"disassociatedDataStorage": "ENABLED",
"retentionPeriod": {
"numberOfDays": retention-in-days
},
"configurationStatus": {
"state": "ACTIVE"
},
"lastUpdateDate": "2023-10-25T15:59:46-07:00",
"warmTier": "DISABLED"
}
```
### 使用配置暖层的存储设置 AWS CLI
要配置存储设置，请运行以下命令。`file-name`替换为包含 AWS IoT SiteWise 存储配置的文件的名称。
```
aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
```
**Example AWS IoT SiteWise 带热层和温层的配置**
```
{
"storageType": "SITEWISE_DEFAULT_STORAGE",
"disassociatedDataStorage": "ENABLED",
"warmTier": "ENABLED",
"retentionPeriod": {
"numberOfDays": hot-tier-retention-in-days
}
}
```
`hot-tier-retention-in-days` 必须是大于或等于 30 天的整数。
**Example 响应**
```
{
"storageType": "SITEWISE_DEFAULT_STORAGE",
"configurationStatus": {
"state": "UPDATE_IN_PROGRESS"
}
}
```
如果您启用了冷层存储，请参阅[使用 AWS CLI 和现有冷层配置存储设置](#configure-storage-cli-existing-cold)。
### 使用 AWS CLI 和现有冷层配置存储设置
**使用 AWS CLI 现有冷层存储配置存储设置**
+ 要配置存储设置，请运行以下命令。将 *file-name* 替换为包含 AWS IoT SiteWise 存储配置的文件的名称。
```
aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
```
**Example AWS IoT SiteWise 存储配置**
+ 将 *amzn-s3-demo-bucket* 替换为您的 Amazon S3 桶名称。
+ *prefix*替换为您的 Amazon S3 前缀。
+ *aws-account-id*替换为您的 AWS 账户 ID。
+ *role-name*替换为允许 AWS IoT SiteWise 向 Amazon S3 发送数据的 Amazon S3 访问角色的名称。
+ *hot-tier-retention-in-days*替换为大于或等于 30 天的整数。
+ *warm-tier-retention-in-days*替换为大于或等于 365 天的整数。
**注意**
AWS IoT SiteWise 将删除温层中所有早于冷层保留期的数据。如果未设置保留期，则数据将无限期存储。
```
{
"storageType": "MULTI_LAYER_STORAGE",
"multiLayerStorage": {
"customerManagedS3Storage": {
"s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
"roleArn": "arn:aws:iam::aws-account-id:role/role-name"
}
},
"disassociatedDataStorage": "ENABLED",
"retentionPeriod": {
"numberOfDays": hot-tier-retention-in-days
},
"warmTier": "ENABLED",
"warmTierRetentionPeriod": {
"numberOfDays": warm-tier-retention-in-days
}
}
```
**Example 响应**
```
{
"storageType": "MULTI_LAYER_STORAGE",
"configurationStatus": {
"state": "UPDATE_IN_PROGRESS"
}
}
```
## 配置冷层的存储设置（控制台）
以下过程向您展示如何在 AWS IoT SiteWise 控制台中配置存储设置以将数据复制到冷层。
**若要配置控制台中的存储设置**
1. 导航至 [AWS IoT SiteWise 控制台](https://console.aws.amazon.com/iotsitewise/)。
1. 在导航窗格中的**设置**下，选择**存储**。
1. 在右上角，选择 **编辑**。
1. 在**编辑存储**页面中，执行以下操作：
1. 对于 **存储设置**，选择 **启用冷层存储**。默认情况下，冷层存储处于禁用状态。
1. 对于 **S3 存储桶位置**，输入现有 Amazon S3 存储桶的名称和前缀。
**注意**
Amazon S3 使用前缀作为 Amazon S3 存储桶中的文件夹名称。前缀必须包含 1-255 个字符，并以正斜杠 (/) 结尾。您的 AWS IoT SiteWise 数据将保存在此文件夹中。
如果您没有 Amazon S3 存储桶，请选择 **查看**，然后在 Amazon S3 控制台中创建一个存储桶。有关更多信息，请参阅 *Amazon S3 用户指南*中的[创建您的第一个 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket)。
1. 对于 **S3 访问角色**，执行下列操作之一：
+ 选择**从 AWS 托管模板创建角色**， AWS 自动创建允许向 Amazon S3 AWS IoT SiteWise 发送数据的 IAM 角色。
+ 选择**使用现有角色**，然后从列表中选择您创建的角色。
**注意**
您必须对 **S3 存储桶位置**使用与您在上一步和 IAM Policy 中使用的相同的 Amazon S3 存储桶名称。
确保您的角色具有以下示例中显示的权限。
**Example 权限策略：**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}
```
将 amzn-s3-demo-bucket 替换为您的 Amazon S3 存储桶的名称。
如果使用客户托管的 KMS 密钥对 Amazon S3 存储桶进行加密，那么 KMS 密钥必须具有访问策略，该策略必须具有 IAM 角色`kms:Decrypt`和`kms:GenerateDataKey`操作。
1. 要设置热层，请参阅[为温层配置存储设置（控制台）](#configure-storage-console-warm)中的步骤 5。
1. （可选）对于 **AWS IoT Analytics 集成**，请执行以下操作。
**注意**
终止支持通知： AWS 将于 2025 年 12 月 15 日终止对的支持 AWS IoT Analytics。2025 年 12 月 15 日之后，您将无法再访问 AWS IoT Analytics 控制台或 AWS IoT Analytics 资源。有关更多信息，请参阅[AWS IoT Analytics 终止支持](https://docs.aws.amazon.com/iotanalytics/latest/userguide/iotanalytics-end-of-support.html)。
1. 如果要使用 AWS IoT Analytics 来查询数据，请选择**已启用 AWS IoT Analytics 数据存储**。
1. AWS IoT SiteWise 为您的数据存储生成一个名称，也可以输入其他名称。
AWS IoT SiteWise 自动在中创建数据存储 AWS IoT Analytics 以保存您的数据。要查询数据，您可以使用 AWS IoT Analytics 创建数据集。有关更多信息，请参阅《*AWS IoT Analytics 用户指南》*中的[使用 AWS IoT SiteWise 数据](https://docs.aws.amazon.com/iotanalytics/latest/userguide/dataset-itsw.html)。
1. 选择**保存**。
在 **AWS IoT SiteWise 存储**部分中，**冷层存储**可以是以下值之一：
+ **已启用**- AWS IoT SiteWise 将您的数据复制到指定的 Amazon S3 存储桶。
+ **启用**- AWS IoT SiteWise 正在处理您的启用冷层存储的请求。此过程可能需要几分钟才能完成。
+ **Enable\$1Failed — AWS IoT SiteWise 无法**处理您的启用冷层存储的请求。如果您启用 AWS IoT SiteWise 向 Amazon Logs 发送 CloudWatch 日志，则可以使用这些日志来解决问题。有关更多信息，请参阅 [使用 Amazon CloudWatch 日志进行监控](monitor-cloudwatch-logs.md)。
+ **已禁用** – 冷层存储已禁用。
## 为冷层配置存储设置（AWS CLI）
以下过程演示如何配置存储设置以使用 AWS CLI将数据复制到冷层。
**要使用配置存储设置 AWS CLI**
1. 要将数据导出到您账户中的 Amazon S3 存储桶，请运行以下命令以配置存储设置。*file-name*替换为包含 AWS IoT SiteWise 存储配置的文件的名称。
```
aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
```
**Example AWS IoT SiteWise 存储配置**
+ 将 *amzn-s3-demo-bucket* 替换为您的 Amazon S3 桶名称。
+ *prefix*替换为您的 Amazon S3 前缀。
+ *aws-account-id*替换为您的 AWS 账户 ID。
+ *role-name*替换为允许 AWS IoT SiteWise 向 Amazon S3 发送数据的 Amazon S3 访问角色的名称。
+ *retention-in-days*替换为大于或等于 30 天的整数。
```
{
"storageType": "MULTI_LAYER_STORAGE",
"multiLayerStorage": {
"customerManagedS3Storage": {
"s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
"roleArn": "arn:aws:iam::aws-account-id:role/role-name"
}
},
"retentionPeriod": {
"numberOfDays": retention-in-days,
"unlimited": false
}
}
```
**注意**
您必须在存储配置和 IAM 策略中使用相同的 Amazon S3 AWS IoT SiteWise 存储桶名称。
确保您的角色具有以下示例中显示的权限。
**Example 权限策略：**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}
```
将 amzn-s3-demo-bucket 替换为您的 Amazon S3 存储桶的名称。
如果使用客户托管的 KMS 密钥对 Amazon S3 存储桶进行加密，那么 KMS 密钥必须具有访问策略，该策略必须具有 IAM 角色`kms:Decrypt`和`kms:GenerateDataKey`操作。
**Example 响应**
```
{
"storageType": "MULTI_LAYER_STORAGE",
"retentionPeriod": {
"numberOfDays": 100,
"unlimited": false
},
"configurationStatus": {
"state": "UPDATE_IN_PROGRESS"
}
}
```
**注意**
更新存储配置可能需要几分钟。 AWS IoT SiteWise
1. 若要检索存储配置信息，请运行以下命令。
```
aws iotsitewise describe-storage-configuration
```
**Example 响应**
```
{
"storageType": "MULTI_LAYER_STORAGE",
"multiLayerStorage": {
"customerManagedS3Storage": {
"s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/torque/",
"roleArn": "arn:aws:iam::123456789012:role/SWAccessS3Role"
}
},
"retentionPeriod": {
"numberOfDays": 100,
"unlimited": false
},
"configurationStatus": {
"state": "ACTIVE"
},
"lastUpdateDate": "2021-03-30T15:54:14-07:00"
}
```
1. 要停止将数据导出到 Amazon S3 存储桶，请运行以下命令以配置存储设置。
```
aws iotsitewise put-storage-configuration --storage-type SITEWISE_DEFAULT_STORAGE
```
**注意**
默认情况下，您的数据仅存储在热门层中 AWS IoT SiteWise。
**Example 响应**
```
{
"storageType": "SITEWISE_DEFAULT_STORAGE",
"configurationStatus": {
"state": "UPDATE_IN_PROGRESS"
}
}
```
1. 若要检索存储配置信息，请运行以下命令。
```
aws iotsitewise describe-storage-configuration
```
**Example 响应**
```
{
"storageType": "SITEWISE_DEFAULT_STORAGE",
"configurationStatus": {
"state": "ACTIVE"
},
"lastUpdateDate": "2021-03-30T15:57:14-07:00"
}
```
### （可选）创建 AWS IoT Analytics 数据存储 (AWS CLI)
**注意**
终止支持通知： AWS 将于 2025 年 12 月 15 日终止对的支持 AWS IoT Analytics。2025 年 12 月 15 日之后，您将无法再访问 AWS IoT Analytics 控制台或 AWS IoT Analytics 资源。有关更多信息，请参阅[AWS IoT Analytics 终止支持](https://docs.aws.amazon.com/iotanalytics/latest/userguide/iotanalytics-end-of-support.html)。
AWS IoT Analytics 数据存储是一种可扩展且可查询的存储库，用于接收和存储数据。您可以使用 AWS IoT SiteWise 控制台或 AWS IoT Analytics APIs 创建 AWS IoT Analytics 数据存储来保存 AWS IoT SiteWise 数据。要查询数据，请使用创建数据集 AWS IoT Analytics。有关更多信息，请参阅*《AWS IoT Analytics 用户指南》*中的[使用 AWS IoT SiteWise 数据](https://docs.aws.amazon.com/iotanalytics/latest/userguide/dataset-itsw.html)。
以下步骤 AWS CLI 用于在中创建数据存储 AWS IoT Analytics。
若要创建数据集，运行以下命令。*file-name*替换为包含数据存储配置的文件的名称。
```
aws iotanalytics create-datastore --cli-input-json file://file-name.json
```
**注意**
您必须指定现有 Amazon S3 存储桶的名称。如果没有 Amazon S3 存储桶，请先创建一个。有关更多信息，请参阅 *Amazon S3 用户指南*中的[创建您的第一个 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket)。
您必须在存储配置、IAM 策略和 AWS IoT Analytics 数据 AWS IoT SiteWise 存储配置中使用相同的 Amazon S3 存储桶名称。
**Example AWS IoT Analytics 数据存储配置**
将*data-store-name*和*amzn-s3-demo-bucket*替换为您的 AWS IoT Analytics 数据存储名称和 Amazon S3 存储桶名称。
```
{
"datastoreName": "data-store-name",
"datastoreStorage": {
"iotSiteWiseMultiLayerStorage": {
"customerManagedS3Storage": {
"bucket": "amzn-s3-demo-bucket"
}
}
},
"retentionPeriod": {
"numberOfDays": 90
}
}
```
**Example 响应**
```
{
"datastoreName": "datastore_IoTSiteWise_demo",
"datastoreArn": "arn:aws:iotanalytics:us-west-2:123456789012:datastore/datastore_IoTSiteWise_demo",
"retentionPeriod": {
"numberOfDays": 90,
"unlimited": false
}
}
```
# 对存储设置进行故障排除 AWS IoT SiteWise
使用以下信息对存储配置进行故障诊断并解决问题。
**Topics**
+ [错误：存储桶不存在](#no-s3-bucket)
+ [错误：访问 Amazon S3 路径被拒](#iam-permissions)
+ [错误：无法代入角色 ARN](#iam-trust-relationship)
+ [错误：无法访问跨区域 Amazon S3 存储桶](#cross-region-s3-bucket)
## 错误：存储桶不存在
**解决方案：**找 AWS IoT SiteWise 不到您的 Amazon S3 存储桶。确保您输入当前区域中现有 Amazon S3 存储桶的名称。
## 错误：访问 Amazon S3 路径被拒
**解决方案：** AWS IoT SiteWise 无法访问您的 Amazon S3 存储桶。执行以下操作：
+ 确保您使用的 Amazon S3 存储桶与您在 IAM Policy 中指定的相同。
+ 确保您的角色具有以下示例中显示的权限。
**Example 权限策略**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}
```
------
将 amzn-s3-demo-bucket 替换为您的 Amazon S3 存储桶的名称。
## 错误：无法代入角色 ARN
**解决方案：** AWS IoT SiteWise 无法代表您担任 IAM 角色。确保您的角色信任以下服务：`iotsitewise.amazonaws.com`。有关更多信息，请参阅 *《IAM 用户指南》*中的[我无法带入角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_roles.html#troubleshoot_roles_cant-assume-role)。
## 错误：无法访问跨区域 Amazon S3 存储桶
**解决方案：**您指定的 Amazon S3 存储桶位于不同的 AWS 区域。确保您的 Amazon S3 存储桶和 AWS IoT SiteWise 资产位于同一区域。
# 冷层中保存的数据的文件路径和架构
AWS IoT SiteWise 通过复制时间序列（包括度量、指标、转换和聚合，以及资产和资产模型定义）将您的数据存储在冷层中。下面介绍发送到冷层的数据的文件路径和架构。
**Topics**
+ [设备数据（测量）](#measurements-file-path-and-schema)
+ [指标、转换和聚合](#metrics-file-path-and-schema)
+ [资产元数据](#asset-metadata)
+ [资产层次结构元数据](#asset-hierarchy-metadata)
+ [存储数据索引文件](#storage-data-index)
## 设备数据（测量）
AWS IoT SiteWise 每六小时将设备数据（测量值）导出到冷层一次。原始数据以 [Apache AVRO](https://avro.apache.org) (`.avro`) 格式保存在冷层中。
### 文件路径
AWS IoT SiteWise 使用以下模板将设备数据（测量值）存储在冷层中。
```
{keyPrefix}/raw/startYear={startYear}/startMonth={startMonth}/startDay={startDay}/seriesBucket={seriesBucket}/raw_{timeseriesId}_{startTimestamp}_{quality}.avro
```
Amazon S3 中原始数据的每个文件路径都包含以下组件。
#### 文件路径
| 路径组件 | 说明 |
| --- | --- |
| `keyPrefix` | 您在 AWS IoT SiteWise 存储配置中指定的 Amazon S3 前缀。Amazon S3 使用前缀作为存储桶中的文件夹名称。 |
| `raw` | 存储设备（测量）中的时间序列数据的文件夹。`raw` 文件夹保存在前缀文件夹中。 |
| `seriesBucket` | 介于 00 和 ff 之间的十六进制数。此数字派生自 `timeSeriesId`。此分区用于在 AWS IoT SiteWise 写入冷层时增加吞吐量。当您使用 Amazon Athena 运行查询时，您可以使用该分区进行精细分区以提高查询性能。 资产元数据中的 `seriesBucket` 和 `timeSeriesBucket` 是相同的数字。 |
| `startYear` | 与时间序列数据关联的独占开始时间的年份。 |
| `startMonth` | 与时间序列数据关联的独占开始时间的月份。 |
| `startDay` | 与时间序列数据关联的独占开始时间的月份中的某一天。 |
| `fileName` | 文件名使用下划线 (\$1) 字符作为分隔符来分隔以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/file-path-and-schema.html) 该文件通过使用 [Snappy](https://github.com/google/snappy) 压缩以 `.avro` 格式保存。 |
**Example 冷层中原始数据的文件路径**
`keyPrefix/raw/startYear=2021/startMonth=1/startDay=2/seriesBucket=a2/raw_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1609577700_GOOD.avro`
### 字段
导出到冷层的原始数据的架构包含以下字段。
AWS IoT SiteWise 建议客户在从冷层读取原始数据的系统上实现对架构演变的支持，因为将来可能会引入其他字段。
空数据表示为所有值字段均为空。但是，客户在使用查询时仍会收到正确的数据类型 AWS IoT SiteWise APIs。
#### 字段
| 字段名称 | 支持的类型 | 默认类型 | 说明 |
| --- | --- | --- | --- |
| `seriesId` | `string` | 不适用 | 标识设备（度量）中的时间序列数据的 ID。您可以使用此字段在查询中联接原始数据和资产元数据。 |
| `timeInSeconds` | `long` | 不适用 | 采用 Unix 纪元时间格式的时间戳日期（以秒为单位）。分数纳秒数据由 `offsetInNanos` 提供。 |
| `offsetInNanos` | `long` | 不适用 | 与 `timeInSeconds` 的纳秒偏移量。 |
| `quality` | `string` | 不适用 | 时间序列值的质量。 |
| `doubleValue` | `double` 或 `null` | `null` | 双精度（浮点数）类型的时间序列数据。 |
| `stringValue` | `string` 或 `null` | `null` | 字符串类型（字符序列）的时间序列数据。 |
| `integerValue` | `int` 或 `null` | `null` | 整数类型（整数）的时间序列数据。 |
| `booleanValue` | `boolean` 或 `null` | `null` | 布尔类型的时间序列数据（true 或 false）。 |
| `jsonValue` | `string` 或 `null` | `null` | JSON 类型的时间序列数据（存储为字符串的复杂数据类型）。 |
| `recordVersion` | `long` 或 `null` | `null` | 记录的版本号。您可以使用版本号来选择最新记录。较新的记录具有较大的版本号。 |
**Example 冷层中的原始数据**
```
{"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675887,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.75},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
{"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675889,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.69},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
{"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675890,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.66},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
{"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675891,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.92},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
{"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675892,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.73},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
```
## 指标、转换和聚合
AWS IoT SiteWise 每六小时将指标、转换和聚合导出到冷层一次。指标、转换和聚合以 [Apache AVRO](https://avro.apache.org) (`.avro`) 格式保存在冷层中。
### 文件路径
AWS IoT SiteWise 使用以下模板将指标、转换和聚合存储在冷层中。
```
{keyPrefix}/agg/startYear={startYear}/startMonth={startMonth}/startDay={startDay}/seriesBucket={seriesBucket}/agg_{timeseriesId}_{startTimestamp}_{quality}.avro
```
Amazon S3 中指标、转换和聚合的每个文件路径都包含以下组件。
#### 文件路径
| 路径组件 | 说明 |
| --- | --- |
| `keyPrefix` | 您在 AWS IoT SiteWise 存储配置中指定的 Amazon S3 前缀。Amazon S3 使用前缀作为存储桶中的文件夹名称。 |
| `agg` | 用于存储来自指标的时间序列数据的文件夹。`agg` 文件夹保存在前缀文件夹中。 |
| `seriesBucket` | 介于 00 和 ff 之间的十六进制数。此数字派生自 `timeSeriesId`。此分区用于在 AWS IoT SiteWise 写入冷层时增加吞吐量。当您使用 Amazon Athena 运行查询时，您可以使用该分区进行精细分区以提高查询性能。 资产元数据中的 `seriesBucket` 和 `timeSeriesBucket` 是相同的数字。 |
| `startYear` | 与时间序列数据关联的独占开始时间的年份。 |
| `startMonth` | 与时间序列数据关联的独占开始时间的月份。 |
| `startDay` | 与时间序列数据关联的独占开始时间的月份中的某一天。 |
| `fileName` | 文件名使用下划线 (\$1) 字符作为分隔符来分隔以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/file-path-and-schema.html) 该文件通过使用 [Snappy](https://github.com/google/snappy) 压缩以 `.avro` 格式保存。 |
**Example 冷层中指标的文件路径**
`keyPrefix/agg/startYear=2021/startMonth=1/startDay=2/seriesBucket=a2/agg_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1609577700_GOOD.avro`
### 字段
导出到冷层的指标、转换和聚合的架构包含以下字段。
#### 字段
| 字段名称 | 支持的类型 | 默认类型 | 说明 |
| --- | --- | --- | --- |
| `seriesId` | `string` | 不适用 | 标识来自设备、指标或转换的时序数据的 ID。您可以使用此字段在查询中联接原始数据和资产元数据。 |
| `timeInSeconds` | `long` | 不适用 | 采用 Unix 纪元时间格式的时间戳日期（以秒为单位）。分数纳秒数据由 `offsetInNanos` 提供。 |
| `offsetInNanos` | `long` | 不适用 | 与 `timeInSeconds` 的纳秒偏移量。 |
| `quality` | `string` | 不适用 | 筛选资产数据所依据的质量。 |
| `resolution` | `string` | 不适用 | 聚合数据的时间间隔。 |
| `count` | `double` 或 `null` | `null` | 给定变量在当前时间间隔内的数据点总数。 |
| `average` | `double` 或 `null` | `null` | 给定变量在当前时间间隔内的平均值。 |
| `min` | `double` 或 `null` | `null` | 给定变量在当前时间间隔内的最小值。 |
| `max` | `boolean` 或 `null` | `null` | 给定变量在当前时间间隔内的最大值。 |
| `sum` | `string` 或 `null` | `null` | 给定变量在当前时间间隔内的值总和。 |
| `recordVersion` | `long` 或 `null` | `null` | 记录的版本号。您可以使用版本号来选择最新记录。较新的记录具有较大的版本号。 |
**Example 冷层中的指标数据**
```
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334060,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334120,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":29.0,"average":{"double":46.0},"min":{"double":32.0},"max":{"double":60.0},"sum":{"double":1334.0},"recordVersion":null}
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334540,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334600,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":29.0,"average":{"double":46.0},"min":{"double":32.0},"max":{"double":60.0},"sum":{"double":1334.0},"recordVersion":null}
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637335020,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
```
## 资产元数据
首次启用 AWS IoT SiteWise 将数据导出到冷层时，资产元数据将导出到冷层。初始配置完成后，只有在您更改资产模型定义或资产定义时，才会将资产元数据 AWS IoT SiteWise 导出到该层。资产元数据以换行符分隔的 JSON（`.ndjson`）格式保存在冷层中。
### 文件路径
AWS IoT SiteWise 使用以下模板将资产元数据存储在冷层中。
```
{keyPrefix}/asset_metadata/asset_{assetId}.ndjson
```
冷层中资产元数据的每个文件路径都包含以下组件。
#### 文件路径
| 路径组件 | 说明 |
| --- | --- |
| `keyPrefix` | 您在的存储配置中指定的 Amazon AWS IoT SiteWise S3 前缀。Amazon S3 使用前缀作为存储桶中的文件夹名称。 |
| `asset_metadata` | 存储资产元数据的文件夹。`asset_metadata` 文件夹保存在前缀文件夹中。 |
| `fileName` | 文件名使用下划线 (\$1) 字符作为分隔符来分隔以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/file-path-and-schema.html) 该文件以 `.ndjson` 格式保存。 |
**Example 较冷层中资产元数据的文件路径**
`keyPrefix/asset_metadata/asset_35901915-d476-4dca-8637-d9ed4df939ed.ndjson`
### 字段
导出到冷层的资产元数据的模式包含以下字段。
#### 字段
| 字段名称 | 说明 |
| --- | --- |
| `assetId` | 资产的 ID。 |
| `assetName` | 资产的名称。 |
| `assetExternalId` | 资产的外部 ID。 |
| `assetModelId` | 用于创建该资产的资产模型的 ID。 |
| `assetModelName` | 资产模型的名称。 |
| `assetModelExternalId` | 资产模型的外部 ID。 |
| `assetPropertyId` | 资产属性的 ID。 |
| `assetPropertyName` | 资产属性的名称。 |
| `assetPropertyExternalId` | 资产属性的外部 ID。 |
| `assetPropertyDataType` | 资产属性的数据类型。 |
| `assetPropertyUnit` | 资产属性的单位（例如，`Newtons` 和 `RPM`）。 |
| `assetPropertyAlias` | 标识资产属性的别名，例如 OPC UA 服务器数据流路径（例如，`/company/windfarm/3/turbine/7/temperature`）。 |
| `timeSeriesId` | 标识来自设备、指标或转换的时序数据的 ID。您可以使用此字段在查询中联接原始数据和资产元数据。 |
| `timeSeriesBucket` | 介于 00 和 ff 之间的十六进制数。此数字派生自 `timeSeriesId`。此分区用于在 AWS IoT SiteWise 写入冷层时增加吞吐量。当您使用 Amazon Athena 运行查询时，您可以使用该分区进行精细分区以提高查询性能。 原始数据的文件路径中的 `timeSeriesBucket` 和 `seriesBucket` 是相同的数字。 |
| `assetCompositeModelId` | 复合模型的 ID。 |
| `assetCompositeModelExternalId` | 复合模型的外部 ID。 |
| `assetCompositeModelDescription` | 复合模型的描述。 |
| `assetCompositeModelName` | 复合模型的名称。 |
| `assetCompositeModelType` | 复合模型的类型。对于警报复合模型，这种类型是 `AWS/ALARM`。 |
| `assetCreationDate` | 资产的创建日期，以 Unix 纪元时间为单位。 |
| `assetLastUpdateDate` | 资产上次更新的日期，以 Unix 纪元为单位。 |
| `assetStatusErrorCode` | 错误代码。 |
| `assetStatusErrorMessage` | 错误消息。 |
| `assetStatusState` | 资产的当前状态。 |
**Example 冷层中的资产元数据**
```
{"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"95e63da7-d34e-43e1-bc6f-1b490154b07a","assetPropertyExternalId":null,"assetPropertyName":"Temperature","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"Celsius","assetPropertyAlias":"USA/Washington/Seattle/WT2/temp","timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeSeriesBucket":"f6","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
{"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"c706d54d-4c11-42dc-9a01-63662fc697b4","assetPropertyExternalId":null,"assetPropertyName":"Pressure","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"KiloPascal","assetPropertyAlias":"USA/Washington/Seattle/WT2/pressure","timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_c706d54d-4c11-42dc-9a01-63662fc697b4","timeSeriesBucket":"1e","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
{"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"8cf1162f-dead-4fbe-b468-c8e24cde9f50","assetPropertyExternalId":null,"assetPropertyName":"Max Temperature","assetPropertyDataType":"DOUBLE","assetPropertyUnit":null,"assetPropertyAlias":null,"timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_8cf1162f-dead-4fbe-b468-c8e24cde9f50","timeSeriesBucket":"d7","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
{"assetId":"3a5f2a22-3b37-4332-9c1c-404ea1d73fab","assetExternalId":null,"assetName":"BatchAssetDouble1","assetModelId":"814bdfd8-24db-4a33-8d9b-ebc75e75e827","assetModelExternalId":null,"assetModelName":"FlashTestAssetModelDouble","assetPropertyId":"6b7e1532-175b-4c02-b410-ab401a9176ed","assetPropertyExternalId":null,"assetPropertyName":"measurementProperty","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"u","assetPropertyAlias":null,"timeSeriesId":"ab19f4fa-7e7b-4247-ae89-ff316f5ff8aa","timeSeriesBucket":"af","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1646960106,"assetLastUpdateDate":1646960106,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
```
## 资产层次结构元数据
当您首次启用 AWS IoT SiteWise 在冷层保存数据时，资产层次结构元数据将导出到冷层。初始配置完成后，只有在对资产模型或资产定义进行更改时，才会将资产层次结构元数据 AWS IoT SiteWise 导出到冷层。资产层次结构元数据以换行符分隔的 JSON（`.ndjson`）格式保存在冷层中。
通过调用 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html)API 可以检索层次结构、目标资产或源资产的外部标识符。
### 文件路径
AWS IoT SiteWise 使用以下模板将资产层次结构元数据存储在冷层中。
```
{keyPrefix}/asset_hierarchy_metadata/{parentAssetId}_{hierarchyId}.ndjson
```
冷层中资产层次结构元数据的每个文件路径都包含以下组件。
#### 文件路径
| 路径组件 | 说明 |
| --- | --- |
| `keyPrefix` | 您在 AWS IoT SiteWise 存储配置中指定的 Amazon S3 前缀。Amazon S3 使用前缀作为存储桶中的文件夹名称。 |
| `asset_hierarchy_metadata` | 存储资产层次结构元数据的文件夹。`asset_hierarchy_metadata` 文件夹保存在前缀文件夹中。 |
| `fileName` | 文件名使用下划线 (\$1) 字符作为分隔符来分隔以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/file-path-and-schema.html) 该文件以 `.ndjson` 格式保存。 |
**Example 冷层中资产层次结构元数据的文件路径**
`keyPrefix/asset_hierarchy_metadata/35901915-d476-4dca-8637-d9ed4df939ed_c5b3ced8-589a-48c7-9998-cdccfc9747a0.ndjson`
### 字段
导出到冷层的资产层次结构元数据的架构包含以下字段。
#### 字段
| 字段名称 | 说明 |
| --- | --- |
| `sourceAssetId` | 此资产关系中源资产的 ID。 |
| `targetAssetId` | 此资产关系中目标资产的 ID。 |
| `hierarchyId` | 层次结构的 ID。 |
| `associationType` | 此资产关系的关联类型。 值必须为 `CHILD`。目标资产是源资产的子资产。 |
**Example 冷层中的资产层次结构元数据**
```
{"sourceAssetId":"80388e72-2284-44fb-9c89-bfbaf0dfedd2","targetAssetId":"2b866c25-0c74-4750-bdf5-b73683c8a2a2","hierarchyId":"bbed9f59-0412-4585-a61d-6044db526aee","associationType":"CHILD"}
{"sourceAssetId":"80388e72-2284-44fb-9c89-bfbaf0dfedd2","targetAssetId":"6b51246e-984d-460d-bc0b-470ea47d1e31","hierarchyId":"bbed9f59-0412-4585-a61d-6044db526aee","associationType":"CHILD"}
```
**若要在冷层中查看您的数据**
1. 导航到 [Amazon S3 控制台](https://console.aws.amazon.com/s3/)。
1. 在导航窗格中，选择**存储桶**，然后选择您的 Amazon S3 存储桶。
1. 导航到包含原始数据、资产元数据或资产层次结构元数据的文件夹。
1. 选择文件，然后从**操作**中选择**下载**。
## 存储数据索引文件
AWS IoT SiteWise 使用这些文件来优化数据查询性能。它们显示在您的 Amazon S3 存储桶中，但您不需要使用它们。
### 文件路径
AWS IoT SiteWise 使用以下模板将数据索引文件存储在冷层中。
```
keyPrefix/index/series=timeseriesId/startYear=startYear/startMonth=startMonth/startDay=startDay/index_timeseriesId_startTimestamp_quality
```
**Example 数据存储索引文件的文件路径**
`keyPrefix/index/series=7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a/startYear=2022/startMonth=02/startDay=03/index_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1643846400_GOOD`