# 按缓存标签使内容失效
<a name="invalidation-by-tags"></a>

Amazon CloudFront 支持标签失效，这可让您根据语义标签而不是 URL 路径使缓存对象失效。这样，您就可以灵活地控制缓存失效，而不要求 URL 结构与失效策略相匹配。

## 标签失效的工作原理
<a name="invalidation-by-tags-how-it-works"></a>

1. **配置您的分配**：向您的分配中添加一个 ` CacheTagConfig`，指定源用来返回缓存标签的 HTTP 标头名称。

1. **在源处为对象添加标签**：当返回要使用标签来缓存的对象时，请将源配置为在 HTTP 响应中包含指定的标头，并使用逗号分隔的标签值。

   ```
   HTTP/1.1 200 OK
   Content-Type: text/html
   x-amz-meta-cache-tag: product:electronics, category:tv, brand:example
   Cache-Control: max-age=3600
   ```
**注意**  
对于 S3 源，您可以将缓存标签作为元数据附加到 S3 对象。您可以添加一个元数据条目，其中包含您选择的键（示例：` cache-tag`），并以逗号分隔的标签列表作为值（示例：`product:electronics, category:tv, brand:example`）。  
S3 将对象元数据显示为前缀为 ` x-amz-meta-<Key>` 的响应标头，因此元数据键 `cache-tag` 将作为 `x-amz-meta-cache-tag` 标头返回。您可以将 `CacheTagConfig` 中的 ` HeaderName` 设置为 ` x-amz-meta-cache-tag`，以支持向这些标签发送失效。
**注意**  
或者，您可以将源响应 Lambda@Edge 函数附加到缓存行为，以添加缓存标签标头。如果使用 Lambda@Edge，则标头名称无需遵循 `x-amz-meta-<Key>` 格式。

1. **按标签失效**：使用 ` CreateInvalidation` API 以及 `#` 前缀来使通过指定的标签缓存的所有对象失效。

   ```
   aws cloudfront create-invalidation \
     --distribution-id {{distribution_ID}} \
     --paths "#product:electronics"
   ```

   这将使包含标签 ` product:electronics` 的“所有”缓存对象失效，无论其 URL 路径如何。

## 标签格式要求
<a name="invalidation-by-tags-format"></a>

 **源响应标头值：**
+ 标签在标头值中以逗号分隔。
+ 每个标签周围的前导和尾随空格都会被修剪。
+ `tag1,tag2,tag3` 和 `tag1, tag2, tag3` 均有效且等效。

 **单个标签值：**
+ ASCII 可见字符（33–126）
+ 无控制字符、空格或逗号
+ 不区分大小写
+ 每个标签最多 256 个字符
+ 每个对象最多 50 个标签（忽略附加标签）

## 为标签失效配置分配
<a name="invalidation-by-tags-configuring"></a>

要启用标签失效，请向分配配置中添加 `CacheTagConfig`：

```
aws cloudfront create-distribution \
  --distribution-config '{
    "CallerReference": "my-distribution",
    "CacheTagConfig": {
      "HeaderName": "x-amz-meta-cache-tag"
    },
    "DefaultCacheBehavior": {
      "TargetOriginId": "myOrigin",
      "ViewerProtocolPolicy": "redirect-to-https",
      "CachePolicyId": "658327ea-f89d-4fab-a63d-7e88639e58f6"
    },
    "Origins": { ... },
    "Enabled": true,
    "Comment": "Distribution with tag support"
  }'
```

## 创建标签失效
<a name="invalidation-by-tags-creating"></a>

在 `--paths` 参数中使用 `#` 前缀来指定标签：

```
# Invalidate all objects tagged with "user1"
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "#user1"

# Invalidate objects matching any of multiple tags (OR logic)
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "#user1" "#product-category:electronics"

# Mix path and tag invalidations in one batch
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "/index.html" "#user1" "/images/*" "#product-category:electronics"
```

## 检查失效状态
<a name="invalidation-by-tags-checking-status"></a>

使用 `GetInvalidation` 来检查状态。响应同时包括路径项和标签项：

```
aws cloudfront get-invalidation \
  --distribution-id {{distribution_ID}} \
  --id {{invalidation_ID}}
```

## 重要注意事项
<a name="invalidation-by-tags-considerations"></a>
+ **需要选择加入**：标签失效仅适用于配置了 `CacheTagConfig` 的分配。没有此配置的分配会忽略源中的缓存标签标头。
+ **标签处理限制**：CloudFront 为每个缓存的对象最多处理 50 个标签。如果源响应包含 50 个以上的标签，则不会存储超出限制的其它标签。
+ **更改标头名称**：根据当前 `CacheTagConfig` 配置查找标签失效。如果您在 `CacheTagConfig` 中更改 `HeaderName`，则对使用旧标头名称下的标签缓存的对象发出的失效将不再进行评估。如果您需要更改标头名称，请开始将新的和旧的缓存标签标头与对象一起返回，接着发出路径失效（例如 `/*`）或使现有标签无效，然后再更改标头名称以避免提供陈旧内容。完成后，您可以停止将旧的缓存标签标头与对象一起发送。
+ **移除 CacheTagConfig**：当您从分配中移除 ` CacheTagConfig` 时，CloudFront 会停止从源响应中提取标签。带有标签的现有缓存对象将正常提供，直到它们过期或按路径失效。
+ **向后兼容**：现有路径和通配符失效继续保持不变。标签失效是累加的：您可以对同一个分配使用这两种方法。
+ **分配租户**：还支持通过 ` CreateInvalidationForDistributionTenant` API 对分配租户实施标签失效。

## 使用案例示例
<a name="invalidation-by-tags-examples"></a>

### 示例 1：电子商务产品目录
<a name="invalidation-by-tags-example-ecommerce"></a>

一个电子商务网站通过产品、类别和品牌为缓存的产品页面添加标签：

```
x-amz-meta-cache-tag: category:electronics, brand:acme, product:12345
```

当 ACME 更新其品牌时，会立即使所有 ACME 产品失效：

```
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "#brand:acme"
```

### 示例 2：用户生成的内容平台
<a name="invalidation-by-tags-example-ugc"></a>

平台使用拥有者的用户 ID 为缓存内容添加标签：

```
x-amz-meta-cache-tag: user:12345, content-type:image
```

当用户关闭其账户时，在您将其所有内容从源中移除后，使所有内容都失效：

```
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "#user:12345"
```

### 示例 3：内容版本控制
<a name="invalidation-by-tags-example-versioning"></a>

CMS 使用版本标识符来为内容添加标签：

```
x-amz-meta-cache-tag: version:v2, template:homepage
```

部署新版本时，使所有 v2 内容都失效：

```
aws cloudfront create-invalidation \
  --distribution-id {{distribution_ID}} \
  --paths "#version:v2"
```