Riferimento API del report sull'attività di accesso di Azure Active Directory

Questo argomento fa parte di una raccolta di argomenti sull'API di creazione report di Azure Active Directory.
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. L'obiettivo di questo argomento è fornire informazioni di riferimento sull' API del report sull'attività di accesso.

Vedere:

Chi può accedere ai dati dell'API?

  • Utenti ed entità servizio nel ruolo di amministratore della sicurezza o con autorizzazioni di lettura per la sicurezza
  • Gli amministratori globali
  • 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.

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 sicurezza

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

Prerequisiti

Per accedere a questo report tramite l'API di creazione report, è necessario:

Accesso all'API

È possibile accedere a questa API tramite Graph Explorer o a livello di codice, ad esempio usando 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 $. 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).

Questo argomento si concentra su Graph Explorer. Per un esempio di PowerShell, vedere questo script di PowerShell.

Endpoint API

È possibile accedere a questa API tramite l'URI di base seguente:

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.

Questa chiamata restituisce i dati in batch. Ogni batch contiene un massimo di 1000 record.
Per ottenere il batch successivo di record, usare il link Avanti. Ottenere le informazioni sullo skiptoken dal primo set di record restituiti. Il token skip si trova alla fine del set di risultati.

https://graph.windows.net/$tenantdomain/activities/signinEvents?api-version=beta&%24skiptoken=-1339686058

Filtri supportati

È possibile restringere il numero di record restituiti da una chiamata API usando un filtro.
Per i dati relativi all'API di accesso sono supportati i filtri seguenti:

  • $top=<numero di record da restituire>: per limitare il numero di record restituiti. Si tratta di un'operazione impegnativa. Non è consigliabile usare questo filtro se si desidera restituire migliaia di oggetti.
  • $filter=<istruzione per il filtro>: per specificare il tipo di record da restituire, sulla base dei campi filtro supportati

Operatori e campi dei filtri supportati

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:

  • signinDateTime : definisce una data o un intervallo di date
  • userId : definisce uno specifico utente in base all'ID dell'utente
  • userPrincipalName : definisce uno specifico utente in base al nome dell'entità utente (UPN)
  • appId : definisce una specifica applicazione in base all'ID dell'app
  • appDisplayName : definisce una specifica app in base al nome visualizzato dell'app
  • loginStatus : definisce lo stato dell'accesso (esito positivo/esito negativo)
Nota

Quando si usa Graph Explorer, è necessario distinguere tra lettere maiuscole e minuscole per ogni lettera nei campi del filtro.

Per restringere l'ambito dei dati restituiti, è possibile creare combinazioni dei filtri supportati e dei campi dei filtri. Ad esempio, l'istruzione seguente restituisce i primi 10 record tra il 1° luglio 2016 e il 6 luglio 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

signinDateTime

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

Esempio:

Uso di una data specifica

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

Uso di un intervallo di date

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

Note:

Il parametro datetime deve presentarsi nel formato UTC


userId

Operatori supportati: eq

Esempio:

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

Note:

Il valore di userId è un valore stringa


userPrincipalName

Operatori supportati: eq

Esempio:

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

Note:

Il valore di userPrincipalName è un valore stringa


appId

Operatori supportati: eq

Esempio:

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

Note:

Il valore di appId è un valore stringa


appDisplayName

Operatori supportati: eq

Esempio:

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

Note:

Il valore di appDisplayName è un valore stringa


loginStatus

Operatori supportati: eq

Esempio:

$filter=loginStatus+eq+'1'  

Note:

Sono disponibili due opzioni per loginStatus: 0 - esito positivo, 1 - esito negativo


Passaggi successivi