AceDataCloud 上的生产 API 治理

生产 API 密钥不仅仅是一个秘密字符串。它是一个控制点，用于控制谁可以调用什么、他们可以消耗多少、访问持续多久、哪个应用付费，以及如何追踪事件。

AceDataCloud 在四个相互关联的层面提供这些控制：

1. 凭证签发 — 为特定应用创建密钥。
2. 应用余额策略 — 确定从何处扣除使用量，以及配额不足时会发生什么。
3. 使用情况可观测性 — 追踪状态、成本、延迟、API、应用和凭证。
4. 凭证生命周期 — 更新限制、轮换密钥和撤销访问权限。

本指南将平台的各项独立管理 API 整合为一个实用的运营模型。

¶ 首先，区分两种凭证

AceDataCloud 针对不同的使用界面使用不同的凭证：

凭证	用途	典型主机
账户令牌 / 平台令牌	账户管理：应用、凭证、余额、使用情况、订单	platform.acedata.cloud/api/v1/**
API 凭证	调用某项服务的业务 API	api.acedata.cloud/**

它们不可互换。业务 API 凭证不应被用于调用管理端点，平台令牌也不应作为应用的业务 API 密钥嵌入到应用中。

这种分离建立了一个有用的安全边界：

• 将平台令牌保存在严格受控的运维环境中。
• 为每个工作负载提供其自己的 API 凭证。
• 让运行时服务仅调用其所需的业务 API。
• 让 CI 或管理服务执行凭证和余额管理。

¶ 为每个工作负载和环境签发一个凭证

使用账户令牌通过 POST https://platform.acedata.cloud/api/v1/credentials/ 创建凭证。

一个面向生产的最小请求可以包含显示名称、独立消费限额、过期时间和 API 允许列表：

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"application_id\": \"${APPLICATION_ID}\",
    \"name\": \"prod-support-agent\",
    \"limited_amount\": 100,
    \"expired_at\": \"2027-01-01T00:00:00Z\",
    \"allowed_api_ids\": [\"${CHAT_API_ID}\"],
    \"metadata\": {\"environment\": \"production\", \"owner\": \"support-platform\"}
  }"

创建契约支持：

字段	治理目的
application_id	将使用量绑定到目标应用
name	使工作负载能够在审计中被识别
limited_amount	设置独立的凭证使用限额；null 表示没有独立限额
expired_at	建立自动的有时间限制的访问
allowed_api_ids	将凭证限制为选定的 API
host	在适用情况下存储凭证主机信息
for_user_id	允许应用所有者为另一位用户签发委派凭证
tags / metadata	记录环境、团队、系统或变更工单上下文

空的 allowed_api_ids 数组会被规范化为无限制。当你的意图是“什么都不允许”时，不要发送空数组。请使用实际的 API 允许列表。

API/Agent 服务通常会返回 Token 凭证。Proxy 服务通常会返回用户名/密码身份，并且一个 Proxy 应用只允许一个凭证。

将创建响应视为敏感信息。立即将密钥保存到密码管理器或密钥管理器中，并且不要将响应写入日志。客户端不应依赖明文密钥在后续仍可被检索；生命周期 API 可能会返回掩码值。

¶ 将限额用作爆炸半径控制，而不仅仅是预算

凭证级别的 limited_amount 对于限制泄露的密钥或失控的工作负载很有用，但它只是成本治理的一部分。

一个稳健的层级结构是：

• 凭证限额： 单个工作负载的最大风险暴露。
• 应用余额： 可供订阅服务应用使用的配额。
• 全局余额策略： 面向符合条件的按量付费应用的可选后备方案。
• 透支授权： 一项独立的只读平台授权，客户无法自行启用。

不要将这些视为等同的东西。

例如，即使应用拥有可用配额，单个凭证限额仍可能阻止该工作负载。反之，启用全局余额共享可能允许符合条件的应用在其自身余额不足后继续运行——但这不会移除凭证限额、禁用状态或过期检查。

¶ 使用单位和状态监控余额

通过以下方式查询应用：

curl --fail-with-body \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

在运维层面重要的字段包括：

• remaining_amount — 当前应用配额；负值表示等待结算的配额。
• used_amount — 为该应用报告的累计使用量。
• service.unit — 单位，例如 Credit、Count 或 Token。
• disabled — 应用是否被禁用。
• expired_at — 订阅访问是否已过期。
• allow_overdraft — 表明管理员已批准透支的只读指示。

永远不要假设金额是美元。告警阈值必须以服务的实际单位定义。

仅有正余额并不能证明可用性。你的健康检查应评估余额、disabled、过期时间、凭证限额和服务状态。对于 Proxy 服务，余额同步可能会暂停或超时，在这种情况下，可能会返回最近一次保存的余额。

一个简洁的 Python 检查：

import os
import requests

minimum = float(os.getenv("MINIMUM_BALANCE", "10"))
url = f"https://platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")

if application.get("disabled"):
    raise RuntimeError("Application is disabled")
if application.get("expired_at"):
    print("Check whether the Application expiry has passed:", application["expired_at"])
if remaining is None:
    raise RuntimeError("No balance is available for this Application")
if not application.get("allow_overdraft", False) and float(remaining) < minimum:
    raise RuntimeError(f"Low balance: {remaining} {unit}")

对于多个服务，应获取一次应用列表并在本地评估每个项目，而不是以高频率轮询每个应用详情端点。

¶ 明确决定是否允许全局余额共享

符合条件的按量付费应用可以配置为在其自身余额不足时使用账户的全局余额：

curl -X POST \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}/update-allow-consume-global/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"allow_consume_global": true}'

将返回的 allow_consume_global 值作为事实来源。不要假设请求的值已被保存。

重要限制：

• Period 应用无法消耗全局余额；服务器会将该字段保留为 false。
• 需要拥有的 application_id 和账户令牌。
• 如果 allow_overdraft=true，按量付费应用可以继续从其自身余额中扣除至零以下，并且不会仅仅因为其自身余额不足就切换到全局余额。
• 当发生后备切换时，透支行为由实际付款的全局应用决定。

全局后备可提高连续性，但它也会扩大财务爆炸半径。应将其作为经过审慎决定的服务级策略启用，而不是作为默认便利功能。

¶ 按凭证追踪每一次生产调用

AceDataCloud 保留最近 60 天的 API 调用记录和计费摘要。请求和响应正文保留 30 天；第 30–60 天的记录会保留摘要，但不再返回完整的 metadata.request 和 metadata.response 正文。

通过以下方式查询最新记录：

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode "credential_id=${CREDENTIAL_ID}" \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

有用的筛选器包括 application_id、api_id、credential_id、status_code 和 ISO 8601 时间范围。perspective 参数区分三种视图：

• billing — 由当前账户付费的调用。
• actor — 实际由当前账户发起的调用。
• both — 付费调用和发起调用的默认并集。 事件响应的关键字段包括：

字段	运维用途
credential_id	识别已暴露或发生故障的工作负载
trace_id	端到端调查单个请求
status_code	区分成功和失败的调用
elapsed	跟踪延迟
used_amount	按原始规则计算的使用量
original_amount	应用折扣前的使用量
deducted_amount	实际扣除的最终金额
remaining_amount	扣费后的应用配额
actor_user_id / user_id	区分调用方与负责付款的账户

对于大型查询，使用更短的时间窗口——最好为一天或更短——并添加筛选条件。如果相同查询已在运行，API 可能返回 429 usage_query_in_progress；请遵循 Retry-After 并进行退避。503 usage_query_timeout 表明应缩小请求范围，而不是立即重复请求。

¶ 在需要之前构建轮换和事件工作流

一个实用的响应手册如下：

1. 识别 使用记录或服务配置中的凭证。
2. 遏制 暴露风险，方法包括降低其限额、更改其到期时间、缩小 allowed_api_ids 范围或撤销它。
3. 轮换 密钥并更新密钥管理器。
4. 部署 新值到工作负载，且不记录它。
5. 验证 在预期凭证 ID 下的成功调用。
6. 审查 按凭证、状态、API 和追踪 ID 分类的近期记录。
7. 在确认切换完成后，撤销 过时的凭证。

为开发、预发布、生产、计划任务和第三方集成创建单独的凭证。这使轮换具有局部性，并使归因清晰。一个共享的“生产”密钥会最大化停机风险和调查歧义。

¶ 推荐的控制基线

对于每个生产工作负载：

• 专用 API 凭证；不跨环境共享。
• 描述性名称和所有权元数据。
• API 允许列表，仅包含所需的端点 ID。
• 与预期工作负载成比例的独立消费限额。
• 带有计划续期窗口的到期日期。
• 密钥存储在密钥管理器中，并排除在日志之外。
• 使用正确服务单位的应用余额告警。
• 检查禁用状态和到期状态，而不仅仅是余额。
• 对 allow_consume_global 作出明确决定。
• 按应用和凭证筛选的使用量仪表板。
• 在应用日志中捕获追踪 ID。
• 已记录的轮换和撤销流程。

¶ 治理是一个循环

凭证签发、余额监控和使用量追踪不应作为彼此独立的事务来管理。它们共同构成一个持续的控制循环：

严格签发 → 监控付款的应用 → 追踪实际调用 → 快速轮换或撤销。

AceDataCloud 的管理 API 提供了实现该循环所需的字段，而不会混淆管理访问、运行时访问、配额和计费归因。结果不仅仅是一个更安全的 API 密钥；它还是一个具有受限暴露范围和可解释使用量的生产系统。

¶ 官方资源

• 创建 AceDataCloud 平台 API 凭证
• 查询 AceDataCloud 应用余额
• 配置应用全局余额共享
• 获取 AceDataCloud 平台 API 调用记录
• AceDataCloud 平台控制台