本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 Amazon Athena 資料來源
**注意**
在支援第 9 版或更新版本的工作區中，此資料來源可能需要您安裝適當的外掛程式。如需詳細資訊，請參閱[使用外掛程式擴展您的工作區](grafana-plugins.md)。
**注意**
本指南假設在使用 Athena 資料來源之前，您已熟悉 Amazon Athena 服務。
透過 Amazon Managed Grafana，您可以使用 Grafana 工作區主控台中的資料來源組態選項，將 Athena 新增為 AWS 資料來源。此功能可探索現有的 Athena 帳戶，並管理存取 Athena 所需的身分驗證憑證組態，以簡化將 Athena 新增為資料來源的程序。您可以使用此方法來設定身分驗證，並將 Athena 新增為資料來源，也可以使用與自我管理 Grafana 伺服器上相同的方法手動設定資料來源和必要的身分驗證憑證。
Athena 有先決條件可供 Amazon Managed Grafana 存取。如需使用 Athena 資料來源與 相關聯的先決條件，請參閱 [先決條件](Athena-prereq.md)。
# 先決條件
若要使用 Amazon Managed Grafana for Athena 的受管政策，請先完成下列任務，再設定 Athena 資料來源：
+ 使用 標記您的 Athena 工作群組`GrafanaDataSource: true`。
+ 建立名稱開頭為 的 S3 儲存貯體`grafana-athena-query-results-`。此政策提供將查詢結果寫入具有該命名慣例的 S3 儲存貯體的許可。
此受管政策不包含存取 Athena 查詢基礎資料來源的 Amazon S3 許可。您必須根據case-by-case手動新增 Amazon S3 儲存貯體的必要許可。如需詳細資訊，請參閱本指南[中 Amazon Managed Grafana 中的身分型政策範例](https://docs.aws.amazon.com/grafana/latest/userguide/security_iam_id-based-policy-examples.html)。
# 使用 AWS 資料來源組態將 Amazon Athena 新增為資料來源
## 先決條件
+ [AWS CLI ](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) 已安裝並設定在您的環境中。
+ 您可以從您的帳戶存取 Athena。
若要使用 AWS 資料來源組態，請先前往 Amazon Managed Grafana 主控台，以啟用服務受管 IAM 角色，將讀取您帳戶或整個組織單位中 Athena 資源所需的 IAM 政策授予工作區。然後，您可以使用 Amazon Managed Grafana 工作區主控台將 Athena 新增為資料來源。
# 使用 AWS 資料來源組態將 Athena 新增為資料來源
1. 確保您的使用者角色是管理員或編輯器。
1. 從 Amazon Managed Grafana 主控台選取您要使用的工作區，網址為 https：//[https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/)。
1. 如果您在建立工作空間時未選擇對此工作空間使用服務受管許可，則從使用客戶受管許可變更為使用服務受管許可，以確保在 Grafana 工作空間主控台中使用 AWS 資料來源組態選項啟用適當的 IAM 角色和政策。若要這樣做，請選擇依 **IAM 角色**編輯圖示，然後選擇**服務受管**、**儲存變更**。如需詳細資訊，請參閱[AWS 資料來源的 Amazon Managed Grafana 許可和政策](AMG-manage-permissions.md)。
1. 選擇**資料來源**索引標籤。然後選取 **Amazon Athena** 的核取方塊，然後選擇**動作**、**啟用服務受管政策**。
1. 再次選擇**資料來源**索引標籤，然後在 **Amazon Athena** 列中選擇在 **Grafana 中設定**。
1. 如有必要，請使用 IAM Identity Center 登入 Grafana 工作區主控台。使用者應該將 Athena 存取政策連接到使用者/角色，才能存取 Athena 資料來源。如需更多詳細資訊，請參閱 [AWS 受管政策：AmazonGrafanaAthenaAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonGrafanaAthenaAccess)。
1. 在 Grafana 工作區主控台的左側導覽列中，選擇下方 AWS 圖示 （有兩個），然後從**資料來源**功能表中選擇 **Athena**。
1. 選取您希望 Athena 資料來源查詢的預設區域，然後選取您想要的帳戶，然後選擇**新增資料來源**。
1. 依照步驟在 中設定 **Athena 詳細資訊** [**Athena 詳細資訊**設定](#Athena-settings)
## **Athena 詳細資訊**設定
**設定 **Athena 詳細資訊**設定**
1. 在**連線詳細資訊**功能表中，選取身分驗證提供者 （建議：**工作區 IAM 角色**)。
1. 選取您擁有 Athena 帳戶的目標 Athena 資料來源。如果您未選取任何資料來源，則下拉式清單中會有預設資料來源。
若要建立新的 Athena 帳戶，請遵循 [Athena 入門](https://docs.aws.amazon.com/athena/latest/ug/getting-started.html)中的指示
1. 在上述選取的資料來源中選取目標 Athena 資料庫。
1. 選取工作群組。**主要** 預設為 。
1. 如果您的工作群組尚未設定輸出位置，請指定要用於查詢結果的 S3 儲存貯體和資料夾。例如 `s3://grafana-athena-plugin-test-data/query-result-output/ `
1. 選取**儲存並測試**。
# 手動新增 Athena 資料來源
## 先決條件
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) 已安裝並設定在您的環境中。
+ 您可以從您的帳戶存取 **Amazon Athena**。
**若要手動新增 Athena 資料來源：**
1. 在 Grafana 主控台側邊選單中，暫停**組態** （齒輪） 圖示，然後選擇**資料來源**。
1. 選擇**新增資料來源**。
1. 選擇 **AWS Athena** 資料來源。如有必要，您可以開始**Athena**在搜尋方塊中輸入 ，以協助您找到它。
1. 在**連線詳細資訊**功能表中，設定身分驗證提供者 （建議：**工作區 IAM 角色**)
1. 選取目標 Athena 資料來源、資料庫和工作群組。
若要建立新的 Athena 帳戶，請遵循 [Athena 入門](https://docs.aws.amazon.com/athena/latest/ug/getting-started.html)中的指示。
1. 如果您的工作群組尚未設定輸出位置，請指定要用於查詢結果的 S3 儲存貯體和資料夾。例如 `s3://grafana-athena-plugin-test-data/query-result-output/ `。
1. 選取**儲存並測試**。
以下是 **Athena 詳細資訊**設定的範例。
![\[Athena 詳細資訊範例\]](http://docs.aws.amazon.com/zh_tw/grafana/latest/userguide/images/athena.png)
# 使用 Athena 資料來源
## IAM 政策
Grafana 需要透過 IAM 授予的許可，才能讀取 Athena 指標。您可以將這些許可連接到 IAM 角色，並利用 Grafana 的內建支援來擔任角色。請注意，您必須先設定角色[所需的政策，](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)才能將資料來源新增至 Grafana。您需要管理員或編輯器角色來新增資料來源。內建 Amazon Grafana Athena 存取政策在 [AWS 受管政策：AmazonGrafanaAthenaAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonGrafanaAthenaAccess)區段中定義。
## 查詢 Athena 資料
Athena 資料來源提供標準 SQL 查詢編輯器。Amazon Managed Grafana 包含一些巨集，可協助撰寫更複雜的時間序列查詢。
巨集
| 巨集 | Description | 範例 | 輸出範例 |
| --- | --- | --- | --- |
| \$1\$1\$1dateFilter(column) | \$1\$1\$1dateFilter 會根據面板的日期範圍，建立條件式篩選條件來選取資料 （使用 column)。 | \$1\$1\$1date(my\$1date) | my\$1date BETWEEN date '2017-07-18' AND date '2017-07-18' |
| \$1\$1\$1parseTime(column,format) | \$1\$1\$1parseTime 會將 varchar 轉換為具有指定格式的時間戳記。 | \$1\$1\$1parseTime(eventtime, 'yyyy-MM-dd''T''HH:mm:ss''Z') | parse\$1datetime(time,'yyyy-MM-dd''T''HH:mm:ss''Z') |
| \$1\$1\$1timeFilter(column,format) | \$1\$1\$1timeFilter 會建立條件式，根據面板的時間範圍篩選資料 （使用 column )。第二個引數用於選擇性地將資料欄從 varchar 剖析為具有特定格式的時間戳記。 | \$1\$1\$1timeFilter(time, 'yyyy-MM-dd HH:mm:ss') | TIMESTAMP time BETWEEN TIMESTAMP '2017-07-18T11:15:52Z' AND TIMESTAMP '2017-07-18T11:15:52Z' |
| \$1\$1\$1timeFrom() | \$1\$1\$1timeFrom 會使用引號輸出面板範圍的目前開始時間。 | \$1\$1\$1timeFrom() | TIMESTAMP '2017-07-18 11:15:52' |
| \$1\$1\$1timeTo() | \$1\$1\$1timeTo 會使用引號輸出面板範圍的目前結束時間。 | \$1\$1\$1timeTo() | TIMESTAMP '2017-07-18 11:15:52' |
| \$1\$1\$1timeGroup(column, '1m', format) | \$1\$1\$1timeGroup 群組時間戳記，因此圖形上的每個期間只有 1 點。第三個引數用於選擇性地將資料欄從 varchar 剖析為具有特定格式的時間戳記。 | \$1\$1\$1timeGroup(time,'5m','yyyy-MM-dd''T''HH:mm:ss.SSSSSS''Z') | FROM\$1UNIXTIME(FLOOR(TO\$1UNIXTIME(parse\$1datetime(time,'yyyy-MM-dd''T''HH:mm:ss.SSSSSS''Z'))/300)\$1300) |
| \$1\$1\$1table | \$1\$1\$1table 傳回在資料表選取器中選取的資料表。 | \$1\$1\$1table | my\$1table |
| \$1\$1\$1column | \$1\$1\$1column 傳回在資料欄選取器中選取的資料欄 （需要資料表）。 | \$1\$1\$1column | col1 |
**視覺化**
Athena 中的大多數查詢最好以資料表視覺化呈現。查詢會在資料表中顯示傳回資料。如果可以查詢，則可以將其顯示為資料表。
此範例會傳回資料表視覺化的結果：
```
SELECT {column_1}, {column_2} FROM {table};
```
**時間序列/圖形視覺化 **
對於時間序列和圖形視覺化，您必須：
+ 選取具有 `date`或 `datetime`類型的資料欄。資料`date`欄必須依遞增順序排列 （使用 `ORDER BY column ASC`)。
+ 也會選取數值欄。
**檢查查詢 **
Amazon Managed Grafana 支援 Athena 不支援的巨集，這表示直接複製並貼入 Athena 時，查詢可能無法運作。若要檢視直接在 Athena 中運作的完整插補查詢，請按一下**查詢檢查器**按鈕。完整查詢會顯示在**查詢**索引標籤下。
## 範本和變數
如需新增 Athena 查詢變數的詳細資訊，請參閱 [新增查詢變數](variables-types.md#add-a-query-variable)。使用 Athena 資料來源做為可用查詢的資料來源。
從 Athena 資料表查詢的任何值都可以用作變數。避免選取太多值，因為這可能會導致效能問題。
建立變數之後，您可以使用 在 Athena 查詢中使用它[變數語法](templates-and-variables.md#variable-syntax)。如需變數的詳細資訊，請參閱 [範本和變數](templates-and-variables.md)。
## 註釋
[註釋](dashboard-annotations.md) 可讓您在圖形上方疊加豐富的事件資訊。您可以透過選取面板或使用**儀表板**功能表註釋檢視新增註釋查詢來新增**註釋**。
自動新增註釋的範例查詢：
```
SELECT
time as time,
environment as tags,
humidity as text
FROM
tableName
WHERE
$__dateFilter(time) and humidity > 95
```
下表代表可用於轉譯註釋的資料欄描述：
| 名稱 | 描述 |
| --- | --- |
| Time | 日期/時間欄位的名稱。可以是具有原生 SQL 日期/時間資料類型或 epoch 值的資料欄。 |
| Timeend | 結束日期/時間欄位的選用名稱。可以是具有原生 SQL 日期/時間資料類型或 epoch 值的資料欄。(Grafana v6.6\$1) |
| Text | 事件描述欄位。 |
| Tags | 用於事件標籤的選用欄位名稱，做為逗號分隔字串。 |
## 非同步查詢資料支援
Amazon Managed Grafana 中的 Athena 查詢會以非同步方式處理，以避免逾時。非同步查詢使用單獨的請求來啟動查詢，然後檢查其進度，最後擷取結果。這可避免長時間執行的查詢逾時。
## 查詢結果重複使用
您可以重複使用先前查詢的結果，以改善查詢效能。若要啟用查詢重複使用，請在查詢編輯器的**查詢結果重複使用**區段中啟用 。這必須針對您要重複使用查詢的每個查詢完成。
**注意**
此功能需要您的 Athena 執行個體位於引擎版本 3。如需詳細資訊，請參閱《*Amazon Athena * [Athena 使用者指南》中的變更 Athena 引擎版本](https://docs.aws.amazon.com/athena/latest/ug/engine-versions-changing.html)。