Report di utilizzo delle deprecazioni

GET /v1/reports/deprecation-usage · autorizzazione reports:read

Mostra quali dei tuoi client chiamano ancora operazioni previste per la rimozione, così da poterli migrare prima della data di rimozione (vedi la politica di versionamento). Le chiamate sono conteggiate per giorno UTC e raggruppate per deprecazione, client e versione dell'SDK. Quando nessuna operazione è deprecata, il report è vuoto.

L'ambiente proviene sempre dalla chiave API; non esiste un parametro ambiente. Le righe non contengono indirizzi IP, User-Agent o identificatori di utenti finali.

Richiesta

Parametro	In	Obbligatorio	Descrizione
`from`	query	no	Primo giorno incluso, data completa (`YYYY-MM-DD`, UTC). Predefinito: `to` meno 30 giorni. Limitato dalla cronologia dei report del tuo piano (vedi sotto).
`to`	query	no	Ultimo giorno incluso, data completa (`YYYY-MM-DD`, UTC). Predefinito: oggi. `from` non deve essere successivo a `to`.
`limit`	query	no	Dimensione della pagina, da 1 a 100. Predefinito 50.
`cursor`	query	no	`next_cursor` della pagina precedente. Valido solo per l'ambiente, `from` e `to` per cui è stato emesso.

Le righe sono ordinate per deprecation_id, client_id, sdk_package, sdk_version. Entrambi gli estremi dell'intervallo sono inclusi. Un cursore ottenuto con un intervallo predefinito (senza from/to inviati) smette di funzionare quando cambia il giorno UTC; invia from e to in modo esplicito quando paginare.

Cronologia dei report per piano

Piano	Cronologia
Free	30 giorni
Startup, Business	13 mesi
Enterprise	25 mesi, con un limite di 400 giorni

La tabella dei report conserva 400 giorni, quindi nessun piano risale oltre i 400 giorni. Un from più vecchio della cronologia consentita fallisce con 422 report_range_exceeds_plan; la data minima consentita è indicata nel messaggio e in errors[0].detail (earliest_allowed_date=YYYY-MM-DD).

Risposta

200 OK. data contiene le righe della pagina; next_cursor è null nell'ultima pagina.

Campo	Descrizione
`deprecation_id`	Identificatore nel registro delle deprecazioni (`dep-YYYY-NN`).
`client_id`	`key_…` per una chiave API di gestione, `app_…` per un client OAuth di gestione, `dashboard` per la dashboard.
`sdk_package`	Pacchetto SDK dall'intestazione `Idp-Client`; `other` per un pacchetto fuori dal catalogo, `none` quando l'intestazione è assente.
`sdk_version`	Versione SemVer, oppure una stringa vuota.
`call_count`	Chiamate nell'intervallo.
`last_seen_at`	Ultima chiamata nell'intervallo (RFC 3339, UTC).
`sunset_at`	Data di rimozione dal registro delle deprecazioni (`YYYY-MM-DD`), `null` se sconosciuta. Dopo questo giorno l'operazione risponde `410 endpoint_sunset`.

{
  "data": [
    {
      "deprecation_id": "dep-2027-01",
      "client_id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d",
      "sdk_package": "keenauth-go",
      "sdk_version": "1.4.0",
      "call_count": 1280,
      "last_seen_at": "2027-03-02T09:30:00Z",
      "sunset_at": "2028-01-17"
    }
  ],
  "next_cursor": null
}

CSV

Invia Accept: text/csv per ricevere le stesse colonne in CSV (RFC 4180) con una riga di intestazione. Le celle di testo che iniziano con =, +, -, @, una tabulazione o un ritorno a capo ricevono un apice singolo davanti, così che i fogli di calcolo non le eseguano come formule. Il cursore della pagina successiva è nell'intestazione Link (rel="next"); l'intervallo è esplicitato in quel link.

deprecation_id,client_id,sdk_package,sdk_version,call_count,last_seen_at,sunset_at
dep-2027-01,key_01j9xk3m7q8r2s4t6v8w0y2z4d,keenauth-go,1.4.0,1280,2027-03-02T09:30:00Z,2028-01-17

Note

I conteggi sono raccolti per minuto e scritti nel report in modo asincrono, quindi le chiamate più recenti possono impiegare alcuni minuti a comparire. Un arresto anomalo può far perdere fino a 60 secondi di conteggi. Il report non è un dato di fatturazione.

Errori

Ogni errore è un corpo application/problem+json con un code stabile.

HTTP	`code`	Quando
400	`invalid_filter`	`from` o `to` non è una data `YYYY-MM-DD`, una data è ripetuta, o `from` è successivo a `to`.
400	`invalid_cursor`	Il cursore è malformato o non è stato emesso per questo ambiente e intervallo.
422	`report_range_exceeds_plan`	`from` è più vecchio della cronologia dei report del tuo piano.
422	`validation_failed`	`limit` è fuori intervallo oppure un parametro è ripetuto.
401	`unauthenticated`	La chiave API è mancante, non valida o revocata.
403	`insufficient_permissions`	La chiave non ha `reports:read`.
429	`rate_limited`	È stato superato il limite di frequenza; rispetta `Retry-After`.
503	`service_unavailable`	Il servizio di report è temporaneamente non disponibile; riprova più tardi.

Esempio

curl "https://api.eu.keenauth.com/v1/reports/deprecation-usage?from=2027-03-01&to=2027-03-31" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth reports deprecation-usage --from 2027-03-01 --to 2027-03-31
keenauth reports deprecation-usage --format csv > deprecation-usage.csv