AceDataCloud における本番 API ガバナンス

本番 API キーは単なる秘密文字列ではありません。これは、誰が何を呼び出せるか、どれだけ消費できるか、アクセスがどれだけ続くか、どのアプリケーションが支払うか、そしてインシデントをどのように追跡できるかを制御するポイントです。

AceDataCloud は、これらの制御を相互接続された 4 つのレイヤーにわたって公開しています。

1. 認証情報の発行 — 特定の Application 用のキーを作成します。
2. Application 残高ポリシー — 使用量がどこから差し引かれるか、およびクォータが少ない場合に何が起こるかを決定します。
3. 使用状況の可観測性 — ステータス、コスト、レイテンシ、API、Application、および認証情報を追跡します。
4. 認証情報のライフサイクル — 制限を更新し、シークレットをローテーションし、アクセスを取り消します。

このガイドでは、プラットフォームの個別の管理 API を 1 つの実用的な運用モデルにまとめます。

¶ まず、2 種類の認証情報を区別します

AceDataCloud は、異なるサーフェスに対して異なる認証情報を使用します。

認証情報	使用対象	典型的なホスト
Account Token / Platform Token	アカウント管理: Applications、認証情報、残高、使用量、注文	platform.acedata.cloud/api/v1/**
API Credential	サービスのビジネス API の呼び出し	api.acedata.cloud/**

これらは交換可能ではありません。ビジネス API の認証情報を管理エンドポイントの呼び出しに使用すべきではなく、Platform Token をアプリケーション内にビジネス API キーとして埋め込むべきではありません。

この分離により、有用なセキュリティ境界が作られます。

• Platform Token は厳格に管理された運用環境に保持します。
• 各ワークロードに固有の API Credential を付与します。
• ランタイムサービスには、必要なビジネス API のみを呼び出させます。
• CI または管理サービスに認証情報と残高の管理を実行させます。

¶ ワークロードと環境ごとに 1 つの認証情報を発行します

Account 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	使用量を対象の Application に紐付けます
name	監査においてワークロードを識別可能にします
limited_amount	独立した認証情報の使用上限を設定します。null は独立した上限なしを意味します
expired_at	自動的に期限が限定されたアクセスを確立します
allowed_api_ids	認証情報を選択された API に制限します
host	該当する場合に認証情報のホスト情報を保存します
for_user_id	Application 所有者が別のユーザー用に委任認証情報を発行できるようにします
tags / metadata	環境、チーム、システム、または変更チケットのコンテキストを記録します

空の allowed_api_ids 配列は、制限なしに正規化されます。「何も許可しない」という意図の場合は空の配列を送信しないでください。実際の API 許可リストを使用してください。

API/Agent サービスは通常 Token 認証情報を返します。Proxy サービスは通常ユーザー名/パスワードの ID を返し、Proxy Application では認証情報を 1 つだけ許可します。

作成レスポンスは機密情報として扱ってください。シークレットは直ちにパスワードマネージャーまたはシークレットマネージャーに保存し、レスポンスをログに書き込まないでください。クライアントは、平文のシークレットが後で引き続き取得可能であることに依存すべきではありません。ライフサイクル API はマスクされた値を返す場合があります。

¶ 上限は予算管理だけでなく、影響範囲の制御として使用します

認証情報レベルの limited_amount は、漏洩したキーや暴走したワークロードを抑制するために役立ちますが、コストガバナンスの一部にすぎません。

堅牢な階層は次のとおりです。

• 認証情報の上限: 1 つのワークロードに対する最大エクスポージャー。
• Application 残高: サブスクライブされたサービス Application で利用可能なクォータ。
• グローバル残高ポリシー: 対象となる従量課金 Application のための任意のフォールバック。
• 当座貸越承認: 顧客自身では有効化できない、独立した読み取り専用のプラットフォーム承認。

これらを同等のものとして扱わないでください。

たとえば、Application に利用可能なクォータがある場合でも、個々の認証情報上限によってワークロードがブロックされることがあります。逆に、グローバル残高共有を有効にすると、対象の Application は自身の残高が不足した後でも継続できる場合がありますが、認証情報の上限、無効化、または有効期限のチェックは解除されません。

¶ 単位とステータスを含めて残高を監視します

次のように Application を照会します。

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

運用上重要なフィールドには、以下が含まれます。

• remaining_amount — 現在の Application クォータ。負の値は、決済待ちのクォータを示します。
• used_amount — Application に対して報告された累積使用量。
• service.unit — Credit、Count、Token などの単位。
• disabled — Application が無効化されているかどうか。
• 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}")

複数のサービスについては、すべての Application 詳細エンドポイントを高頻度でポーリングする代わりに、Application リストを一度取得し、各項目をローカルで評価してください。

¶ グローバル残高共有を許可するかどうかを明示的に決定します

対象となる従量課金 Application は、自身の残高が不足している場合にアカウントのグローバル残高を使用するよう設定できます。

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 Application はグローバル残高を消費できません。サーバーはフィールドを false のまま維持します。
• 所有する application_id と Account Token が必要です。
• allow_overdraft=true の場合、従量課金 Application は自身の残高がゼロ未満でも引き続き差し引くことができ、自身の残高が不足したという理由だけでグローバル残高に切り替わることはありません。
• フォールバックが発生した場合、当座貸越の動作は実際に支払うグローバル Application によって決定されます。

グローバルフォールバックは継続性を向上させますが、財務上の影響範囲も拡大します。デフォルトの利便性としてではなく、意図的なサービスレベルポリシーとして有効にしてください。

¶ 認証情報ごとにすべての本番呼び出しを追跡します

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 パラメーターは、3 つのビューを分離します。

• billing — 現在のアカウントが支払った呼び出し。
• actor — 現在のアカウントが実際に開始した呼び出し。
• both — 支払い対象および開始された呼び出しのデフォルトの和集合。 インシデント対応の主要フィールドは次のとおりです。

フィールド	運用上の用途
credential_id	露出した、または誤作動しているワークロードを特定する
trace_id	1つのリクエストをエンドツーエンドで調査する
status_code	成功した呼び出しと失敗した呼び出しを分離する
elapsed	レイテンシを追跡する
used_amount	元のルールに基づいて計算された使用量
original_amount	Application 割引前の使用量
deducted_amount	実際に差し引かれた最終金額
remaining_amount	請求後の Application クォータ
actor_user_id / user_id	呼び出し元と支払い責任を負うアカウントを区別する

大規模なクエリでは、より短い期間（できれば1日以下）を使用し、フィルターを追加してください。同一のクエリがすでに実行中の場合、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 Credential。環境間で共有しない。
• 説明的な名前と所有者メタデータ。
• 必要なエンドポイント ID のみを含む API 許可リスト。
• 想定されるワークロードに比例した独立した消費上限。
• 計画された更新期間を伴う有効期限。
• シークレットマネージャーに保存され、ログから除外されたシークレット。
• 正しいサービス単位での Application 残高アラート。
• 残高だけでなく、無効化と有効期限のチェック。
• allow_consume_global に関する明示的な決定。
• Application と認証情報でフィルタリングされた使用状況ダッシュボード。
• アプリケーションログに記録されたトレース ID。
• 文書化されたローテーションおよび失効手順。

¶ ガバナンスはループである

認証情報の発行、残高監視、使用状況トレーシングは、別々の作業として管理すべきではありません。これらを組み合わせることで、継続的なコントロールループが形成されます。

限定的に発行 → 支払いを行う Application を監視 → 実際の呼び出しを追跡 → 迅速にローテーションまたは失効。

AceDataCloud の管理 API は、管理アクセス、ランタイムアクセス、クォータ、請求帰属を混同せずに、そのループを実装するために必要なフィールドを公開しています。その結果は、単により安全な API キーではありません。露出が限定され、使用状況を説明可能な本番システムです。

¶ 公式リソース

• AceDataCloud Platform API Credential を作成する
• AceDataCloud Application 残高を照会する
• Application のグローバル残高共有を設定する
• AceDataCloud Platform API 呼び出し記録を取得する
• AceDataCloud Platform コンソール