Riferimento API del report sull'attività di accesso di Azure Active DirectoryAzure Active Directory sign-in activity report 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 del report sull'attività di accesso tramite codice o strumenti correlati.Azure AD reporting provides you with an API that enables you to access sign-in activity report data using code or related tools. L'obiettivo di questo argomento è fornire informazioni di riferimento sull' API del report sull'attività di accesso.The scope of this topic is to provide you with reference information about the sign-in activity report API.

Vedere:See:

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

  • Utenti ed entità servizio nel ruolo di amministratore della sicurezza o con autorizzazioni di lettura per la sicurezzaUsers and Service Principals 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)

Per configurare l'accesso per un'applicazione che usa API di sicurezza, ad esempio eventi di accesso, usare questo comando PowerShell per aggiungere le entità servizio delle applicazioni al ruolo con autorizzazioni di lettura per la sicurezzaTo configure access for an application to access security APIs such as signin events, use the following PowerShell to add the applications Service Principal into the Security Reader role

Connect-MsolService
$servicePrincipal = Get-MsolServicePrincipal -AppPrincipalId "<app client id>"
$role = Get-MsolRole | ? Name -eq "Security Reader"
Add-MsolRoleMember -RoleObjectId $role.ObjectId -RoleMemberType ServicePrincipal -RoleMemberObjectId $servicePrincipal.ObjectId

PrerequisitiPrerequisites

Per accedere a questo report tramite l'API di creazione report, è necessario: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 di base seguente:You can access this API using the following base URI:

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

A causa del volume di dati, questa API presenta un limite di un milione di record restituiti.Due to the volume of data, this API has a limit of one million returned records.

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/$tenantdomain/activities/signinEvents?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:

  • signinDateTime : definisce una data o un intervallo di datesigninDateTime - defines a date or date range
  • userId : definisce uno specifico utente in base all'ID dell'utenteuserId - defines a specific user based the user's ID.
  • userPrincipalName : definisce uno specifico utente in base al nome dell'entità utente (UPN)userPrincipalName - defines a specific user based the user's user principal name (UPN)
  • appId : definisce una specifica applicazione in base all'ID dell'appappId - defines a specific app based the app's ID
  • appDisplayName : definisce una specifica app in base al nome visualizzato dell'appappDisplayName - defines a specific app based the app's display name
  • loginStatus : definisce lo stato dell'accesso (esito positivo/esito negativo)loginStatus - defines the status of the logins (success / failure)

Nota

Quando si usa Graph Explorer, è necessario distinguere tra lettere maiuscole e minuscole per ogni lettera nei campi del filtro.When using Graph Explorer, you the need to use the correct case for each letter is your filter fields.

Per restringere l'ambito dei dati restituiti, è possibile creare combinazioni dei filtri supportati e dei campi dei filtri.To narrow down the scope of the returned data, you can build combinations of the supported filters and filter fields. Ad esempio, l'istruzione seguente restituisce i primi 10 record tra il 1° luglio 2016 e il 6 luglio 2016:For example, the following statement returns the top 10 records between July 1st 2016 and July 6th 2016:

https://graph.windows.net/contoso.com/activities/signinEvents?api-version=beta&$top=10&$filter=signinDateTime+ge+2016-07-01T17:05:21Z+and+signinDateTime+le+2016-07-07T00:00:00Z

signinDateTimesigninDateTime

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

Esempio:Example:

Uso di una data specificaUsing a specific date

$filter=signinDateTime+eq+2016-04-25T23:59:00Z    

Uso di un intervallo di dateUsing a date range

$filter=signinDateTime+ge+2016-07-01T17:05:21Z+and+signinDateTime+le+2016-07-07T17:05:21Z

Note:Notes:

Il parametro datetime deve presentarsi nel formato UTCThe datetime parameter should be in the UTC format


userIduserId

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=userId+eq+’00000000-0000-0000-0000-000000000000’

Note:Notes:

Il valore di userId è un valore stringaThe value of userId is a string value


userPrincipalNameuserPrincipalName

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=userPrincipalName+eq+'audrey.oliver@wingtiptoysonline.com' 

Note:Notes:

Il valore di userPrincipalName è un valore stringaThe value of userPrincipalName is a string value


appIdappId

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=appId+eq+’00000000-0000-0000-0000-000000000000’

Note:Notes:

Il valore di appId è un valore stringaThe value of appId is a string value


appDisplayNameappDisplayName

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=appDisplayName+eq+'Azure+Portal' 

Note:Notes:

Il valore di appDisplayName è un valore stringaThe value of appDisplayName is a string value


loginStatusloginStatus

Operatori supportati: eqSupported operators: eq

Esempio:Example:

$filter=loginStatus+eq+'1'  

Note:Notes:

Sono disponibili due opzioni per loginStatus: 0 - esito positivo, 1 - esito negativoThere are two options for the loginStatus: 0 - success, 1 - failure


Passaggi successiviNext steps