Governance delle API di produzione su AceDataCloud

Una chiave API di produzione non è solo una stringa segreta. È un punto di controllo per chi può chiamare cosa, quanto può consumare, quanto dura l'accesso, quale applicazione paga e come può essere tracciato un incidente.

AceDataCloud espone questi controlli attraverso quattro livelli connessi:

  1. Emissione delle credenziali — creare una chiave per una Application specifica.
  2. Politica del saldo dell'Application — determinare da dove viene detratto l'utilizzo e cosa accade quando la quota è bassa.
  3. Osservabilità dell'utilizzo — tracciare stato, costo, latenza, API, Application e credenziale.
  4. Ciclo di vita delle credenziali — aggiornare le restrizioni, ruotare i segreti e revocare l'accesso.

Ciclo di controllo della governance delle API di produzione

Questa guida trasforma le singole API di gestione della piattaforma in un unico modello operativo pratico.

Innanzitutto, separa i due tipi di credenziali

AceDataCloud utilizza credenziali diverse per superfici diverse:

Credenziale Utilizzata per Host tipico
Account Token / Platform Token Gestione dell'account: Applications, credenziali, saldi, utilizzo, ordini platform.acedata.cloud/api/v1/**
API Credential Chiamata delle API aziendali per un servizio api.acedata.cloud/**

Non sono intercambiabili. Una credenziale API aziendale non deve essere utilizzata per chiamare endpoint di gestione, e un Platform Token non deve essere incorporato in un'applicazione come sua chiave API aziendale.

Questa separazione crea un utile confine di sicurezza:

  • Mantieni i Platform Token in un ambiente operativo strettamente controllato.
  • Fornisci a ogni workload la propria API Credential.
  • Consenti ai servizi di runtime di chiamare solo le API aziendali di cui hanno bisogno.
  • Consenti a CI o a un servizio amministrativo di eseguire la gestione delle credenziali e del saldo.

Emetti una credenziale per ogni workload e ambiente

Crea una credenziale con POST https://platform.acedata.cloud/api/v1/credentials/ utilizzando un Account Token.

Una richiesta minima orientata alla produzione può includere un nome visualizzato, un limite di consumo indipendente, una scadenza e una allowlist 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\"}
  }"

Il contratto di creazione supporta:

Campo Finalità di governance
application_id Collega l'utilizzo alla Application di destinazione
name Rende il workload identificabile negli audit
limited_amount Imposta un limite di utilizzo della credenziale indipendente; null significa nessun limite indipendente
expired_at Stabilisce un accesso automatico limitato nel tempo
allowed_api_ids Limita la credenziale alle API selezionate
host Memorizza le informazioni host della credenziale dove applicabile
for_user_id Consente al proprietario di una Application di emettere credenziali delegate per un altro utente
tags / metadata Registra il contesto di ambiente, team, sistema o ticket di modifica

Un array allowed_api_ids vuoto viene normalizzato come nessuna restrizione. Non inviare un array vuoto quando la tua intenzione è “non consentire nulla”. Utilizza una reale allowlist API.

I servizi API/Agent normalmente restituiscono una credenziale Token. I servizi Proxy normalmente restituiscono un'identità username/password, e una Proxy Application consente solo una credenziale.

Tratta la risposta di creazione come sensibile. Salva immediatamente il segreto in un password manager o secret manager e non scrivere la risposta nei log. I client non devono dipendere dal fatto che i segreti in testo semplice rimangano recuperabili in seguito; le API del ciclo di vita potrebbero restituire valori mascherati.

Utilizza i limiti come controlli del raggio d'impatto, non solo per il budget

Un limited_amount a livello di credenziale è utile per contenere una chiave trapelata o un workload fuori controllo, ma è solo una parte della governance dei costi.

Una gerarchia solida è:

  • Limite della credenziale: esposizione massima per un workload.
  • Saldo dell'Application: quota disponibile per la Application del servizio sottoscritto.
  • Politica del saldo globale: fallback opzionale per le Applications pay-as-you-go idonee.
  • Autorizzazione allo scoperto: un'autorizzazione della piattaforma separata e di sola lettura che i clienti non possono abilitare autonomamente.

Non trattarli come equivalenti.

Ad esempio, anche quando una Application dispone di quota disponibile, un limite della singola credenziale può comunque bloccare il workload. Al contrario, abilitare la condivisione del saldo globale può consentire a una Application idonea di continuare dopo che il proprio saldo è insufficiente, ma non rimuove i limiti della credenziale, i controlli di disabilitazione o di scadenza.

Monitora il saldo con unità e stato

Interroga una Application con:

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

I campi importanti dal punto di vista operativo includono:

  • remaining_amount — quota attuale dell'Application; un valore negativo indica una quota in attesa di regolamento.
  • used_amount — utilizzo accumulato riportato per l'Application.
  • service.unit — l'unità, ad esempio Credit, Count o Token.
  • disabled — se l'Application è disabilitata.
  • expired_at — se l'accesso all'abbonamento è scaduto.
  • allow_overdraft — indicazione di sola lettura dello scoperto approvato dall'amministratore.

Non presumere mai che l'importo sia in dollari statunitensi. Le soglie di avviso devono essere definite nell'unità effettiva del servizio.

Un saldo positivo da solo non dimostra la disponibilità. Il controllo di integrità deve valutare saldo, disabled, scadenza, limiti delle credenziali e stato del servizio. Per i servizi Proxy, la sincronizzazione del saldo può essere sospesa o andare in timeout, nel qual caso può essere restituito il saldo salvato più di recente.

Un controllo Python conciso:

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

Per più servizi, recupera una volta l'elenco delle Applications e valuta ogni elemento localmente invece di interrogare ogni endpoint dei dettagli dell'Application ad alta frequenza.

Decidi esplicitamente se è consentita la condivisione del saldo globale

Le Applications pay-as-you-go idonee possono essere configurate per utilizzare il saldo globale dell'account quando il proprio saldo è insufficiente:

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

Utilizza il valore allow_consume_global restituito come fonte di verità. Non presumere che il valore richiesto sia stato salvato.

Vincoli importanti:

  • Le Applications Period non possono consumare il saldo globale; il server mantiene il campo su false.
  • Sono richiesti un application_id posseduto e un Account Token.
  • Se allow_overdraft=true, una Application pay-as-you-go può continuare a detrarre dal proprio saldo sotto zero e non passerà al saldo globale semplicemente perché il proprio saldo è insufficiente.
  • Quando si verifica il fallback, il comportamento dello scoperto è determinato dalla Application globale che effettivamente paga.

Il fallback globale migliora la continuità, ma amplia anche il raggio d'impatto finanziario. Abilitalo come una politica deliberata a livello di servizio, non come una comodità predefinita.

Traccia ogni chiamata di produzione tramite credenziale

AceDataCloud conserva i record delle chiamate API e i riepiloghi di fatturazione per i 60 giorni più recenti. I corpi delle richieste e delle risposte vengono conservati per 30 giorni; i record dai giorni 30–60 conservano i riepiloghi ma non restituiscono più i corpi completi metadata.request e metadata.response.

Interroga i record più recenti su:

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

I filtri utili includono application_id, api_id, credential_id, status_code e limiti temporali ISO 8601. Il parametro perspective separa tre viste:

  • billing — chiamate pagate dall'account corrente.
  • actor — chiamate effettivamente avviate dall'account corrente.
  • both — l'unione predefinita delle chiamate pagate e avviate. I campi chiave per la risposta agli incidenti sono:
Campo Utilizzo operativo
credential_id Identificare il carico di lavoro esposto o malfunzionante
trace_id Investigare una richiesta dall'inizio alla fine
status_code Separare le chiamate riuscite da quelle non riuscite
elapsed Monitorare la latenza
used_amount Utilizzo calcolato secondo le regole originali
original_amount Utilizzo prima degli sconti dell'Application
deducted_amount Importo finale effettivamente detratto
remaining_amount Quota dell'Application dopo l'addebito
actor_user_id / user_id Distinguere il chiamante dall'account responsabile del pagamento

Per query di grandi dimensioni, utilizzare finestre più brevi, preferibilmente di un giorno o meno, e aggiungere filtri. Se una query identica è già in esecuzione, l'API può restituire 429 usage_query_in_progress; seguire Retry-After con backoff. Un 503 usage_query_timeout è un segnale per restringere la richiesta anziché ripeterla immediatamente.

Costruisci un flusso di rotazione e gestione degli incidenti prima di averne bisogno

Un playbook pratico di risposta è:

  1. Identificare la credenziale dal record di utilizzo o dalla configurazione del servizio.
  2. Contenere l'esposizione riducendone il limite, modificandone la scadenza, restringendo allowed_api_ids o revocandola.
  3. Ruotare il segreto e aggiornare il gestore dei segreti.
  4. Distribuire il nuovo valore al carico di lavoro senza registrarlo nei log.
  5. Verificare le chiamate riuscite con l'ID credenziale previsto.
  6. Esaminare i record recenti per credenziale, stato, API e ID traccia.
  7. Revocare le credenziali obsolete dopo la conferma del passaggio.

Creare credenziali separate per sviluppo, staging, produzione, processi pianificati e integrazioni di terze parti. Questo rende la rotazione locale e l'attribuzione chiara. Una singola chiave “di produzione” condivisa massimizza sia il rischio di interruzione sia l'ambiguità investigativa.

Baseline di controllo consigliata

Per ogni carico di lavoro di produzione:

  • Credenziale API dedicata; nessuna condivisione tra ambienti.
  • Nome descrittivo e metadati di proprietà.
  • Allowlist API contenente solo gli ID endpoint richiesti.
  • Limite di consumo indipendente proporzionale al carico di lavoro previsto.
  • Data di scadenza con una finestra di rinnovo pianificata.
  • Segreto archiviato in un gestore dei segreti ed escluso dai log.
  • Avviso sul saldo dell'Application nella corretta unità di servizio.
  • Controlli per disabilitazione e scadenza, non solo per il saldo.
  • Decisione esplicita su allow_consume_global.
  • Dashboard di utilizzo filtrata per Application e credenziale.
  • ID traccia acquisiti nei log dell'applicazione.
  • Procedura documentata di rotazione e revoca.

La governance è un ciclo

L'emissione delle credenziali, il monitoraggio del saldo e il tracciamento dell'utilizzo non dovrebbero essere gestiti come attività separate. Insieme formano un ciclo di controllo continuo:

emettere in modo ristretto → monitorare l'Application pagante → tracciare le chiamate effettive → ruotare o revocare rapidamente.

Le API di gestione di AceDataCloud espongono i campi necessari per implementare tale ciclo senza confondere l'accesso di gestione, l'accesso in fase di esecuzione, la quota e l'attribuzione della fatturazione. Il risultato non è semplicemente una chiave API più sicura; è un sistema di produzione con esposizione limitata e utilizzo spiegabile.

Risorse ufficiali