本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS IoT TwinMaker Athena 表格数据连接器
您可通过 Athena 表格数据连接器访问和使用 AWS IoT TwinMaker中存储的 Athena 数据。您可以使用 Athena 数据构建数字孪生，而无需大量迁移数据。您可以使用预先构建的连接器或创建自定义 Athena 连接器来访问来自 Athena 数据源的数据。
## AWS IoT TwinMaker Athena 数据连接器先决条件
在使用 Athena 表格数据连接器之前，请完成以下先决条件：
+ 创建托管 Athena 表及其关联的 Amazon S3 资源。[有关使用 Athena 的信息，请参阅Athena 文档](https://docs.aws.amazon.com//athena/latest/ug/what-is.html)。
+ 创建 AWS IoT TwinMaker 工作空间。您可以在 [AWS IoT TwinMaker 控制台](https://console.aws.amazon.com/iottwinmaker/)中创建工作区。
+ 使用 Athena 权限更新您的工作空间 IAM 角色。有关更多信息，请参阅 [修改工作区 IAM 角色以使用 Athena 数据连接器](twinmaker-gs-service-role.md#athena-tabular-data-connector-ws-IAM)。
+ 熟悉 AWS IoT TwinMaker的实体组件系统以及如何创建实体。有关更多信息，请参阅 [创建您的第一个实体](twinmaker-gs-entity.md)。
+ 熟悉 AWS IoT TwinMaker的数据连接器。有关更多信息，请参阅 [AWS IoT TwinMaker 数据连接器](data-connector-interface.md)。
## 使用 Athena 数据连接器
若要使用 Athena 数据连接器，必须采用 Athena 连接器创建组件。然后将组件连接至 AWS IoT TwinMaker场景内使用的实体。
**通过 Athena 数据连接器创建组件类型**
使用以下步骤使用 Athena 表格数据连接器创建 AWS IoT TwinMaker 组件类型：
1. 导航至 [AWS IoT TwinMaker 控制台](https://console.aws.amazon.com/iottwinmaker/)。
1. 打开现有工作区或[创建新工作区](twinmaker-gs-workspace.md)。
1. 在左侧导航菜单中选择 **组件类型**，然后选择**创建组件类型**以打开组件类型创建页面。
1. 在 **创建组件类型** 页面，填写匹配您用例的 **ID**。
![\[组件类型信息控制台页面，包含 ID、描述和基本类型的输入字段。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/CreateComponentType-ComponentTypeInformation.png)
1. 选择 **基类型**。**从下拉列表中，选择标记为com.amazon.athena.connector** 的 Athena 表格数据连接器。
1. 通过为以下字段选择 Athena 资源，以配置组件类型**数据来源**：
+ 选择 **Athena 数据源。**
+ 选择 **Athena 数据库**。
+ 选择 **表格名称**。
+ 选择 **Athena 工作组**。
1. 选择要用作数据来源的 Athena 资源后，从表格中选择要包含的列。
1. 选择**外部 ID 列名称**。从上一步中选择一列，作为外部 ID 列。外部 ID 是用于表示 Athena 资产并将其映射到实体的 ID。 AWS IoT TwinMaker
![\[Athena Data Connector 控制台页面允许您选择数据源、数据库、表名和列。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/CreateComponentType-AthenaDataConnector.png)
1. **（可选）**为这些资源添加 AWS 标签，以便您可以对它们进行分组和组织。
1. 选择 **创建组件类型** 以完成创建组件类型。
**创建具有 Athena 数据连接器类型的组件，并将其附加至实体**
使用以下步骤创建带有 Athena 表格数据连接器的 AWS IoT TwinMaker 组件并将其连接到实体：
若要完成此程序，您的现有组件类型必须将 Athena 表格数据连接器作为数据来源。查看前述程序**开始本操作前，通过 Athena 数据连接器创建组件类型**。
1. 导航至 [AWS IoT TwinMaker 控制台](https://console.aws.amazon.com/iottwinmaker/)。
1. 打开现有工作区或[创建新工作区](twinmaker-gs-workspace.md)。
1. 从左侧导航菜单中选择 “**实**体”，然后选择要向其添加组件或创建新实体的实体。
1. [创建一个新实体](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/twinmaker-gs-entity.html)。
1. 接下来选择**添加组件**，在**组件名称**字段中填写匹配您用例的名称。
1. 在 **组件类型**下拉菜单中，选择您在前述程序中创建的 **组件类型 ID**。
1. 输入**组件信息**、**组件名称**，然后选择之前 ComponentType 创建的子项。这是 ComponentType 您使用 Athena 数据连接器创建的。
1. 在 “**属性**” 部分中，输入组件的 **athenaComponentExternalID**。
![\[“属性” 控制台页面允许您添加组件的属性。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/CreateEntity-Properties.png)
1. 选择 **添加组件**以完成组件创建。
现在您已成功创建了带 Athena 数据连接器的组件，将其作为适当的组件类型，并连接至实体。
## 使用 Athena 表格数据连接器 JSON 参考资料
以下是 Athena 表格数据连接器的完整 JSON 参考资料示例。将其用作创建自定义数据连接器以及组件类型的资源。
```
{
"componentTypeId": "com.amazon.athena.connector",
"description": "Athena connector for syncing tabular data",
"workspaceId":"AmazonOwnedTypesWorkspace",
"propertyGroups": {
"tabularPropertyGroup": {
"groupType": "TABULAR",
"propertyNames": []
}
},
"propertyDefinitions": {
"athenaDataSource": {
"dataType": { "type": "STRING" },
"isRequiredInEntity": true
},
"athenaDatabase": {
"dataType": { "type": "STRING" },
"isRequiredInEntity": true
},
"athenaTable": {
"dataType": { "type": "STRING" },
"isRequiredInEntity": true
},
"athenaWorkgroup": {
"dataType": { "type": "STRING" },
"isRequiredInEntity": true
},
"athenaExternalIdColumnName": {
"dataType": { "type": "STRING" },
"isRequiredInEntity": true,
"isExternalId": false
},
"athenaComponentExternalId": {
"dataType": { "type": "STRING" },
"isStoredExternally": false,
"isRequiredInEntity": true,
"isExternalId": true
}
},
"functions": {
"tabularDataReaderByEntity": {
"implementedBy": {
"isNative": true
}
}
}
}
```
## 使用 Athena 数据连接器
您可以在 Grafana 中显示使用 Athena 表的实体。有关更多信息，请参阅 [AWS IoT TwinMaker Grafana 控制面板集成](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/grafana-integration.html)。
有关创建和使用 Athena 表存储数据的信息，请阅读 [Athena 文档](https://docs.aws.amazon.com//athena/latest/ug/what-is.html)。
### 排除 Athena 数据连接器故障
本主题介绍您在配置 Athena 数据连接器时可能遇到的常见问题。
Athena 工作组位置：
当创建 Athena 连接器 ComponentType 时，Athena 工作组必须设置输出位置。查看 [工作组的工作原理](https://docs.aws.amazon.com//athena/latest/ug/user-created-workgroups.html)。
IAM 角色权限缺失：
在创建 ComponentType、向实体添加 Ca 组件或运行 API 时， AWS IoT TwinMaker; workspace 角色可能缺少 Athena API 访问权限。 GetPropertyValue 要更新 IAM 权限，请参阅[创建和管理的服务角色 AWS IoT TwinMaker](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/twinmaker-gs-service-role.html)。
## 查看 Grafana 中的 Athena 表格数据
Grafana插件还可用于在Grafana上可视化您的表格数据，Grafana是一个仪表板面板，具有其他功能，例如根据所选属性进行排序和筛选，而无需对Athena进行API调用或与Athena进行交互。 AWS IoT TwinMaker本主题向您介绍如何配置 Grafana 以查看 Athena 表格数据。
### 先决条件
在配置 Grafana 平面以可查看 Athena 表格数据之前，请查看以下先决条件：
+ 您已经设置了 Grafana 环境。有关更多信息，请参阅 [AWS IoT TwinMaker Grafana 集成](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/grafana-integration.html)。
+ 您可配置 Grafana 数据来源。欲了解更多信息，请参阅 [Grafana AWS IoT TwinMaker](https://github.com/grafana/grafana-iot-twinmaker-app/blob/main/src/datasource/README.md)。
+ 您熟悉如何创建新控制面板和添加新面板。
### 查看 Grafana 中的 Athena 表格数据
此过程向您展示如何设置 Grafana 面板以查看 Athena 表格数据。
1. 打开你的 AWS IoT TwinMaker Grafana 控制面板。
1. 在面板设置中选择 **表格**面板。
1. 在查询配置中选择数据来源。
1. 选择 **Get Property Value**（获取属性值）查询。
1. 选择一个实体。
1. 选择包含扩展 **Athena 基本组件类型的**ComponentType 组件。
1. 选择 Athena 表格的属性群组。
1. 从属群组中选择任意数量的属性。
1. 通过筛选条件和属性顺序列表，配置表格条件。使用以下选项：
+ **筛选条件**：定义数据筛选属性值的表达式。
+ **OrderBy**：指定应按升序还是降序返回属性的数据。
![\[设置为可视化 Athena 表格数据的 Grafana 控制台面板示例。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/ate-grafana-panel.png)