本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 標記 Athena 資源
每個標記皆包含由您定義的金鑰和值。標記 Athena 資源時，您可以將自訂中繼資料指派給該資源。您可以使用標籤以不同方式分類 AWS 資源，例如依用途、擁有者或環境。在 Athena 中，工作群組、資料目錄和容量保留等資源都是可標記的資源。例如，您可以為帳戶中的工作群組建立一組標籤，以協助您追蹤工作群組擁有者，或依用途來識別工作群組。如果您也在 Billing and Cost Management 主控台中啟用標籤作為成本分配標籤，則與執行查詢相關聯的成本會顯示在「成本和用量報告」中，並含有該成本分配標籤。我們建議您使用 AWS [ 標記最佳實務](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html)來建立一組一致的標籤，以滿足您組織的需求。
您可以使用 Athena 主控台或 API 操作來處理標籤。
**Topics**
+ [標籤基本概念](#tag-basics)
+ [標籤限制](#tag-restrictions)
+ [使用工作群組的標籤](tags-console.md)
+ [使用 API 和 AWS CLI 標籤操作](tags-operations.md)
+ [使用標籤型 IAM 存取控制政策](tags-access-control.md)
## 標籤基本概念
標籤是您指派給 Athena 資源的標籤。每個標籤皆包含由您定義的一個金鑰與一個選用值。
標籤可讓您以不同的方式分類 AWS 資源。例如，您可以為您帳戶的工作群組定義一組標籤，以協助您追蹤每個工作群組擁有者或用途。
您可以在建立新的 Athena 工作群組或資料目錄時新增標籤，或從中新增、編輯或移除標籤。您可以在主控台編輯標籤。如果您使用 API 操作來編輯標籤，請移除舊標籤，再加入新標籤。如果您刪除資源，也會刪除任何該資源所使用的標籤。
Athena 不會自動為您的資源指派標籤。您可以編輯標籤索引鍵和值，也可以隨時從資源中移除標籤。您可以將標籤的值設為空白字串，但您無法將標籤的值設為 Null。請勿將重複的標籤鍵新增至相同的資源。如果這樣做，Athena 會發出錯誤訊息。如果您使用 **TagResource** 動作來標記使用現有標籤鍵的資源，則新標籤值會覆寫舊值。
在 IAM 中，您可以控制 Amazon Web Services 帳戶中的哪些使用者具有建立、編輯、移除或列出標籤的許可。如需詳細資訊，請參閱[使用標籤型 IAM 存取控制政策](tags-access-control.md)。
如需 Amazon Athena 標籤動作的完整清單，請參閱 [Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)中的 API 動作名稱。
您可以使用標籤來計費。如需詳細資訊，請參閱《AWS 帳單與成本管理 使用者指南》**中的[使用標籤計費](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html)。
如需詳細資訊，請參閱[標籤限制](#tag-restrictions)。
## 標籤限制
標籤有以下限制：
+ 在 Athena 中，您可以標記工作群組、資料目錄和容量保留。您無法標記查詢。
+ 每一資源標籤數最多為 50。若要保持在限制內，請檢閱和刪除未使用的標籤。
+ 針對每一個資源，每個標籤鍵必須是唯一的，且每個標籤鍵只能有一個值。請勿將重複的標籤鍵同時新增到相同的工作群組。如果這樣做，Athena 會發出錯誤訊息。如果您在個別的 `TagResource` 動作中使用現有的標籤鍵來標記資源，新標籤值會覆寫舊值。
+ 標籤索引鍵長度為 1-128 個 UTF-8 Unicode 字元。
+ 標籤值長度為 0-256 個 UTF-8 Unicode 字元。
您需要指定工作群組資源的 ARN，才能執行標記操作，例如新增、編輯、移除或列出標籤。
+ Athena 可讓您使用字母、數字、以 UTF-8 表示的空格，以及下列字元：\$1 – = . \$1 : / @。
+ 標籤鍵與值皆區分大小寫。
+ 標籤索引鍵中的`"aws:"`字首保留供 AWS 使用。您無法編輯或刪除含有此字首的標籤索引鍵。含有此字首的標籤不算在每一資源的標籤限制內。
+ 您指派的標籤僅供 Amazon Web Services 帳戶使用。
# 使用工作群組的標籤
您可以使用 Athena 主控台，查看您帳戶中每個工作群組正在使用的標籤。您只能依工作群組來檢視標籤。Athena 主控台也可讓您一次在一個工作群組中套用、編輯或移除標籤。
您可以使用您建立的標籤來搜尋工作群組。
**Topics**
+ [顯示個別工作群組的標籤](#tags-display)
+ [在個別工作群組上新增和刪除標籤](#tags-add-delete)
## 顯示個別工作群組的標籤
**在 Athena 主控台中顯示個別工作群組的標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在導覽選單上，選擇 **Workgroups** (工作群組)，然後選擇您要的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤。如果標籤清單很長，請使用搜尋方塊。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
## 在個別工作群組上新增和刪除標籤
您可以直接從 **Workgroups** (工作群組) 索引標籤來管理個別工作群組的標籤。
**注意**
如果您希望使用者在主控台中建立工作群組時新增標籤，或在使用 **CreateWorkGroup** 動作時傳入標籤，請確定您授予使用者進行 **TagResource** 和 **CreateWorkGroup** 動作的 IAM 許可。
**在建立新的工作群組時新增標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽選單中，選擇 **Workgroups** (工作群組)。
1. 選擇 **Create workgroup** (建立工作群組)，並視需要填寫值。如需詳細步驟，請參閱[建立工作群組](creating-workgroups.md)。
1. 在 **Tags** (標籤) 區段中，指定索引鍵和值來新增一或多個標籤。請勿將重複的標籤索引鍵同時新增到相同的工作群組。如果這樣做，Athena 會發出錯誤訊息。如需詳細資訊，請參閱[標籤限制](tags.md#tag-restrictions)。
1. 完成時，選擇 **Create Workgroup** (建立工作群組)。
**在現有的工作群組中新增或編輯標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選擇您想要修改的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤，然後選擇 **Manage tags** (管理標籤)。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
1. 指定每個標籤的索引鍵和數值。如需詳細資訊，請參閱[標籤限制](tags.md#tag-restrictions)。
1. 選擇 **Save** (儲存)。
**從個別工作群組中刪除標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選擇您想要修改的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤，然後選擇 **Manage tags** (管理標籤)。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
1. 在標籤清單中，選取您要刪除標籤的 **Remove** (移除)，然後選擇 **Save** (儲存)。
# 使用 API 和 AWS CLI 標籤操作
使用下列標籤操作來新增、移除或列出資源上的標籤。
****
| API | CLI | 動作描述 |
| --- | --- | --- |
| TagResource | tag-resource | 在具有指定 ARN 的資源上新增或覆寫一或多個標籤。 |
| UntagResource | untag-resource | 從具有指定 ARN 的資源中刪除一個或多個標籤。 |
| ListTagsForResource | list‑tags‑for‑resource | 列出具有指定 ARN 之資源的一個或多個標籤。 |
**在建立資源時新增標籤**
若要在建立工作群組或資料目錄時新增標籤，請使用 `tags` 參數搭配 `CreateWorkGroup`或 `CreateDataCatalog` API 操作，或搭配 AWS CLI `create-work-group`或 `create-data-catalog`命令。
## 使用 API 動作管理標籤
下列範例說明如何使用標籤 API 操作來管理工作群組和資料目錄上的標籤。這些範例使用 Java 程式語言。
### 範例 – TagResource
下列範例將兩個標籤新增至工作群組 `workgroupA`：
```
List tags = new ArrayList<>();
tags.add(new Tag().withKey("tagKey1").withValue("tagValue1"));
tags.add(new Tag().withKey("tagKey2").withValue("tagValue2"));
TagResourceRequest request = new TagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA")
.withTags(tags);
client.tagResource(request);
```
下列範例將兩個標籤新增至資料目錄 `datacatalogA`：
```
List tags = new ArrayList<>();
tags.add(new Tag().withKey("tagKey1").withValue("tagValue1"));
tags.add(new Tag().withKey("tagKey2").withValue("tagValue2"));
TagResourceRequest request = new TagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA")
.withTags(tags);
client.tagResource(request);
```
**注意**
請勿將重複的標籤鍵新增至相同的資源。如果這樣做，Athena 會發出錯誤訊息。如果您在個別的 `TagResource` 動作中使用現有的標籤鍵來標記資源，新標籤值會覆寫舊值。
### 範例 – UntagResource
下列範例將 `tagKey2` 從工作群組 `workgroupA` 中移除：
```
List tagKeys = new ArrayList<>();
tagKeys.add("tagKey2");
UntagResourceRequest request = new UntagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA")
.withTagKeys(tagKeys);
client.untagResource(request);
```
下列範例將 `tagKey2` 從資料目錄 `datacatalogA` 中移除：
```
List tagKeys = new ArrayList<>();
tagKeys.add("tagKey2");
UntagResourceRequest request = new UntagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA")
.withTagKeys(tagKeys);
client.untagResource(request);
```
### 範例 – ListTagsForResource
下列範例列出工作群組 `workgroupA` 的標籤：
```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA");
ListTagsForResourceResult result = client.listTagsForResource(request);
List resultTags = result.getTags();
```
下列範例列出資料目錄 `datacatalogA` 的標籤：
```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA");
ListTagsForResourceResult result = client.listTagsForResource(request);
List resultTags = result.getTags();
```
## 使用 管理標籤 AWS CLI
下列範例示範如何使用 AWS CLI 來建立和管理資料目錄上的標籤。
### 新增標籤至資源：tag-resource
`tag-resource` 命令將一或多個標籤新增到指定的資源。
**語法**
`aws athena tag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tags Key=string,Value=string Key=string,Value=string`
`--resource-arn` 參數會指定要新增標籤的資源。`--tags` 參數會指定以空格分隔的鍵值組清單，以做為標籤新增至資源。
**Example**
下列範例會將標籤新增至 `mydatacatalog` 資料目錄。
```
aws athena tag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tags Key=Color,Value=Orange Key=Time,Value=Now
```
若要顯示結果，請使用 `list-tags-for-resource` 命令。
如需使用 `create-data-catalog` 命令時新增標籤的相關資訊，請參閱[註冊目錄：Create-data-catalog](datastores-hive-cli.md#datastores-hive-cli-registering-a-catalog)。
### 列出資源的標籤：list-tags-for-resource
`list-tags-for-resource` 命令會列出指定資源的標籤。
**語法**
`aws athena list-tags-for-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name`
`--resource-arn` 參數會指定列出標籤的資源。
下列範例列出 `mydatacatalog` 資料目錄的標籤。
```
aws athena list-tags-for-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog
```
以下樣本結果為 JSON 格式。
```
{
"Tags": [
{
"Key": "Time",
"Value": "Now"
},
{
"Key": "Color",
"Value": "Orange"
}
]
}
```
### 從資源移除標籤：untag-resource
`untag-resource` 命令會從指定的資源中刪除指定的標籤鍵及其關聯的數值。
**語法**
`aws athena untag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tag-keys key_name [key_name ...]`
`--resource-arn` 參數會指定要從中移除標籤的資源。`--tag-keys` 參數會取得以空格分隔的索引鍵名稱清單。對於指定的每個索引鍵名稱，`untag-resource` 命令會同時移除索引鍵及其數值。
下列範例會從 `mydatacatalog` 目錄資源中移除 `Color` 和 `Time` 索引鍵及其數值。
```
aws athena untag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tag-keys Color Time
```
# 使用標籤型 IAM 存取控制政策
使用標籤可讓您撰寫包含 `Condition` 區塊的 IAM 政策，以根據資源的標籤來控制對資源的存取。本節包含工作群組和資料目錄資源的標籤政策範例。
## 工作群組的標籤政策範例
### 範例 – 基本標籤政策
以下 IAM 政策可讓您執行查詢，並與名為 `workgroupA` 的工作群組的標籤互動：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListWorkGroups",
"athena:ListEngineVersions",
"athena:ListDataCatalogs",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"athena:GetWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery",
"athena:CreatePreparedStatement",
"athena:GetPreparedStatement",
"athena:ListPreparedStatements",
"athena:UpdatePreparedStatement",
"athena:DeletePreparedStatement"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA"
}
]
}
```
------
### 範例 – 根據標籤索引鍵和標籤值配對在工作群組上拒絕動作的政策區塊
與資源 (如工作群組) 相關聯的標籤稱為資源標籤。資源標籤可讓您編寫政策區塊，如以下項目在以鍵值組所標記的任何工作群組上拒絕列出的動作，例如 `stack`、`production`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"athena:GetWorkGroup",
"athena:UpdateWorkGroup",
"athena:DeleteWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery",
"athena:CreatePreparedStatement",
"athena:GetPreparedStatement",
"athena:ListPreparedStatements",
"athena:UpdatePreparedStatement",
"athena:DeletePreparedStatement"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/stack": "production"
}
}
}
]
}
```
------
### 範例 – 限制對指定的標籤提出標籤變更動作請求的政策區塊
做為參數傳入至變更標籤之操作的標籤 (例如帶有標籤的 `TagResource`、`UntagResource` 或 `CreateWorkGroup`) 稱為請求標籤。下列範例政策區塊只有在傳遞的其中一個標籤具有索引鍵 `costcenter` 和數值 `1`、`2` 或 `3` 時，才允許 `CreateWorkGroup` 操作。
**注意**
如果您想要允許 IAM 角色在 `CreateWorkGroup` 操作中傳入標籤，請確定您授予角色進行 `TagResource` 和 `CreateWorkGroup` 動作的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:CreateWorkGroup",
"athena:TagResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/costcenter": [
"1",
"2",
"3"
]
}
}
}
]
}
```
------
## 資料目錄的標籤政策範例
### 範例 – 基本標籤政策
以下 IAM 政策可讓您與名為 `datacatalogA` 的資料目錄的標籤互動：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListWorkGroups",
"athena:ListEngineVersions",
"athena:ListDataCatalogs",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"athena:GetWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery"
],
"Resource": [
"arn:aws:athena:us-east-1:123456789012:workgroup/*"
]
},
{
"Effect": "Allow",
"Action": [
"athena:CreateDataCatalog",
"athena:GetDataCatalog",
"athena:UpdateDataCatalog",
"athena:DeleteDataCatalog",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"
}
]
}
```
------
### 範例 – 根據標籤索引鍵和標籤值組在資料目錄上拒絕動作的政策區塊
您可以使用資源標籤撰寫政策區塊，以拒絕針對以特定標籤鍵值組標記的資料目錄上的特定動作。下列範例政策會拒絕具有標籤鍵值組 `stack`、`production` 的資料目錄上的動作。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"athena:CreateDataCatalog",
"athena:GetDataCatalog",
"athena:UpdateDataCatalog",
"athena:DeleteDataCatalog",
"athena:GetDatabase",
"athena:ListDatabases",
"athena:GetTableMetadata",
"athena:ListTableMetadata",
"athena:StartQueryExecution",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/stack": "production"
}
}
}
]
}
```
------
### 範例 – 限制對指定的標籤提出標籤變更動作請求的政策區塊
做為參數傳入至變更標籤之操作的標籤 (例如帶有標籤的 `TagResource`、`UntagResource` 或 `CreateDataCatalog`) 稱為請求標籤。下列範例政策區塊只有在傳遞的其中一個標籤具有索引鍵 `costcenter` 和數值 `1`、`2` 或 `3` 時，才允許 `CreateDataCatalog` 操作。
**注意**
如果您想要允許 IAM 角色在 `CreateDataCatalog` 操作中傳入標籤，請確定您授予角色進行 `TagResource` 和 `CreateDataCatalog` 動作的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:CreateDataCatalog",
"athena:TagResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/costcenter": [
"1",
"2",
"3"
]
}
}
}
]
}
```
------