跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

快速入门

最后更新 查看 MarkdownAgent 设置

本指南将引导您验证您的账户是否已启用标记功能，并进行您的首次 API 调用。

前提条件

  • 至少有一个用户拥有 Super Administrator（超级管理员）、Workers Admin（Workers 管理员）或 Tag Admin（标签管理员）角色。这些角色可以创建、更新和删除标签。
  • API 是管理标签的首选接口。您也可以在仪表板的 Manage Account（管理账户）> **Resource Tagging（资源标记）**下管理标签，但您应当熟悉如何为自动化工作流发送经过身份验证的 HTTP 请求。
  • 具有所需权限的 API 令牌。推荐使用 账户所有令牌 (Account Owned Tokens) 进行自动化操作。

1. 验证标记功能是否已启用

测试 API 以确认您的账户中标记功能已处于活动状态：

curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/keys" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json"

响应结果说明

响应 含义 对应操作
200 OK 且返回 {"success": true, "result": [...]} 标记功能已启用。如果尚未创建任何标签，返回空数组是正常的。 继续下一步。
403 提到 "permission"（权限）或 "role"（角色） 调用方缺少所需的权限。 验证调用方是否拥有 Super Admin、Workers Admin 或 Tag Admin 角色，或者令牌是否具有 #com.cloudflare.api.account.tag.list 作用域。
403 提到 "feature"（功能）或 "gate"（限制） 该账户未启用标记功能。 联系 Cloudflare 支持 寻求帮助。
401 Unauthorized 身份验证失败。 验证令牌是否有效、未过期，以及在 Authorization: Bearer 标头中的格式是否正确。
其他任何响应 意外错误。 记录完整的响应正文，并联系 Cloudflare 支持，提供您的 Account ID、请求详情和时间戳。

2. 创建您的首个标签

使用 PUT 在资源上设置标签：

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "worker",
    "resource_id": "'"$RESOURCE_ID"'",
    "tags": {
      "environment": "production",
      "team": "platform"
    }
  }'

然后检索这些标签：

curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags?resource_type=worker&resource_id=$RESOURCE_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json"

3. 列出已标记的资源

查询账户中所有已标记的资源，可选择按标签进行过滤：

# 所有已标记的资源
curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources" \
  -H "Authorization: Bearer $API_TOKEN"

# 过滤：仅包含 environment=production 的资源
curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production" \
  -H "Authorization: Bearer $API_TOKEN"

后续步骤

这篇文档对您有帮助吗？