Control API - loggar, granskning och användning

Använd FoxIDs Control API för att fråga diagnostiska loggar, granskningshändelser och användningsdata och för att konfigurera loggtyperna som sänds ut av en miljö. Dessa resurser har olika syften och åtkomsträttigheter:

Loggar hjälper operatörer att diagnostisera fel, varningar, protokollflöden, händelser och mätvärden.
Revision registrerar säkerhets- och administrativa åtgärder, inklusive inloggningsaktivitet och Control API skapa, uppdatera och ta bort förfrågningar.
Användning aggregerar aktivitet för drifts- och faktureringsanalys.

Innan du anropar dessa åtgärder, konfigurera Control API autentisering och åtkomsträttigheter. Swagger förblir den exakta referensen för alla frågeparametrar, uppräkningsvärden, inställningar och svarsscheman:

Frågans omfattning och slutpunkter

FoxIDs tillhandahåller tre frågeomfång.

Omfattning	Slutpunktsbas	Diagnostisk logg	Granska	Användande
En miljö	`/api/{tenant_name}/{track_name}`	`!tracklog`	`!tracklogaudit`	`!tracklogusage`
Din tenant	`/api/{tenant_name}/master`	`!mytenantlog`	`!mytenantlogaudit`	`!mytenantlogusage`
Driftsättningsadministration	`/api/master/master`	`!tenantlog`	`!tenantlogaudit`	`!tenantlogusage`

Prefix basen med FoxIDs Control-värden, till exempel https://control.foxids.com. Ändra värd för en självvärd driftsättning. Skicka åtkomsttoken i rubriken Authorization: Bearer {access_token}.

Miljöfrågor använder miljön från rutten. Tenant frågor kan valfritt välja en miljö med trackName. Frågor om implementering och administration kan välja en tenant och miljö med tenantName och trackName. Implementeringsdiagnostikfrågan kan också inkludera förfrågningar som avvisats före tenant och miljödirigering.

Använd åtkomsträttigheterna track:log, track:audit eller track:usage, eventuellt avgränsade till en specifik miljö. Implementeringsomfattande granskning och användning kräver motsvarande master åtkomsträttigheter. Se fullständiga åtkomsträttstabeller.

Fråga diagnostiska loggar

En diagnostisk loggförfrågan anger fromTime och toTime som Unix-tid i sekunder. En enstaka begäran kan omfatta högst 24 timmar. Välj en eller flera kategorier som fel, varningar, spår, händelser och mätvärden och använd filter för fritextfiltrering.

Ett svar innehåller upp till 300 av de senaste matchande inläggen. Kontrollera responseTruncated; när det är true, begränsa tidsintervallet eller filtret och fråga igen istället för att anta att resultatet är komplett.

Application Insights har inte stöd för att söka efter spår och händelser tillsammans genom denna operation. Skicka separata förfrågningar när båda kategorierna krävs. Håll tidsintervallen så smala som möjligt för att förbättra frågeprestanda och minska mängden känslig data som returneras.

Frågeslutpunkterna kräver ett sökbart primärt loggförråd. De kan inte hämta loggar när distributionens primära loggutgång är standardutdata (Stdout). I den konfigurationen frågar du istället plattformens container- eller värdloggningssystem. FoxIDs stöder kontrollfrågor mot konfigurerade Application Insights- och OpenSearch-förråd.

Fråga granskningshändelser

En granskningsbegäran anger fromTime och toTime som Unix-tid i sekunder och kan omfatta högst sju dagar. toTime måste vara lika med eller senare än fromTime. Den valfria filter utför en allmän fritextsökning i granskningsfält och händelsedata.

Ett svar innehåller upp till 300 av de senaste matchande granskningshändelserna. Markera responseTruncated och dela eller begränsa frågan när ett komplett resultat krävs.

Revisionshändelser inkluderar användarinriktad autentiseringsaktivitet och administrativa mutationer. Åtgärderna Control API POST, PUT och DELETE granskas automatiskt, medan skrivskyddade GET-förfrågningar inte gör det. En granskningshändelse kan innehålla användbara korrelationsvärden som tenant, miljö, autentiseringsmetod, applikation, användare, session, klient-IP och användaragent när dessa värden är tillgängliga för åtgärden.

Granskningen är utformad för att visa vilken åtgärd som inträffade och dess sammanhang. Det är inte en transaktionshändelsekö och bör inte användas som den enda utlösaren för affärskritisk synkronisering. Sökresultat beror också på det konfigurerade loggförrådet och lagringen.

Fråga användning

Användningsförfrågningar väljer ett tidsintervall, en UTC-offset och en sammanfattningsnivå. Inkludera flaggor avgör om svaret innehåller tenants, miljöer, autentiseringsmetoder, användare, inloggningar, tokenförfrågningar, ytterligare användning och Control API-aktivitet.

Välj den smalaste omfattningen och endast de mått som konsumenten behöver. Detta håller svaren mindre och undviker att exponera tenant eller användardetaljer i onödan. Använd Swagger för aktuellt tidsintervall och sammanfattningsvärden.

Konfigurera miljöloggning

Miljöloggkonfigurationen använder:

Drift	Slutpunkt	Ändamål
Hämta inställningar	`GET /!tracklogsetting`	Läs aktiverade diagnostiska loggtyper för ruttmiljön.
Spara inställningar	`POST /!tracklogsetting`	Byt ut miljöns logginställningar.
Skaffa strömmar	`GET /!tracklogstreamssettings`	Läs extern loggströmskonfiguration.
Spara strömmar	`POST /!tracklogstreamssettings`	Byt ut extern loggströmskonfiguration.

Inställningarna styr informationsspårningar, anspråksspårningar, meddelandespårningar och mätvärden. Fel, varningar, kritiska fel och händelser förblir tillgängliga oberoende av varandra enligt beskrivningen i Loggning. POST ersätter den fullständiga inställningsresursen; hämta den aktuella resursen, bevara oförändrade egenskaper och spara sedan hela representationen.

En loggström vidarebefordrar valda kategorier till en extern destination oberoende av det primära loggförrådet. Detta kan användas för att skicka en kontrollerad uppsättning miljöloggar till en separat Application Insights-resurs.

Anspråks- och meddelandespårningar kan innehålla personuppgifter, tokens och fullständiga protokollmeddelanden. Aktivera dem endast för ett definierat diagnostiskt behov, begränsa åtkomsten, ställ in en lämplig lagringsperiod och stäng av dem igen när undersökningen är klar.

Operativ vägledning

Använd UTC Unix-tidsstämplar i integrationer och använd timeOffset endast där användningspresentation kräver en lokal gräns.
Dela upp långa undersökningar av förfrågningar inom slutpunktens maximala tidsintervall.
Håll fritextfilter specifika och undvik att lita på visningstext som en permanent maskinidentifierare.
Skydda returnerade logg- och revisionsdata som operativt känslig information.
Använd revision för att undersöka och bevisa åtgärder, inte för att ersätta ett garanterat meddelande eller synkronisering API.
Räkna med att ändringar av logginställningar och strömmar ska granskas eftersom de är Control API mutationer.

Vanliga felsvar

400 Bad Request när ett tidsintervall, väljare, tenant, miljö eller inställningsresurs är ogiltig.
401 Unauthorized när åtkomsttoken saknas eller är ogiltig.
403 Forbidden när den som ringer saknar den nödvändiga logg-, gransknings- eller användningsrättigheten.
404 Not Found när den valda miljön eller inställningsresursen inte finns.

Använd svarstexten för valideringsdetaljer och Swagger UI för svaren som deklareras av varje operation.