AceDataCloud 上的生產 API 治理

生產 API 金鑰不只是一串祕密字串。它是用於控制 誰可以呼叫什麼、他們可以使用多少、存取持續多久、由哪個應用程式付款，以及如何追蹤事件 的控制點。

AceDataCloud 透過四個相互連接的層級公開這些控制：

憑證簽發 — 為特定應用程式建立金鑰。
應用程式餘額政策 — 決定從何處扣除使用量，以及配額不足時會發生什麼。
使用量可觀測性 — 追蹤狀態、成本、延遲、API、應用程式和憑證。
憑證生命週期 — 更新限制、輪替祕密，以及撤銷存取權。

生產 API 治理控制迴路

本指南將平台的個別管理 API 整合為一個實用的操作模型。

¶ 首先，區分兩種憑證

AceDataCloud 對不同介面使用不同憑證：

憑證	用於	典型主機
帳戶 Token / 平台 Token	帳戶管理：應用程式、憑證、餘額、使用量、訂單	`platform.acedata.cloud/api/v1/**`
API 憑證	呼叫服務的業務 API	`api.acedata.cloud/**`

它們不可互換。業務 API 憑證不應用於呼叫管理端點，平台 Token 也不應作為業務 API 金鑰嵌入應用程式中。

這種分離建立了有用的安全邊界：

將平台 Token 保存在受到嚴格控制的營運環境中。
為每個工作負載提供各自的 API 憑證。
讓執行階段服務只呼叫其所需的業務 API。
讓 CI 或管理服務執行憑證和餘額管理。

¶ 為每個工作負載和環境簽發一個憑證

使用帳戶 Token，透過 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 和帳戶 Token。
如果 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`	套用 Application 折扣前的用量
`deducted_amount`	實際扣除的最終金額
`remaining_amount`	扣款後的 Application 配額
`actor_user_id` / `user_id`	區分呼叫者與負責付款的帳戶

對於大型查詢，請使用較短的時間範圍——最好一天或更短——並加入篩選條件。若已有相同的查詢正在執行，API 可能會回傳 429 usage_query_in_progress；請依照 Retry-After 並採用退避機制。503 usage_query_timeout 是應縮小請求範圍的訊號，而不是立即重複執行。

¶ 在需要之前建立輪替與事件工作流程

實用的回應手冊如下：

識別使用量記錄或服務設定中的憑證。
透過降低其限制、變更其到期日、縮小 allowed_api_ids，或撤銷它來控制暴露情況。
輪替密鑰並更新密鑰管理器。
將新值部署至工作負載，而不記錄它。
驗證預期憑證 ID 下的成功呼叫。
依憑證、狀態、API 與追蹤 ID 檢視近期記錄。
在確認切換完成後撤銷過時的憑證。

為開發、預備環境、生產環境、排程工作與第三方整合建立獨立的憑證。這能使輪替範圍保持在局部，並讓歸屬清楚明確。單一共用的「production」金鑰會同時最大化中斷風險與調查上的模糊性。

¶ 建議的控制基準

對於每個生產工作負載：

¶ 治理是一個循環

憑證簽發、餘額監控與使用量追蹤不應作為獨立的工作來管理。它們共同形成一個持續的控制循環：

精確簽發 → 監控付款的 Application → 追蹤實際呼叫 → 快速輪替或撤銷。

AceDataCloud 的管理 API 提供了實作該循環所需的欄位，且不會混淆管理存取權、執行階段存取權、配額與帳務歸屬。結果不僅僅是更安全的 API 金鑰；它是一個具有可控暴露範圍與可解釋使用量的生產系統。

AceDataCloud 上的生產 API 治理：憑證、餘額控制與使用量監控