本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 连接到 Amazon Athena 数据来源 **注意** 在支持版本 9 或更高版本的工作区中，此数据来源可能需要您安装相应的插件。有关更多信息，请参阅 [使用插件扩展您的工作区](grafana-plugins.md)。 **注意** 本指南假设您在使用 Athena 数据来源之前，已熟悉 Amazon Athena 服务。 借助 Amazon Managed Grafana，您可以使用 Grafana 工作空间控制台中的数据源配置选项将 Athena 添加为 AWS 数据源。此功能通过发现您现有的 Athena 账户，简化了将 Athena 添加为数据来源的过程，并可管理访问 Athena 所需身份验证凭证的配置。您可以使用此方法设置身份验证，将 Athena 添加为数据来源，也可以使用与自我管理的 Grafana 服务器上相同的方法手动设置数据来源和必要的身份验证凭证。 需要满足一些先决条件，Amazon Managed Grafana 才能访问 Athena。有关与使用 Athena 数据来源相关的先决条件，请参阅 [先决条件](Athena-prereq.md)。 # 先决条件 要使用 Amazon Managed Grafana for Athena 的托管策略，请在配置 Athena 数据来源之前完成以下任务： + 用 `GrafanaDataSource: true` 标记您的 Athena 工作组。 + 创建名称以 `grafana-athena-query-results-` 开头的 S3 存储桶。此策略提供了所需的权限，可将查询结果写入符合该命名约定的 S3 存储桶。 用于访问 Athena 查询底层数据来源的 Amazon S3 权限不包含在此托管策略中。您必须手动为 Amazon S3 存储桶添加必要的权限 case-by-case。有关更多信息，请参阅此指南中 [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://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/) 1. 如果您在创建此工作空间时没有选择使用服务管理权限，请从使用客户托管权限更改为使用服务管理权限，以确保启用适当的 IAM 角色和策略以使用 Grafana 工作区控制台中的 AWS 数据源配置选项。为此，请按 **IAM 角色**选择编辑图标，然后选择**服务托管**、**保存更改**。有关更多信息，请参阅 [亚马逊托管 Grafana 数据源的权限和政策 AWS](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-settings) 中的步骤配置 **Athena 详细信息** ## **Athena 详细信息**设置 **配置 **Athena 详情**设置** 1. 在**连接详细信息**菜单中，选择身份验证提供者（推荐：**Workspace 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. 在**连接详细信息**菜单中，配置身份验证提供者（推荐：**Workspace 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_cn/grafana/latest/userguide/images/athena.png) # 使用 Athena 数据来源 ## IAM 策略 Grafana 需要通过 IAM 授予权限才能读取 Athena 指标。您可以将这些权限附加到 IAM 角色，并利用 Grafana 的内置支持来担任这些角色。请注意，在将数据来源添加到 Grafana 之前，您需要为角色[配置所需的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。添加数据来源需要管理员或编辑者角色。[AWS 托管策略： AmazonGrafanaAthenaAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonGrafanaAthenaAccess) 一节中定义了内置的 Amazon Grafana Athena 访问策略。 ## 查询 Athena 数据 Athena 数据来源提供了标准的 SQL 查询编辑器。Amazon Managed Grafana 包含一些宏来帮助编写更复杂的时间序列查询。 宏 | 宏 | 说明 | 示例 | 输出示例 | | --- | --- | --- | --- | | \$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)。 ## Annotations 使用 [Annotations](dashboard-annotations.md) 可以在图表上叠加丰富的事件信息。您可以通过选择面板添加注释，也可以使用**控制面板**菜单的**注释**视图，通过添加注释查询来添加注释。 自动添加注释的示例查询： ``` SELECT time as time, environment as tags, humidity as text FROM tableName WHERE $__dateFilter(time) and humidity > 95 ``` 下表为可用于呈现注释的列提供了说明： | Name | 说明 | | --- | --- | | Time | date/time 字段的名称。可以是具有本机 SQL date/time 数据类型或纪元值的列。 | | Timeend | 结束 date/time 字段的可选名称。可以是具有本机 SQL date/time 数据类型或纪元值的列。（Grafana v6.6\$1） | | Text | 事件描述字段。 | | Tags | 用于事件标签的可选字段名称，显示为以逗号分隔的字符串。 | ## 异步查询数据支持 Amazon Managed Grafana 中的 Athena 查询以异步方式处理，以避免超时。异步查询使用单独的请求启动查询，然后检查查询进度，最后获取结果。这样可以避免长时间运行的查询发生超时。 ## 查询结果重用 可以重复使用之前查询的结果来提高查询性能。要启用查询重用，请在查询编辑器的**查询结果重用**部分启用它。必须为每个要重用查询的查询执行此操作。 **注意** 此功能要求您的 Athena 实例使用引擎版本 3。有关详细信息，请参阅《Amazon Athena 用户指南》**中的[更改 Athena 引擎版本](https://docs.aws.amazon.com/athena/latest/ug/engine-versions-changing.html)。