Query, opzioni di paging e filtri supportati | Concetti relativi all'API Graph
Questo argomento elenca i filtri, le opzioni di query e le operazioni di paging che è possibile usare con l'API Graph di Azure Active Directory (Azure AD). La sezione finale illustra alcuni esempi di query comuni che si possono eseguire con l'API di Azure AD Graph.
Importante
Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph. Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph. Può essere ancora opportuno usare questa API in un numero molto limitato di scenari. Per altre informazioni, vedere il post di blog Microsoft Graph or the Azure AD Graph (Microsoft Graph o Azure AD Graph) in Office Developer Center.
Indirizzamento
Le query riportate di seguito fanno tutte riferimento al tenant con un nome di dominio. È possibile sostituire contoso.com con uno dei nomi di dominio registrati del tenant in uso, con l'ID del tenant (GUID) oppure con l'alias MyOrganization (per l'accesso delegato). In alcuni casi, potrebbe essere consentito usare l'alias me. Per informazioni su altre modalità di definizione del percorso del tenant, vedere Panoramica delle operazioni.
Opzioni di query supportate
L'API Graph supporta le opzioni di query seguenti: $filter, $orderby, $expand, $top e $format. Attualmente non sono supportate le opzioni di query seguenti: $count, $inlinecount e $skip.
$filter
Le restrizioni generali riportate di seguito si applicano alle query contenenti un filtro:
$filter non è combinabile con espressioni $orderby.
Il filtro non è supportato per le query su oggetti directory DirectoryRole o SubscribedSku.
Non tutte le proprietà di oggetti directory supportati possono essere usate in un'espressione di filtro. Per informazioni sulle proprietà filtrabili di tipi supportati, vedere User, Group e Contact.
Le restrizioni seguenti si applicano alle espressioni di filtro:
Operatori logici: sono supportati gli operatori and e or, ad esempio
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')Operatori di confronto: sono supportati gli operatori eq (uguale a), ge (maggiore o uguale a) e le (minore o uguale a).
startswith è supportato. ad esempio
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')any è supportato per query su proprietà multivalore. ad esempio
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')Operatori aritmetici: non supportati.
Funzioni: non supportate.
I valori null non sono supportati come operandi nelle espressioni di filtro. Ad esempio, non è possibile specificare il valore null per filtrare per proprietà non impostate.
Per filtrare in base a una proprietà binaria, ad esempio issuerUserId in userIdentities, il valore deve essere codificato base64 prima di poter essere usato nella stringa $filter.
$orderby
$orderby permette di ordinare gli oggetti restituiti in base al parametro specificato. Esempi di richieste che usano l'opzione $orderby:
| Richiesta | Descrizione |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Restituisce un elenco di utenti ordinati in base al nome visualizzato. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Restituisce un elenco dei primi 50 utenti ordinati in base al nome visualizzato. |
Le restrizioni seguenti si applicano alle espressioni $orderby:
Sono attualmente supportati due criteri di ordinamento: DisplayName per gli oggetti User e Group e UserPrincipalName per gli oggetti User. L'ordinamento predefinito per gli oggetti utente è UserPrincipalName.
$orderby non è combinabile con espressioni $filter.
$expand
$expand restituisce un oggetto e i relativi oggetti collegati. Esempi di richieste che usano l'opzione $expand:
| Richiesta | Descrizione |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Restituisce sia l'oggetto gruppo che i relativi membri. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Restituisce sia l'oggetto utente che i relativi dipendenti diretti. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Restituisce sia l'oggetto utente che il relativo responsabile. |
Le restrizioni seguenti si applicano alle espressioni $expand:
- Il numero massimo di oggetti restituiti per una richiesta è 20.
$top
$top non è supportato per le query su oggetti directory DirectoryRole o SubscribedSku.
Supporto delle operazioni di paging
In Graph è possibile passare alla pagina precedente e successiva. Una risposta contenente risultati impaginati includerà un token skip (odata.nextLink) che consente di ottenere la pagina di risultati successiva. Il token skip può essere combinato con un argomento di query previous-page=true per passare alla pagina precedente.
La richiesta di esempio seguente dimostra il passaggio alla pagina successiva:
| Richiesta | Descrizione |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
Il parametro $skiptoken dalla risposta precedente è incluso e consente di ottenere la pagina di risultati successiva. |
La richiesta di esempio seguente dimostra il passaggio alla pagina precedente:
| Richiesta | Descrizione |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
Il parametro $skiptoken dalla risposta precedente è incluso. Se combinato con il parametro &previous-page=true, verrà recuperata la pagina di risultati precedente. |
Nei passaggi seguenti viene illustrato il flusso di richiesta/risposta per passare alla pagina precedente e successiva:
- Viene inviata una richiesta per recuperare l'elenco dei primi 10 utenti su 15. La risposta contiene un token skip per indicare la pagina finale di 10 utenti.
- Per ottenere gli ultimi 5 utenti, viene inviata un'altra richiesta contenente il token skip restituito nella risposta precedente.
- Per passare alla pagina precedente, viene inviata una richiesta che usa il token skip restituito nel passaggio 1 e viene aggiunto alla richiesta il parametro &previous-page=true.
- La risposta contiene la pagina precedente, ovvero la prima, con i primi 10 utenti. In uno scenario diverso in cui vi siano altre pagine, verrebbe restituito un nuovo token skip. Il nuovo token skip può essere aggiunto alla richiesta insieme a &previous-page=true per passare nuovamente alla pagina precedente.
Le restrizioni seguenti si applicano alle richieste di paging:
- Le dimensioni di pagina predefinite sono pari a 100. Le dimensioni massime della pagina sono pari a 999.
- Le query sui ruoli non supportano il paging, inclusa la lettura di oggetti di ruolo stessi e membri del ruolo.
- Le query su un elenco di risorse, ad esempio una ricerca per tutti gli utenti di un tenant (/users), supportano le operazioni di paging. Ad esempio:
https://graph.windows.net/contoso.com/users?api-version=1.6. Per tutti i tipi di richieste, tuttavia, quando è applicato un filtro il paging non è supportato e viene restituita solo la prima pagina di risultati. - Il paging non è supportato per ricerche su collegamenti, ad esempio nel caso di query sui membri dei gruppi. Ad esempio:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Ordinamento
- Il set di risultati di una query per tutti gli utenti viene ordinato in base alla proprietà UserPrincipalName. Ad esempio:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Il set di risultati di una query per tutte le altre risorse di primo livello, ad esempio gruppi, contatti e così via,viene ordinato in base alla proprietà objectId. Ad esempio:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - L'ordine dei risultati di query è indeterminato, a eccezione delle risorse di livello superiore.
Query comuni
Le sezioni seguenti mostrano alcuni esempi di query comuni che è possibile eseguire con l'API Graph.
Esecuzione di query su risorse di primo livello
Le query seguenti indicano come accedere a risorse di primo livello con l'API Graph usando contoso.com come tenant di esempio. Si noti che per eseguire query su un tenant è necessaria un'intestazione di autorizzazione contenente un token di connessione valido ricevuto da Azure AD.
| Risorsa di primo livello | Risultati della query | URI (per contoso.com) |
|---|---|---|
| Risorse di primo livello | Viene restituito l'elenco di URI delle risorse di livello superiore per i servizi directory (elencati anche di seguito) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informazioni sulla società | Vengono restituite le informazioni sulla società | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Contatti | Restituisce le informazioni sui contatti aziendali | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Vengono restituite le informazioni sugli utenti | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Gruppi | Vengono restituiti i dati dei gruppi | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Ruoli della directory | Restituisce tutti i ruoli della directory attivati nel tenant | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Vengono restituite le sottoscrizioni del tenant | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Metadati di directory | Viene restituito un documento dei metadati del servizio in cui viene descritto il modello di dati, vale a dire la struttura e l'organizzazione delle risorse della directory | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Altre operazioni di query
La tabella seguente mostra alcuni esempi aggiuntivi di query eseguite con l'API Graph usando contoso.com come tenant di esempio.
| Operazione di query | URI (per contoso.com) |
|---|---|
| Elencare tutti gli utenti e gruppi | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Recuperare il singolo utente specificando objectId o userPrincipalName | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| Effettuare una richiesta e filtrare per un utente con displayName uguale a "Jon Doe" | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Effettuare una richiesta e filtrare per utenti specifici con firstName uguale a "Jon" | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtrare per i valori givenName e surname. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Recuperare il singolo gruppo specificando il valore objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Recuperare la gestione di un utente | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Recuperare l'elenco di report diretti di un utente | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Recuperare un elenco di collegamenti ai report diretti di un utente | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Recuperare l'elenco di appartenenze di un gruppo | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Recuperare un elenco di collegamenti ai membri di un gruppo. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Recuperare l'appartenenza a un gruppo di un utente (non transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Recuperare un elenco dei gruppi di cui l'utente è un membro (non transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Effettuare una richiesta e filtrare per gruppi con displayName >= "az" e <= "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Restituire tutti gli utenti account locale in un tenant Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Restituire l'utente account locale con il nome di accesso "joe@example.com" da un tenant di Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Nota: per gli spazi vuoti nella stringa di query è necessario applicare la codifica URL prima di inviare una richiesta. Ad esempio, alla stringa di query https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 seguente deve essere applicata la codifica URL come: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.
Risorse aggiuntive
- Query differenziale dell'API di Azure AD Graph
- Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph)