本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT TwinMaker Athena 表格式資料連接器
使用 Athena 表格式資料連接器，您可以存取和使用您的 Athena 資料存放區 AWS IoT TwinMaker。您可以使用 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 欄位。
1. 選擇 **Base 類型**。從下拉式清單中選取標記為 **com.amazon.athena.connector 的 Athena** 表格式資料連接器。
1. 為下列欄位選擇 Athena 資源，以設定元件類型的**資料來源**：
+ 選擇 **Athena 資料來源**。
+ 選擇 **Athena 資料庫**。
+ 選擇**資料表名稱**。
+ 選擇 **Athena workGroup**。
1. 選取要用作資料來源的 Athena 資源之後，請從資料表中選擇要包含的資料欄。
1. 選取**外部 ID 資料欄名稱**。從上一個步驟中選取資料欄，做為外部 ID 資料欄。外部 ID 是用來代表 Athena 資產並將其映射至 AWS IoT TwinMaker 實體的 ID。
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。這是您使用 Athena 資料連接器建立的 ComponentType。
1. 在**屬性**區段中，輸入元件的 **athenaComponentExternalId**。
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 資料表存放資料的相關資訊，](https://docs.aws.amazon.com//athena/latest/ug/what-is.html)請參閱 Athena 文件。
### 故障診斷 Athena 資料連接器
本主題涵蓋您在設定 Athena 資料連接器時可能遇到的常見問題。
Athena 工作群組位置：
建立 Athena 連接器 componentType 時，Athena 工作群組必須設定輸出位置。請參閱[工作群組的運作方式](https://docs.aws.amazon.com//athena/latest/ug/user-created-workgroups.html)。
缺少 IAM 角色許可：
AWS IoT TwinMaker建立 componentType、將 Ca 元件新增至實體或執行 GetPropertyValue API 時，工作區角色可能缺少 Athena API 存取許可。若要更新 IAM 許可[，請參閱建立和管理 的服務角色 AWS IoT TwinMaker](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/twinmaker-gs-service-role.html)。
## 在 Grafana 中視覺化 Athena 表格式資料
Grafana 外掛程式也可用於視覺化 Grafana 儀表板面板上的表格式資料，其中包含其他功能，例如根據所選屬性進行排序和篩選，而不呼叫 API AWS IoT TwinMaker，或與 Athena 互動。本主題說明如何設定 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. 選取**取得屬性值**查詢。
1. 選擇實體。
1. 選取具有延伸 Athena 基本元件類型的 componentType 的元件。 ****
1. 選取 Athena 資料表的屬性群組。
1. 從屬性群組中選取任意數量的屬性。
1. 透過篩選條件和屬性順序清單設定表格式條件。使用下列選項：
+ **篩選條件**：定義屬性值的表達式來篩選資料。
+ **OrderBy**：指定是否應為屬性以遞增或遞減順序傳回資料。
