Produktions-API-Governance auf AceDataCloud

Ein Produktions-API-Schlüssel ist nicht nur eine geheime Zeichenfolge. Er ist ein Kontrollpunkt dafür, wer was aufrufen kann, wie viel sie verbrauchen können, wie lange der Zugriff dauert, welche Anwendung bezahlt und wie ein Vorfall nachverfolgt werden kann.

AceDataCloud stellt diese Kontrollen über vier verbundene Ebenen bereit:

Ausstellung von Zugangsdaten — einen Schlüssel für eine bestimmte Anwendung erstellen.
Anwendungsguthabenrichtlinie — bestimmen, wo die Nutzung abgezogen wird und was passiert, wenn das Kontingent niedrig ist.
Nutzungsbeobachtbarkeit — Status, Kosten, Latenz, API, Anwendung und Zugangsdaten nachverfolgen.
Lebenszyklus der Zugangsdaten — Einschränkungen aktualisieren, Geheimnisse rotieren und Zugriff widerrufen.

Kontrollschleife für Produktions-API-Governance

Dieser Leitfaden fasst die einzelnen Management-APIs der Plattform zu einem praktischen Betriebsmodell zusammen.

¶ Zuerst die beiden Arten von Zugangsdaten trennen

AceDataCloud verwendet unterschiedliche Zugangsdaten für unterschiedliche Oberflächen:

Zugangsdaten	Verwendet für	Typischer Host
Account Token / Platform Token	Kontoverwaltung: Anwendungen, Zugangsdaten, Guthaben, Nutzung, Bestellungen	`platform.acedata.cloud/api/v1/**`
API Credential	Aufruf von Geschäfts-APIs für einen Dienst	`api.acedata.cloud/**`

Sie sind nicht austauschbar. Eine Geschäfts-API-Zugangsdaten sollten nicht zum Aufrufen von Management-Endpunkten verwendet werden, und ein Platform Token sollte nicht als Geschäfts-API-Schlüssel in eine Anwendung eingebettet werden.

Diese Trennung schafft eine nützliche Sicherheitsgrenze:

Bewahren Sie Platform Tokens in einer streng kontrollierten Betriebsumgebung auf.
Geben Sie jeder Arbeitslast ihre eigenen API-Zugangsdaten.
Lassen Sie Laufzeitdienste nur die Geschäfts-APIs aufrufen, die sie benötigen.
Lassen Sie CI oder einen administrativen Dienst die Verwaltung von Zugangsdaten und Guthaben durchführen.

¶ Eine Zugangsdaten pro Arbeitslast und Umgebung ausstellen

Erstellen Sie Zugangsdaten mit POST https://platform.acedata.cloud/api/v1/credentials/ unter Verwendung eines Account Tokens.

Eine minimale produktionsorientierte Anfrage kann einen Anzeigenamen, ein unabhängiges Verbrauchslimit, ein Ablaufdatum und eine API-Zulassungsliste enthalten:

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\"}
  }"

Der Erstellungsvertrag unterstützt:

Feld	Governance-Zweck
`application_id`	Bindet die Nutzung an die Zielanwendung
`name`	Macht die Arbeitslast in Audits identifizierbar
`limited_amount`	Legt ein unabhängiges Nutzungslimit für Zugangsdaten fest; `null` bedeutet kein unabhängiges Limit
`expired_at`	Legt einen automatischen zeitlich begrenzten Zugriff fest
`allowed_api_ids`	Beschränkt die Zugangsdaten auf ausgewählte APIs
`host`	Speichert gegebenenfalls Host-Informationen für Zugangsdaten
`for_user_id`	Ermöglicht einem Anwendungsbesitzer, delegierte Zugangsdaten für einen anderen Benutzer auszustellen
`tags` / `metadata`	Zeichnet Kontext zu Umgebung, Team, System oder Änderungsticket auf

Ein leeres allowed_api_ids-Array wird zu keiner Einschränkung normalisiert. Senden Sie kein leeres Array, wenn Ihre Absicht „nichts erlauben“ ist. Verwenden Sie eine echte API-Zulassungsliste.

API-/Agent-Dienste geben normalerweise Token-Zugangsdaten zurück. Proxy-Dienste geben normalerweise eine Benutzername/Passwort-Identität zurück, und eine Proxy-Anwendung erlaubt nur eine Zugangsdaten.

Behandeln Sie die Erstellungsausgabe als vertraulich. Speichern Sie das Geheimnis sofort in einem Passwortmanager oder Secret Manager und schreiben Sie die Antwort nicht in Protokolle. Clients sollten nicht davon abhängen, dass Klartext-Geheimnisse später weiterhin abrufbar bleiben; Lebenszyklus-APIs können maskierte Werte zurückgeben.

¶ Limits als Kontrollen des Schadensradius verwenden, nicht nur für Budgetierung

Ein Zugangsdaten-Level-limited_amount ist nützlich, um einen kompromittierten Schlüssel oder eine außer Kontrolle geratene Arbeitslast einzudämmen, aber es ist nur ein Teil der Kosten-Governance.

Eine robuste Hierarchie ist:

Zugangsdatenlimit: maximale Exposition für eine Arbeitslast.
Anwendungsguthaben: für die abonnierte Dienstanwendung verfügbares Kontingent.
Globale Guthabenrichtlinie: optionaler Fallback für berechtigte Pay-as-you-go-Anwendungen.
Überziehungsautorisierung: eine separate, schreibgeschützte Plattformautorisierung, die Kunden nicht selbst aktivieren können.

Behandeln Sie diese nicht als gleichwertig.

Zum Beispiel kann ein individuelles Zugangsdatenlimit die Arbeitslast weiterhin blockieren, selbst wenn eine Anwendung verfügbares Kontingent hat. Umgekehrt kann die Aktivierung der globalen Guthabenteilung einer berechtigten Anwendung ermöglichen, fortzufahren, nachdem ihr eigenes Guthaben nicht ausreicht—aber sie entfernt keine Zugangsdatenlimits und deaktiviert keine Deaktivierungs- oder Ablaufprüfungen.

¶ Guthaben mit Einheit und Status überwachen

Fragen Sie eine Anwendung ab mit:

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

Die betrieblich relevanten Felder umfassen:

remaining_amount — aktuelles Anwendungskontingent; ein negativer Wert zeigt ein zur Abrechnung ausstehendes Kontingent an.
used_amount — für die Anwendung gemeldete kumulierte Nutzung.
service.unit — die Einheit, wie Credit, Count oder Token.
disabled — ob die Anwendung deaktiviert ist.
expired_at — ob der Abonnementzugang abgelaufen ist.
allow_overdraft — schreibgeschützte Angabe einer vom Administrator genehmigten Überziehung.

Nehmen Sie niemals an, dass der Betrag US-Dollar ist. Warnschwellen müssen in der tatsächlichen Einheit des Dienstes definiert werden.

Ein positives Guthaben allein beweist keine Verfügbarkeit. Ihre Zustandsprüfung sollte Guthaben, disabled, Ablauf, Zugangsdatenlimits und Dienststatus auswerten. Bei Proxy-Diensten kann die Guthabensynchronisierung ausgesetzt werden oder eine Zeitüberschreitung aufweisen; in diesem Fall kann das zuletzt gespeicherte Guthaben zurückgegeben werden.

Eine prägnante Python-Prüfung:

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}")

Für mehrere Dienste rufen Sie die Anwendungsliste einmal ab und werten jedes Element lokal aus, anstatt jeden Anwendungsdetail-Endpunkt mit hoher Frequenz abzufragen.

¶ Explizit entscheiden, ob globale Guthabenteilung erlaubt ist

Berechtigte Pay-as-you-go-Anwendungen können so konfiguriert werden, dass sie das globale Guthaben des Kontos verwenden, wenn ihr eigenes Guthaben nicht ausreicht:

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}'

Verwenden Sie den zurückgegebenen Wert allow_consume_global als Quelle der Wahrheit. Nehmen Sie nicht an, dass der angeforderte Wert gespeichert wurde.

Wichtige Einschränkungen:

Period-Anwendungen können das globale Guthaben nicht verbrauchen; der Server behält das Feld auf false.
Eine eigene application_id und ein Account Token sind erforderlich.
Wenn allow_overdraft=true, kann eine Pay-as-you-go-Anwendung weiterhin von ihrem eigenen Guthaben unter null abziehen und wird nicht zum globalen Guthaben wechseln, nur weil ihr eigenes Guthaben nicht ausreicht.
Wenn ein Fallback erfolgt, wird das Überziehungsverhalten durch die globale Anwendung bestimmt, die tatsächlich bezahlt.

Der globale Fallback verbessert die Kontinuität, erweitert aber auch den finanziellen Schadensradius. Aktivieren Sie ihn als bewusste Richtlinie auf Dienstebene, nicht als Standardbequemlichkeit.

¶ Jeden Produktionsaufruf nach Zugangsdaten nachverfolgen

AceDataCloud bewahrt API-Aufrufdatensätze und Abrechnungszusammenfassungen für die letzten 60 Tage auf. Anfrage- und Antworttexte werden für 30 Tage aufbewahrt; Datensätze der Tage 30–60 behalten Zusammenfassungen bei, geben jedoch keine vollständigen metadata.request- und metadata.response-Texte mehr zurück.

Fragen Sie die neuesten Datensätze ab unter:

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}"

Nützliche Filter umfassen application_id, api_id, credential_id, status_code und ISO-8601-Zeitgrenzen. Der Parameter perspective trennt drei Ansichten:

billing — Aufrufe, die vom aktuellen Konto bezahlt werden.
actor — Aufrufe, die tatsächlich vom aktuellen Konto initiiert werden.
both — die Standardvereinigung von bezahlten und initiierten Aufrufen. Wichtige Felder für die Incident Response sind:

Feld	Operativer Einsatz
`credential_id`	Den offengelegten oder fehlerhaften Workload identifizieren
`trace_id`	Eine Anfrage Ende-zu-Ende untersuchen
`status_code`	Erfolgreiche und fehlgeschlagene Aufrufe trennen
`elapsed`	Latenz verfolgen
`used_amount`	Nutzung, berechnet nach den ursprünglichen Regeln
`original_amount`	Nutzung vor Anwendungsrabatten
`deducted_amount`	Tatsächlich endgültig abgezogener Betrag
`remaining_amount`	Anwendungskontingent nach der Belastung
`actor_user_id` / `user_id`	Den Aufrufer vom für die Zahlung verantwortlichen Konto unterscheiden

Verwenden Sie für große Abfragen kürzere Zeitfenster — vorzugsweise einen Tag oder weniger — und fügen Sie Filter hinzu. Wenn bereits eine identische Abfrage ausgeführt wird, kann die API 429 usage_query_in_progress zurückgeben; folgen Sie Retry-After mit Backoff. Ein 503 usage_query_timeout ist ein Signal, die Anfrage einzugrenzen, statt sie sofort zu wiederholen.

¶ Erstellen Sie einen Rotations- und Incident-Workflow, bevor Sie ihn benötigen

Ein praktisches Reaktionshandbuch lautet:

Identifizieren Sie das Credential anhand des Nutzungsdatensatzes oder der Servicekonfiguration.
Begrenzen Sie die Offenlegung, indem Sie sein Limit senken, sein Ablaufdatum ändern, allowed_api_ids einschränken oder es widerrufen.
Rotieren Sie das Secret und aktualisieren Sie den Secret Manager.
Stellen Sie den neuen Wert für den Workload bereit, ohne ihn zu protokollieren.
Überprüfen Sie erfolgreiche Aufrufe unter der erwarteten Credential-ID.
Prüfen Sie aktuelle Datensätze nach Credential, Status, API und Trace-ID.
Widerrufen Sie veraltete Credentials, nachdem die Umstellung bestätigt wurde.

Erstellen Sie separate Credentials für Entwicklung, Staging, Produktion, geplante Jobs und Drittanbieterintegrationen. Dies macht die Rotation lokal und die Zuordnung eindeutig. Ein einzelner gemeinsam genutzter „Produktions“-Schlüssel maximiert sowohl das Ausfallrisiko als auch die Unklarheit bei Untersuchungen.

¶ Empfohlene Kontrollbasis

Für jeden Produktions-Workload:

¶ Governance ist ein Kreislauf

Die Credential-Ausstellung, Guthabenüberwachung und Nutzungsverfolgung sollten nicht als getrennte Aufgaben verwaltet werden. Gemeinsam bilden sie einen kontinuierlichen Kontrollkreislauf:

eng ausstellen → die zahlende Anwendung überwachen → tatsächliche Aufrufe nachverfolgen → schnell rotieren oder widerrufen.

Die Management-APIs von AceDataCloud stellen die Felder bereit, die erforderlich sind, um diesen Kreislauf zu implementieren, ohne Managementzugriff, Laufzeitzugriff, Kontingent und Abrechnungszuordnung zu vermischen. Das Ergebnis ist nicht lediglich ein sicherer API-Schlüssel; es ist ein Produktionssystem mit begrenzter Offenlegung und nachvollziehbarer Nutzung.

Produktions-API-Governance auf AceDataCloud: Zugangsdaten, Kontostandskontrollen und Nutzungsüberwachung