本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 API 操作管理密钥标签
<a name="manage-tags-api"></a>

您可以使用 [AWS Payment Cryptography API](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/Welcome.html) 为您管理的密钥添加、删除和列出标签。这些示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。您无法标记 AWS 托管式密钥。

要添加、编辑、查看和删除密钥的标签，您必须具有所需的权限。有关更多信息，请参阅 [控制对标签的访问](tag-permissions.md)。

**Topics**
+ [CreateKey: 为新密钥添加标签](#tagging-keys-create-key)
+ [TagResource: 为密钥添加或更改标签](#tagging-keys-tag-resource)
+ [ListResourceTags: 获取密钥的标签](#tagging-keys-list-resource-tags)
+ [UntagResource: 从密钥中删除标签](#tagging-keys-untag-resource)

## CreateKey: 为新密钥添加标签
<a name="tagging-keys-create-key"></a>

您可以在创建密钥时向其添加标签。要指定标签，请使用[CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html)操作的`Tags`参数。

要在创建密钥时添加标签，调用方必须具有 IAM policy 中的 `payment-cryptography:TagResource` 权限。权限至少必须涵盖账户和区域中的所有密钥。有关更多信息，请参阅 [控制对标签的访问](tag-permissions.md)。

`CreateKey` 的 `Tags` 参数的值是区分大小写的标签键和标签值对的集合。密钥上的每个标签都必须具有不同的标签名称。标签值可为 null 或空字符串。

例如，以下 AWS CLI 命令创建带有`Project:Alpha`标签的对称加密密钥。指定多个键值对时，请使用空格分隔每个对。

```
$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY, \
        KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY, \
        KeyModesOfUse='{Generate=true,Verify=true}' \
        --tags '[{"Key":"Project","Value":"Alpha"},{"Key":"BIN","Value":"123456"}]'
```

当此命令成功时，它会返回一个 `Key` 对象以及有关新密钥的信息。但是，`Key` 不包括标签。要获取标签，请使用[ListResourceTags](#tagging-keys-list-resource-tags)操作。

## TagResource: 为密钥添加或更改标签
<a name="tagging-keys-tag-resource"></a>

该[TagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_TagResource.html)操作向密钥添加一个或多个标签。此操作不能用于添加或编辑不同 AWS 账户中的标签。

要添加标签，请指定新标签键和标签值。要编辑标签，请指定现有标签键和新标签值。密钥上的每个标签都必须具有不同的标签键。标签值可为 null 或空字符串。

例如，以下命令将 **UseCase** 和 **BIN** 标签添加到示例密钥中。

```
$ aws payment-cryptography tag-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h --tags '[{"Key":"UseCase","Value":"Acquiring"},{"Key":"BIN","Value":"123456"}]' 
```

此命令成功执行后，不会返回任何输出。要查看密钥上的标签，请使用[ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html)操作。

您也可以使用 **TagResource** 来更改现有标签的标签值。要替换标签值，请指定具有不同值的相同标签键。修改命令中未列出的标签不会被更改或删除。

例如，此命令会将 `Project` 标签的值从 `Alpha` 更改为 `Noe`。

该命令将返回 http/200，但不包含任何内容。要查看您的更改，请使用 `ListTagsForResource`

```
$ aws payment-cryptography tag-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \ 
        --tags '[{"Key":"Project","Value":"Noe"}]'
```

## ListResourceTags: 获取密钥的标签
<a name="tagging-keys-list-resource-tags"></a>

该[ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html)操作会获取密钥的标签。`ResourceArn`（keyArn 或 keyAlias）参数是必需的。此操作不能用于查看其他 AWS 账户中的密钥上的标签。

例如，以下命令获取示例密钥的标签。

```
$ aws payment-cryptography list-tags-for-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
       
  {
    "Tags": [
        {
            "Key": "BIN",
            "Value": "20151120"
        },
        {
            "Key": "Project",
            "Value": "Production"
        }
    ]
}
```

## UntagResource: 从密钥中删除标签
<a name="tagging-keys-untag-resource"></a>

该[UntagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_UntagResource.html)操作会从密钥中删除标签。要标识要删除的标签，请指定标签键。此操作不能用于从其他 AWS 账户中的密钥中删除标签。

当它成功时，`UntagResource` 操作不返回任何输出。此外，如果在密钥上未找到指定的标签键，则不会抛出异常或返回响应。要确认操作是否奏效，请使用该[ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html)操作。

例如，此命令将从指定的密钥中删除 **Purpose** 标签及其值。

```
$ aws payment-cryptography untag-resource \ 
        --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h --tag-keys Project
```