本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 API 和 AWS 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 操作，或搭配 AWS 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>

下列範例將 `tagKey2` 從工作群組 `workgroupA` 中移除：

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

下列範例將 `tagKey2` 從資料目錄 `datacatalogA` 中移除：

```
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();
```

## 使用 管理標籤 AWS CLI
<a name="tags-operations-examples-cli"></a>

下列範例示範如何使用 AWS 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
```