# 使用 API 和 Amazon CLI 标签操作
<a name="tags-operations"></a>

使用以下标签操作在资源中添加、删除或列出标签。


****  

| API | CLI | 操作描述 | 
| --- | --- | --- | 
| TagResource | tag-resource | 在具有指定 ARN 的资源上添加或覆盖一个或多个标签。 | 
| UntagResource | untag-resource | 从具有指定 ARN 的资源中删除一个或多个标签。 | 
| ListTagsForResource | list‑tags‑for‑resource | 列出具有指定 ARN 的资源的一个或多个标签。 | 

**在创建资源时添加标签**  
要在创建工作组或数据目录时添加标签，请将 `tags` 参数与 `CreateWorkGroup` 或 `CreateDataCatalog` API 操作结合使用，或者将该参数与 Amazon CLI `create-work-group` 或 `create-data-catalog` 命令结合使用。

## 使用 API 操作管理标签
<a name="tags-operations-examples-java"></a>

以下示例说明如何使用标签 API 操作来管理工作组和数据目录上的标签。这些示例采用的是 Java 编程语言。

### 示例：TagResource
<a name="tags-operations-examples-java-tag-resource"></a>

以下示例将两个标签添加到工作组 `workgroupA` 中：

```
List<Tag> 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<Tag> 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
<a name="tags-operations-examples-java-untag-resource"></a>

以下示例从工作组 `workgroupA` 中删除 `tagKey2`：

```
List<String> 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);
```

以下示例从数据目录 `datacatalogA` 中删除 `tagKey2`：

```
List<String> 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
<a name="tags-operations-examples-java-list-tags-for-resource"></a>

以下示例列出了工作组 `workgroupA` 的标签：

```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
    .withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA");

ListTagsForResourceResult result = client.listTagsForResource(request);

List<Tag> resultTags = result.getTags();
```

以下示例列出了数据目录 `datacatalogA` 的标签：

```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
    .withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA");

ListTagsForResourceResult result = client.listTagsForResource(request);

List<Tag> resultTags = result.getTags();
```

## 使用 Amazon CLI 管理标签
<a name="tags-operations-examples-cli"></a>

以下示例说明如何使用 Amazon CLI 创建和管理数据目录上的标签。

### 将标签添加到资源：tag-resource
<a name="tags-operations-examples-cli-tag-resource"></a>

`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
<a name="tags-operations-examples-cli-list-tags-for-resource"></a>

`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
<a name="tags-operations-examples-cli-untag-resource"></a>

`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
```