# Athena リソースにタグ付けする
タグは、1 つのキーと 1 つの値で構成されており、どちらもお客様側が定義します。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 リソースに割り当てるラベルです。タグはそれぞれ、1 つのキーとオプションの 1 つの値で構成されており、どちらもお客様側が定義します。
タグを使用すると、さまざまな方法で 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 Billing and Cost Management ユーザーガイド*」の「[請求へのタグの使用](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html)」を参照してください。
詳細については、「[タグの制限](#tag-restrictions)」を参照してください。
## タグの制限
タグには、次の制約があります。
+ Athena では、ワークグループ、データカタログ、およびキャパシティ予約にタグを付けることができます。クエリにタグを付けることはできません。
+ リソースあたりのタグの最大数は 50 です。制限内に収まるようにするには、未使用のタグを確認して削除します。
+ タグキーは、リソースごとにそれぞれ一意である必要があります。また、各タグキーに設定できる値は 1 つのみです。同じリソースに重複したタグキーを同時に追加しないでください。そのようにした場合には、Athena はエラーメッセージを発行します。別の `TagResource` アクションで既存のタグキーを使用してリソースにタグを付けると、新しいタグ値によって古い値が上書きされます。
+ タグキーの長さは、1～128 文字 (Unicode) (UTF-8) です。
+ タグ値の長さは、0～256 文字 (Unicode) (UTF-8) です。
タグの追加、編集、削除、一覧表示などのタグ付けオペレーションでは、ワークグループリソースの ARN を指定する必要があります。
+ Athena では、文字、数字、UTF-8 で表現されたスペース、および \$1 - = . \$1 : / @ の文字を使用できます。
+ タグのキーと値は大文字と小文字が区別されます。
+ タグキーの `"aws:"` プレフィックスは、AWS 用に予約されています。このプレフィックスが含まれるタグキーを編集したり削除することはできません。このプレフィックスを持つタグは、リソースあたりのタグ数の制限時には計算されません。
+ 割り当てたタグは、お客様の Amazon Web Services アカウントだけに使用できます。
# ワークグループのタグを使用する
Athena コンソールを使用すると、アカウントの各ワークグループでどのタグが使用されているかを確認できます。ワークグループでのみタグを表示できます。また、Athena コンソールを使用して、一度に 1 つのワークグループに対してタグの適用、編集、または削除を行うことができます。
作成したタグを使用してワークグループを検索できます。
**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/ja_jp/athena/latest/ug/images/nav-pane-expansion.png)
1. ナビゲーションメニューで、**[Workgroups]** (ワークグループ) 選択し、ワークグループを選択します。
1. 次のいずれかを行います。
+ **[タグ]** タブを選択します。タグのリストが長い場合は、検索ボックスを使用します。
+ **[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]** (タグ) セクションで、キーと値を指定して、1 つ以上のタグを追加します。同じワークグループに重複したタグキーを同時に追加しないでください。そのようにした場合には、Athena はエラーメッセージを発行します。詳細については、「[タグの制限](tags.md#tag-restrictions)」を参照してください
1. 終了したら、**[Create workgroup]** (ワークグループを作成する) をクリックします。
**既存のワークグループにタグを追加または編集する**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. ナビゲーションペインで、[**Global networks (グローバルネットワーク)**] を選択します。
1. 変更するワークグループを選択します。
1. 次のいずれかを行います。
+ **[タグ]** タブを選択し、**[タグ管理]** を選択します。
+ **[Edit]** (編集) を選択し、**[Tags]** (タグ) セクションまで下にスクロールします。
1. タグごとにキーと値を指定します。詳細については、「[タグの制限](tags.md#tag-restrictions)」を参照してください。
1. **[保存]** を選択します。
**個々のワークグループからタグを削除する**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. ナビゲーションペインで、[**Global networks (グローバルネットワーク)**] を選択します。
1. 変更するワークグループを選択します。
1. 次のいずれかを行います。
+ **[タグ]** タブを選択し、**[タグ管理]** を選択します。
+ **[Edit]** (編集) を選択し、**[Tags]** (タグ) セクションまで下にスクロールします。
1. タグのリストで、削除するタグの **[Remove]** (削除) ボタンをクリックし、**[Save]** (保存) を選択します。
# API および AWS CLI タグオペレーションを使用する
次のタグオペレーションを使用して、リソースのタグを追加、削除、または一覧表示します。
****
| API | CLI | アクションの説明 |
| --- | --- | --- |
| TagResource | tag-resource | 指定した ARN を持つリソースの 1 つ以上のタグを追加または上書きします。 |
| UntagResource | untag-resource | 指定した ARN を持つリソースから 1 つ以上のタグを削除します。 |
| ListTagsForResource | list‑tags‑for‑resource | 指定した ARN を持つリソースの 1 つ以上のタグを一覧表示します。 |
**リソースを作成する際にタグを追加する**
ワークグループまたはデータカタログの作成時にタグを追加するには、`tags` パラメータを `CreateWorkGroup` または `CreateDataCatalog` API オペレーション、あるいは AWS CLI の `create-work-group` または `create-data-catalog` コマンドで使用します。
## API アクションを使用してタグを管理する
次の例は、タグ API アクションを使用して、ワークグループおよびデータカタログのタグを管理する方法を示しています。例は、Java プログラミング言語で記述されています。
### 例 – TagResource
次の例では、ワークグループ `workgroupA` に 2 つのタグを追加します。
```
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` に 2 つのタグを追加します。
```
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` コマンドは、指定されたリソースに 1 つ以上のタグを追加します。
**構文**
`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)」(カタログを登録する: Create-data-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` コマンドは、指定されたキー名ごとに、キーとその値の両方を削除します。
次の例では、`Color` カタログリソースから `Time` および `mydatacatalog` キーとそれぞれの値を削除します。
```
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` など) にパラメータとして渡されるタグは、リクエストタグと呼ばれます。次のポリシーブロックの例では、渡されたタグのいずれかがキー `CreateWorkGroup` と値 `costcenter`、`1`、または `2` を持つ場合にのみ、`3` オペレーションを許可します。
**注記**
`CreateWorkGroup` オペレーションの一環としてタグを渡すことを IAM ロールに許可する場合は、そのロールに `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` など) にパラメータとして渡されるタグは、リクエストタグと呼ばれます。次のポリシーブロックの例では、渡されたタグのいずれかがキー `CreateDataCatalog` と値 `costcenter`、`1`、または `2` を持つ場合にのみ、`3` オペレーションを許可します。
**注記**
`CreateDataCatalog` オペレーションの一環としてタグを渡すことを IAM ロールに許可する場合は、そのロールに `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"
]
}
}
}
]
}
```
------