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

# 標記 Amazon Cognito 資源
<a name="tagging"></a>

*標籤*是您或 AWS 指派給 資源的 AWS 中繼資料標籤。每個標籤皆包含*鍵*與*值*。對於您指派的標籤，您可以定義索引鍵和值。例如，您可以將鍵定義為 `stage`，將資源的值定義為 `test`。

標籤可協助您執行以下操作：
+ 識別和組織您的 AWS 資源。許多 AWS 服務支援標記，因此您可以將相同的標籤指派給來自不同 服務的資源。這可協助您指出哪些資源是相關的。例如，您可以將指派給 Amazon DynamoDB 資料表的相同標籤指派給 Amazon Cognito 使用者集區。
+ 追蹤您的 AWS 成本。您可以在 AWS 帳單與成本管理 儀表板上啟用這些標籤。 AWS 使用成本分配標籤來分類您的成本，並為您提供每月成本分配報告。如需詳細資訊，請參閱《*AWS Billing 使用者指南*》中的[使用成本配置標籤](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html)。
+ 根據資源獲派的標籤，控制資源的存取權。您可以透過在 AWS Identity and Access Management (IAM) 政策條件中指定標籤索引鍵和值，控制存取。例如，您可以允許使用者更新使用者集區，但該使用者集區的 `owner` 標籤值必須包含該使用者名稱。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[使用標籤控制存取權限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html)。

您可以使用 AWS Command Line Interface 或 Amazon Cognito API 來新增、編輯或刪除使用者和身分集區的標籤。您還可以使用 Amazon Cognito 主控台來管理使用者集區的標籤。

如需使用標籤的提示，請參閱 *AWS 回答*部落格上的 [AWS 標記策略](https://aws.amazon.com/answers/account-management/aws-tagging-strategies/)文章。

以下章節提供 Amazon Cognito 標籤的詳細資訊。

## Amazon Cognito 中支援的資源
<a name="tagging-supported-resources"></a>

Amazon Cognito 中的以下資源支援標記：
+ 使用者集區
+ 身分集區

## 標籤限制
<a name="tagging-restrictions"></a>

以下限制適用於 Amazon Cognito 資源上的標籤：
+ 您可以指派給資源的標籤數量上限 – 50 
+ 金鑰長度上限 - 128 個 Unicode 字元 
+ 數值長度上限 - 256 個 Unicode 字元 
+ 索引鍵與值的有效字元 – a-z、A-Z、0-9、空格和下列字元：\$1 . : / = \$1 - @
+ 鍵和值會區分大小寫
+ 請不要使用 `aws:` 做為鍵的字首；它已保留供 AWS 使用

## 使用 Amazon Cognito 主控台管理標籤
<a name="tagging-console"></a>

您可以使用 Amazon Cognito 主控台，管理指派給您的使用者集區的標籤。

**新增標籤至使用者集區**

1. 導覽至 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。如果出現提示，請輸入您的 AWS 登入資料。

1. 選擇 **User Pools** (使用者集區)。

1. 從清單中選擇現有的使用者集區，或[建立使用者集區](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。

1. 選擇**設定**選單並找到**標籤**索引標籤。

1. 選擇 **Add tags** (新增標籤) 以新增您的第一個標籤。如果您先前在 **Manage tags** (管理標籤) 中已將標籤指派給此使用者集區，則請選擇 **Add another** (新增另一個)。

1. 指定 **Tag key (標籤金鑰)** 和 **Tag value (標籤值)** 的值。

1. 對於您要新增的每個額外標籤，請選擇 **Add another** (新增另一個)。

1. 當您完成新增標籤的作業時，請選擇 **Save changes (儲存變更)**。

若要標記身分集區，請導覽至**身分集區**功能表，然後選取或建立身分集區。在**身分集區屬性**索引標籤中，尋找**標籤**。選擇 **Add tag (新增標籤)**。

## AWS CLI 範例
<a name="tagging-cli-examples"></a>

 AWS CLI 提供的命令可協助您管理指派給 Amazon Cognito 使用者集區和身分集區的標籤。

### 指派標籤
<a name="tagging-cli-examples-assigning"></a>

使用下列命令，將標籤指派給現有的使用者集區和身分集區。

**Example 使用者集區適用的 `tag-resource` 命令**  
使用 `cognito-idp` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/tag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/tag-resource.html) 指派標籤給使用者集區：  

```
$ aws cognito-idp tag-resource \
> --resource-arn user-pool-arn \
> --tags Stage=Test
```
此命令包括下列參數：  
+ `resource-arn` – 您要將標籤套用其中之使用者集區的 Amazon Resource Name (ARN)。若要查詢 ARN，請在 Amazon Cognito 主控台中選擇使用者集區，然後檢視 **General settings (一般設定)** 索引標籤上的 **Pool ARN (集區 ARN)** 值。
+ `tags` – 標籤的鍵值組，格式為 `key=value`。
若要一次指派多個標籤，請以逗號分隔清單指定這些標籤：  

```
$ aws cognito-idp tag-resource \
> --resource-arn user-pool-arn \
> --tags Stage=Test,CostCenter=80432,Owner=SysEng
```

**Example 身分集區適用的 `tag-resource` 命令**  
使用 `cognito-identity` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/tag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/tag-resource.html) 指派標記給身分集區：  

```
$ aws cognito-identity tag-resource \
> --resource-arn identity-pool-arn \
> --tags Stage=Test
```
此命令包括下列參數：  
+ `resource-arn` – 您要將標籤套用其中之身分集區的 Amazon Resource Name (ARN)。若要查詢 ARN，請在 Amazon Cognito 主控台中選擇該身分集區，然後選擇 **Edit identity pool (編輯身分集區)**。接著，在 **Identity pool ID (身分集區 ID)** 中，選擇 **Show ARN (顯示 ARN)**。
+ `tags` – 標籤的鍵值組，格式為 `key=value`。
若要一次指派多個標籤，請以逗號分隔清單指定這些標籤：  

```
$ aws cognito-identity tag-resource \
> --resource-arn identity-pool-arn \
> --tags Stage=Test,CostCenter=80432,Owner=SysEng
```

### 檢視標籤
<a name="tagging-cli-examples-viewing"></a>

使用下列命令，檢視您已指派給您的使用者集區和身分集區的標籤。

**Example 使用者集區適用的 `list-tags-for-resource` 命令**  
使用 `cognito-idp` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/list-tags-for-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/list-tags-for-resource.html) 檢視指派給使用者集區的標籤：  

```
$ aws cognito-idp list-tags-for-resource --resource-arn user-pool-arn
```

**Example 身分集區適用的 `list-tags-for-resource` 命令**  
使用 `cognito-identity` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/list-tags-for-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/list-tags-for-resource.html) 檢視指派給身分集區的標籤：  

```
$ aws cognito-identity list-tags-for-resource --resource-arn identity-pool-arn
```

### 移除標籤
<a name="tagging-cli-examples-removing"></a>

使用下列命令，將標籤自您的使用者集區和身分集區上移除。

**Example 使用者集區適用的 `untag-resource` 命令**  
使用 `cognito-idp` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/untag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/untag-resource.html) 從使用者集區移除標籤：  

```
$ aws cognito-idp untag-resource \
> --resource-arn user-pool-arn \
> --tag-keys Stage CostCenter Owner
```
對於 `--tag-keys` 參數，請指定一或多個標籤索引鍵。請勿包含標籤值。請使用空格分隔索引鍵。

**Example 身分集區適用的 `untag-resource` 命令**  
使用 `cognito-identity` 命令集內的 [https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/untag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/untag-resource.html) 從身分集區移除標籤：  

```
$ aws cognito-identity untag-resource \
> --resource-arn identity-pool-arn \
> --tag-keys Stage CostCenter Owner
```
對於 `--tag-keys` 參數，請指定一或多個標籤索引鍵。請勿包含標籤值。

**重要**  
刪除使用者或身分集區後，與所刪除集區相關的標籤在刪除後仍然會顯示於主控台或 API 呼叫中最多 30 天。

### 在建立資源時套用標籤
<a name="tagging-cli-examples-applying"></a>

使用下列命令，在您建立使用者集區或身分集區時指派標籤。

**Example 搭配標籤的 `create-user-pool` 命令**  
當您使用 [https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/create-user-pool.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/create-user-pool.html) 命令建立使用者集區時，您可以搭配 `--user-pool-tags` 參數指定標籤：  

```
$ aws cognito-idp create-user-pool \
> --pool-name user-pool-name \
> --user-pool-tags Stage=Test,CostCenter=80432,Owner=SysEng
```
標籤的鍵值組必須是 `key=value` 格式。如果是新增多個標籤，請以逗號分隔清單指定這些標籤。

**Example 搭配標籤的 `create-identity-pool` 命令**  
當您使用 [https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/create-identity-pool.html](https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/create-identity-pool.html) 命令建立身分集區時，您可以搭配 `--identity-pool-tags` 參數指定標籤：  

```
$ aws cognito-identity create-identity-pool \
> --identity-pool-name identity-pool-name \
> --allow-unauthenticated-identities \
> --identity-pool-tags Stage=Test,CostCenter=80432,Owner=SysEng
```
標籤的鍵值組必須是 `key=value` 格式。如果是新增多個標籤，請以逗號分隔清單指定這些標籤。

## 使用 Amazon Cognito API 管理標籤
<a name="tagging-api"></a>

您可以在 Amazon Cognito API 中使用下列動作，為您的使用者集區和身分集區管理標籤。

### 使用者集區標籤適用的 API 動作
<a name="tagging-api-user-pools"></a>

使用以下 API 動作，指派、檢視和移除使用者集區的標籤。
+ [TagResource](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_TagResource.html)
+ [ListTagsForResource](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListTagsForResource.html)
+ [UntagResource](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UntagResource.html)
+ [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)

### 身分集區標籤適用的 API 動作
<a name="tagging-api-identity-pools"></a>

使用以下 API 動作，指派、檢視和移除身分集區的標籤。
+ [TagResource](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_TagResource.html)
+ [ListTagsForResource](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_ListTagsForResource.html)
+ [UntagResource](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_UntagResource.html)
+ [CreateIdentityPool](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_CreateIdentityPool.html)