Control API - logger, revisjon og bruk
Bruk FoxIDs Control API til å søke etter diagnoselogger, revisjonshendelser og bruksdata, og til å konfigurere loggtypene som sendes ut av et miljø. Disse ressursene har forskjellige formål og tilgangsrettigheter:
- Logger hjelper operatører med å diagnostisere feil, advarsler, protokollflyter, hendelser og beregninger.
- Revisjon registrerer sikkerhets- og administrative handlinger, inkludert påloggingsaktivitet og Control APIoppretting, oppdatering og sletting av forespørsler.
- Bruk samler aktivitet for drifts- og faktureringsanalyse.
Før du kaller disse operasjonene, konfigurer Control API autentisering og tilgangsrettigheter. Swagger forblir den eksakte referansen for alle søkeparametere, enum-verdier, innstillinger og svarskjemaer:
Spørringsomfang og endepunkter
FoxIDs gir tre søkeomfang.
| Omfang | Endepunktbase | Diagnoselogg | Revidere | Bruk |
|---|---|---|---|---|
| Ett miljø | /api/{tenant_name}/{track_name} |
!tracklog |
!tracklogaudit |
!tracklogusage |
| Din tenant | /api/{tenant_name}/master |
!mytenantlog |
!mytenantlogaudit |
!mytenantlogusage |
| Distribusjonsadministrasjon | /api/master/master |
!tenantlog |
!tenantlogaudit |
!tenantlogusage |
Prefiks basen med FoxIDs Control-verten, for eksempel https://control.foxids.com. Endre verten for en selvdrevet distribusjon. Send tilgangstokenet i Authorization: Bearer {access_token}-overskriften.
Miljøspørringer bruker miljøet fra ruten. Tenant søk kan valgfritt velge et miljø med trackName. Forespørsler om distribusjonsadministrasjon kan velge et tenant og miljø med tenantName og trackName. Distribusjonsdiagnosespørringen kan også inkludere forespørsler som ble avvist før tenant og miljøruting.
Bruk tilgangsrettighetene track:log, track:audit eller track:usage, eventuelt begrenset til et spesifikt miljø. Implementeringsomfattende revisjon og bruk krever de tilsvarende master tilgangsrettighetene. Se fullstendige rettighetstabeller.
Spør diagnostiske logger
En diagnoseloggforespørsel spesifiserer fromTime og toTime som Unix-tid i sekunder. En enkelt forespørsel kan dekke maksimalt 24 timer. Velg én eller flere kategorier som feil, advarsler, spor, hendelser og beregninger, og bruk filter for fritekstfiltrering.
Et svar inneholder opptil 300 av de nyeste samsvarende oppføringene. Sjekk responseTruncated; når det er true, begrenser du tidsintervallet eller filteret og spør på nytt i stedet for å anta at resultatet er fullstendig.
Application Insights støtter ikke spørring av spor og hendelser sammen gjennom denne operasjonen. Send separate forespørsler når begge kategorier kreves. Hold tidsintervaller så smale som praktisk mulig for å forbedre søkeytelsen og redusere mengden sensitive data som returneres.
Spørringsendepunktene krever et søkbart primært logglager. De kan ikke hente logger når distribusjonens primære loggutgang er standardutdata (Stdout). I den konfigurasjonen spør du i stedet for plattformens container- eller vertsloggingssystem. FoxIDs støtter kontrollspørringer mot konfigurerte Application Insights- og OpenSearch-lagre.
Spørre revisjonshendelser
En revisjonsforespørsel spesifiserer fromTime og toTime som Unix-tid i sekunder og kan dekke maksimalt syv dager. toTime må være lik eller senere enn fromTime. Den valgfrie filter utfører et generelt fritekstsøk på tvers av revisjonsfelt og hendelsesdata.
Et svar inneholder opptil 300 av de nyeste samsvarende revisjonshendelsene. Merk av for responseTruncated og del eller avgrens søket når et fullstendig resultat kreves.
Revisjonshendelser inkluderer brukervendt autentiseringsaktivitet og administrative mutasjoner. Control API POST-, PUT- og DELETE-handlinger revideres automatisk, mens skrivebeskyttede GET-forespørsler ikke er det. En revisjonshendelse kan inneholde nyttige korrelasjonsverdier som tenant, miljø, autentiseringsmetode, applikasjon, bruker, økt, klient-IP og brukeragent når disse verdiene er tilgjengelige for handlingen.
Tilsyn er utformet for å vise hva som skjedde og dens kontekst. Det er ikke en transaksjonskø og bør ikke brukes som den eneste utløseren for forretningskritisk synkronisering. Søkeresultater avhenger også av det konfigurerte logglageret og oppbevaringen.
Spørrebruk
Bruksforespørsler velger et tidsrom, en UTC-forskyvning og et oppsummeringsnivå. Inkluder flagg bestemmer om svaret inneholder tenants, miljøer, autentiseringsmetoder, brukere, pålogginger, tokenforespørsler, tilleggsbruk og Control API-aktivitet.
Velg det smaleste omfanget og kun de dimensjonene forbrukeren trenger. Dette holder svarene mindre og unngår å eksponere tenant eller brukerdetaljer unødvendig. Bruk Swagger for gjeldende tidsrom og oppsummeringsverdier.
Konfigurer miljølogging
Miljøloggkonfigurasjon bruker:
| Operasjon | Endepunkt | Hensikt |
|---|---|---|
| Få innstillinger | GET /!tracklogsetting |
Les aktiverte diagnostiske loggtyper for rutemiljøet. |
| Lagre innstillinger | POST /!tracklogsetting |
Bytt ut miljøets logginnstillinger. |
| Få strømmer | GET /!tracklogstreamssettings |
Les ekstern loggstrømkonfigurasjon. |
| Lagre strømmer | POST /!tracklogstreamssettings |
Bytt ut ekstern loggstrømkonfigurasjon. |
Innstillingene kontrollerer informasjonssporing, kravsporing, meldingssporing og beregninger. Feil, advarsler, kritiske feil og hendelser forblir tilgjengelig uavhengig som beskrevet i Logging. POST erstatter den fullstendige innstillingsressursen; hent gjeldende ressurs, bevar uendrede egenskaper, og lagre deretter hele representasjonen.
En loggstrøm videresender valgte kategorier til en ekstern destinasjon uavhengig av det primære logglageret. Dette kan brukes til å sende et kontrollert sett med miljølogger til en separat Application Insights-ressurs.
Krav og meldingsspor kan inneholde personlige data, tokens og fullstendige protokollmeldinger. Aktiver dem bare for et definert diagnostisk behov, begrense tilgangen, angi en passende oppbevaringsperiode og slå dem av igjen når undersøkelsen er fullført.
Driftsveiledning
- Bruk UTC Unix-tidsstempler i integrasjoner og bruk
timeOffsetbare der brukspresentasjon krever en lokal grense. - Del lange undersøkelser i forespørsler innenfor endepunktets maksimale tidsrom.
- Hold fritekstfiltre spesifikke og unngå å stole på visningstekst som en permanent maskinidentifikator.
- Beskytt returnerte logg- og revisjonsdata som driftssensitiv informasjon.
- Bruk revisjon til å undersøke og bevise handlinger, ikke for å erstatte en garantert varsling eller synkronisering API.
- Forvent at endringer i logginnstillinger og strømmer blir revidert fordi de er Control API-mutasjoner.
Vanlige feilsvar
400 Bad Requestnår en tidsperiode, velger, tenant, miljø eller innstillingsressurs er ugyldig.401 Unauthorizednår tilgangstokenet mangler eller er ugyldig.403 Forbiddennår den som ringer mangler den nødvendige logg-, revisjons- eller brukstilgangsrettigheten.404 Not Foundnår det valgte miljøet eller innstillingsressursen ikke eksisterer.
Bruk svarteksten for valideringsdetaljer og Swagger UI for svarene deklarert av hver operasjon.