Informazioni di riferimento sull'API di controllo di Azure Active DirectoryAzure Active Directory audit API reference

Questo argomento fa parte di una raccolta di argomenti sull'API di creazione report di Azure Active Directory.This topic is part of a collection of topics about the Azure Active Directory reporting API.
La creazione di report di Azure Active Directory fornisce un'API che consente di accedere ai dati di controllo tramite codice o strumenti correlati.Azure AD reporting provides you with an API that enables you to access audit data using code or related tools. L'obiettivo di questo argomento è fornire informazioni di riferimento sull' API di controllo.The scope of this topic is to provide you with reference information about the audit API.

Vedere:See:

Per:For:

Chi può accedere ai dati?Who can access the data?

  • Gli utenti con ruolo di amministratore della sicurezza o con autorizzazioni di lettura per la sicurezzaUsers in the Security Admin or Security Reader role
  • Gli amministratori globaliGlobal Admins
  • Qualsiasi applicazione che dispone di autorizzazione per accedere all'API. L'autorizzazione dell'app può essere configurata solo in base alle autorizzazioni dell'amministratore globale.Any app that has authorization to access the API (app authorization can be setup only based on Global Admin’s permission)

PrerequisitiPrerequisites

Per accedere a questo report tramite l'API di creazione report, è necessario:In order to access this report through the Reporting API, you must have:

Accesso all'APIAccessing the API

È possibile accedere a questa API tramite Graph Explorer o a livello di codice, ad esempio usando PowerShell.You can either access this API through the Graph Explorer or programmatically using, for example, PowerShell. Al fine di consentire a Per PowerShell di interpretare correttamente la sintassi del filtro OData usata nelle chiamate REST di Graph di AAD, è necessario fare uso dell'apice inverso, ovvero l'accento grave, per eseguire l'"escape" del carattere $.In order for PowerShell to correctly interpret the OData filter syntax used in AAD Graph REST calls, you must use the backtick (aka: grave accent) character to “escape” the $ character. L'apice inverso viene usato come carattere di escape di PowerShelle consente a PowerShell di eseguire un'interpretazione letterale del carattere $, che evita la confusione con il nome di una variabile di PowerShell (ad esempio: $filter).The backtick character serves as PowerShell’s escape character, allowing PowerShell to do a literal interpretation of the $ character, and avoid confusing it as a PowerShell variable name (ie: $filter).

Questo argomento si concentra su Graph Explorer.The focus of this topic is on the Graph Explorer. Per un esempio di PowerShell, vedere questo script di PowerShell.For a PowerShell example, see this PowerShell script.

Endpoint APIAPI Endpoint

È possibile accedere a questa API tramite l'URI seguente:You can access this API using the following URI:

https://graph.windows.net/contoso.com/activities/audit?api-version=beta

Non esiste alcun limite al numero di record restituiti dall'API di controllo di Azure AD (usando l'impaginazione OData).There is no limit on the number of records returned by the Azure AD audit API (using OData pagination). Per i limiti di conservazione sui dati dei report, consultare Criteri di conservazione dei report.For retention limits on reporting data, check out Reporting Retention Policies.

Questa chiamata restituisce i dati in batch.This call returns the data in batches. Ogni batch contiene un massimo di 1000 record.Each batch has a maximum of 1000 records.
Per ottenere il batch successivo di record, usare il link Avanti.To get the next batch of records, use the Next link. Ottenere le informazioni sullo skiptoken dal primo set di record restituiti.Get the skiptoken information from the first set of returned records. Il token skip si trova alla fine del set di risultati.The skip token will be at the end of the result set.

https://graph.windows.net/contoso.com/activities/audit?api-version=beta&%24skiptoken=-1339686058

Filtri supportatiSupported filters

È possibile restringere il numero di record restituiti da una chiamata API usando un filtro.You can narrow down the number of records that are returned by an API call in form of a filter.
Per i dati relativi all'API di accesso sono supportati i filtri seguenti:For sign-in API related data, the following filters are supported:

  • $top=<numero di record da restituire>: per limitare il numero di record restituiti.$top=<number of records to be returned> - to limit the number of returned records. Si tratta di un'operazione impegnativa.This is an expensive operation. Non è consigliabile usare questo filtro se si desidera restituire migliaia di oggetti.You should not use this filter if you want to return thousands of objects.
  • $filter=<istruzione per il filtro>: per specificare il tipo di record da restituire, sulla base dei campi filtro supportati$filter=<your filter statement> - to specify, on the basis of supported filter fields, the type of records you care about

Operatori e campi dei filtri supportatiSupported filter fields and operators

Per specificare il tipo di record da restituire, è possibile compilare un'istruzione per il filtro che può contenere uno o una combinazione dei campi filtro seguenti:To specify the type of records you care about, you can build a filter statement that can contain either one or a combination of the following filter fields:

  • activityDate: definisce una data o un intervallo di dateactivityDate - defines a date or date range
  • category: definisce la categoria in base alla quale applicare il filtrocategory - defines the category you want to filter on.
  • activityStatus: definisce lo stato di un'attivitàactivityStatus - defines the status of an activity
  • activityType: definisce il tipo di un'attivitàactivityType - defines the type of an activity
  • activity - definisce l'attività come stringaactivity - defines the activity as string
  • actor/name: definisce l'attore mediante il nome dell'attoreactor/name - defines the actor in form of the actor's name
  • actor/objectid - definisce l'attore mediante l'ID dell'attoreactor/objectid - defines the actor in form of the actor's ID
  • actor/upn: definisce l'attore mediante il nome dell'entità utente (UPN) dell'attoreactor/upn - defines the actor in form of the actor's user principle name (UPN)
  • target/name: definisce la destinazione mediante il nome dell'attoretarget/name - defines the target in form of the actor's name
  • target/name - definisce la destinazione mediante l'ID della destinazionetarget/objectid - defines the target in form of the target's ID
  • target/upn - definisce l'attore mediante il nome dell'entità utente (UPN) dell'attoretarget/upn - defines the actor in form of the actor's user principle name (UPN)

activityDateactivityDate

Operatori supportati: eq, ge, le, gt, ltSupported operators: eq, ge, le, gt, lt

Esempio:Example:

$filter=tdomain + 'activities/audit?api-version=beta&`$filter=activityDate gt ' + $7daysago    

Note:Notes:

datetime deve essere in formato UTCdatetime should be in UTC format


categorycategory

Valori supportati:Supported values:

CategoriaCategory ValoreValue
Directory principaleCore Directory DirectoryDirectory
Gestione delle password self-serviceSelf-service Password Management SSPRSSPR
Gestione gruppi self-serviceSelf-service Group Management SSGMSSGM
Provisioning degli accountAccount Provisioning SincronizzazioneSync
Automated Password Rollover (Rollover automatizzato delle password)Automated Password Rollover Automated Password Rollover (Rollover automatizzato delle password)Automated Password Rollover
Identity ProtectionIdentity Protection IdentityProtectionIdentityProtection
Utenti invitatiInvited Users Utenti invitatiInvited Users
Servizio MIMMIM Service Servizio MIMMIM Service

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=category eq 'SSPR'

activityStatusactivityStatus

Valori supportati:Supported values:

Stato attivitàActivity Status ValoreValue
SuccessSuccess 00
Esito negativoFailure - 1- 1

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=activityStatus eq -1    

activityTypeactivityType

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=activityType eq 'User'    

Note:Notes:

fa distinzione tra maiuscole e minuscolecase-sensitive


activityactivity

Operatori supportati: eq, contains, startsWithSupported operators: eq, contains, startsWith

Esempio:Example:

$filter=activity eq 'Add application' or contains(activity, 'Application') or startsWith(activity, 'Add')    

Note:Notes:

fa distinzione tra maiuscole e minuscolecase-sensitive


actor/nameactor/name

Operatori supportati: eq, contains, startsWithSupported operators: eq, contains, startsWith

Esempio:Example:

$filter=actor/name eq 'test' or contains(actor/name, 'test') or startswith(actor/name, 'test')    

Note:Notes:

non fa distinzione tra maiuscole e minuscolecase-insensitive


actor/objectidactor/objectId

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=actor/objectId eq 'e8096343-86a2-4384-b43a-ebfdb17600ba'    

target/nametarget/name

Operatori supportati: eq, contains, startsWithSupported operators: eq, contains, startsWith

Esempio:Example:

$filter=targets/any(t: t/name eq 'some name')    

Note:Notes:

Non fa distinzione tra maiuscole e minuscole.Case-insensitive


target/upntarget/upn

Operatori supportati: eq, startsWithSupported operators: eq, startsWith

Esempio:Example:

$filter=targets/any(t: startswith(t/Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.TargetResourceUserEntity/userPrincipalName,'abc'))    

Note:Notes:

  • Non fa distinzione tra maiuscole e minuscole.Case-insensitive
  • È necessario aggiungere lo spazio dei nomi completo quando si eseguono query su Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.TargetResourceUserEntityYou need to add the full namespace when querying Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.TargetResourceUserEntity

target/nametarget/objectId

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=targets/any(t: t/objectId eq 'e8096343-86a2-4384-b43a-ebfdb17600ba')    

actor/upnactor/upn

Operatori supportati: eq, startsWithSupported operators: eq, startsWith

Esempio:Example:

$filter=startswith(actor/Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.ActorUserEntity/userPrincipalName,'abc')    

Note:Notes:

  • Non fa distinzione tra maiuscole e minuscole.Case-insensitive
  • È necessario aggiungere lo spazio dei nomi completo quando si eseguono query su Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.ActorUserEntityYou need to add the full namespace when querying Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting.AuditLog.ActorUserEntity

Fasi successiveNext Steps