Table of contents

Query, opzioni di paging e filtri supportati | Concetti relativi all'API GraphSupported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|Ultimo aggiornamento: 19/06/2018
|
2 Collaboratori

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).This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API.La sezione finale illustra alcuni esempi di query comuni che si possono eseguire con l'API di Azure AD Graph.The final section gives some examples of common queries that you can perform with the Azure AD Graph API.

Importante

Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Indirizzamento Addressing

Le query riportate di seguito fanno tutte riferimento al tenant con un nome di dominio.The queries below all address the tenant using a domain name.È 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).You can replace contoso.com with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the MyOrganization alias (for delegated access).In alcuni casi, potrebbe essere consentito usare l'alias me.In some cases, you may be able to use the me alias.Per informazioni su altre modalità di definizione del percorso del tenant, vedere Panoramica delle operazioni.For information about ways of addressing the tenant, see Operations overview.

Opzioni di query supportate Supported query options

L'API Graph supporta le opzioni di query seguenti: $filter, $orderby, $expand, $top e $format.The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.Attualmente non sono supportate le opzioni di query seguenti: $count, $inlinecount e $skip.The following query options are not currently supported: $count, $inlinecount, and $skip.

$filter$filter

Le restrizioni generali riportate di seguito si applicano alle query contenenti un filtro:The following general restrictions apply to queries that contain a filter:

  • $filter non è combinabile con espressioni $orderby.$filter cannot be combined with $orderby expressions.

  • Il filtro non è supportato per le query su oggetti directory DirectoryRole o SubscribedSku.Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • Non tutte le proprietà di oggetti directory supportati possono essere usate in un'espressione di filtro.Not all properties of supported directory objects can be used in a filter expression.Per informazioni sulle proprietà filtrabili di tipi supportati, vedere User, Group e Contact.For information about filterable properties of supported types, see User, Group, and Contact.

Le restrizioni seguenti si applicano alle espressioni di filtro:The following restrictions apply to filter expressions:

  • Operatori logici: sono supportati gli operatori and e or,Logical operators: and and or are supported.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')For example: 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).Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • startswith è supportato.startswith is supported.ad esempio https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')For example: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

  • any è supportato per query su proprietà multivalore.any is supported when querying multi-valued properties.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')For example: 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.Arithmetic operators: not supported.

  • Funzioni: non supportate.Functions: not supported.

  • I valori null non sono supportati come operandi nelle espressioni di filtro.null values are not supported as an operand in filter expressions.Ad esempio, non è possibile specificare il valore null per filtrare per proprietà non impostate.For example, you cannot specify a null value to filter for unset properties.

  • 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.To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.

$orderby$orderby

$orderby permette di ordinare gli oggetti restituiti in base al parametro specificato.$orderby will sort the returned objects by the specified parameter.Esempi di richieste che usano l'opzione $orderby:Example requests using the $orderby option:

RichiestaRequestDescrizioneDescription
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Restituisce un elenco di utenti ordinati in base al nome visualizzato.Returns a list of users ordered by their display name.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Restituisce un elenco dei primi 50 utenti ordinati in base al nome visualizzato.Returns a list of the first 50 users ordered by their display name.

Le restrizioni seguenti si applicano alle espressioni $orderby:The following restrictions apply to $orderby expressions:

  • Sono attualmente supportati due criteri di ordinamento: DisplayName per gli oggetti User e Group e UserPrincipalName per gli oggetti User.Two sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects.L'ordinamento predefinito per gli oggetti utente è UserPrincipalName.The default sort order for users is by UserPrincipalName.

  • $orderby non è combinabile con espressioni $filter.$orderby cannot be combined with $filter expressions.

$expand$expand

$expand restituisce un oggetto e i relativi oggetti collegati.$expand will return an object and its linked objects.Esempi di richieste che usano l'opzione $expand:Example requests using the $expand option:

RichiestaRequestDescrizioneDescription
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Restituisce sia l'oggetto gruppo che i relativi membri.Returns both the group object as well as its members.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Restituisce sia l'oggetto utente che i relativi dipendenti diretti.Returns both the user object as well as its direct reports.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Restituisce sia l'oggetto utente che il relativo responsabile.Returns both the user object as well as its manager.

Le restrizioni seguenti si applicano alle espressioni $expand:The following restrictions apply to $expand expressions:

  • Il numero massimo di oggetti restituiti per una richiesta è 20.The maximum number of returned objects for a request is 20.

$top$top

$top non è supportato per le query su oggetti directory DirectoryRole o SubscribedSku.$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

Supporto delle operazioni di paging Paging support

In Graph è possibile passare alla pagina precedente e successiva.You can page forward and backward in the Graph.Una risposta contenente risultati impaginati includerà un token skip (odata.nextLink) che consente di ottenere la pagina di risultati successiva.A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results.Il token skip può essere combinato con un argomento di query previous-page=true per passare alla pagina precedente.This skip token can be combined with a previous-page=true query argument to page backwards.

La richiesta di esempio seguente dimostra il passaggio alla pagina successiva:The follow example request demonstrates paging forward:

RichiestaRequestDescrizioneDescription
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.The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.

La richiesta di esempio seguente dimostra il passaggio alla pagina precedente:The following example request demonstrates paging backward:

RichiestaRequestDescrizioneDescription
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueIl parametro $skiptoken dalla risposta precedente è incluso.The $skiptoken parameter from the previous response is included.Se combinato con il parametro &previous-page=true, verrà recuperata la pagina di risultati precedente.When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.

Nei passaggi seguenti viene illustrato il flusso di richiesta/risposta per passare alla pagina precedente e successiva:The following steps demonstrate the request/response flow to page forward and backward:

  1. Viene inviata una richiesta per recuperare l'elenco dei primi 10 utenti su 15.A request is made to get a list of the first 10 users out of 15.La risposta contiene un token skip per indicare la pagina finale di 10 utenti.The response contains a skip token to indicate the final page of 10 users.
  2. Per ottenere gli ultimi 5 utenti, viene inviata un'altra richiesta contenente il token skip restituito nella risposta precedente.To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  3. 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.To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
  4. La risposta contiene la pagina precedente, ovvero la prima, con i primi 10 utenti.The response contains the previous (first) page of 10 users.In uno scenario diverso in cui vi siano altre pagine, verrebbe restituito un nuovo token skip.In a different scenario where more pages are left, a new skip token would be returned.Il nuovo token skip può essere aggiunto alla richiesta insieme a &previous-page=true per passare nuovamente alla pagina precedente.This new skip token can be added to the request along with &previous-page=true to page backward again.

Le restrizioni seguenti si applicano alle richieste di paging:The following restrictions apply to paged requests:

  • Le dimensioni di pagina predefinite sono pari a 100.The default page size is 100.Le dimensioni massime della pagina sono pari a 999.The maximum page size is 999.
  • Le query sui ruoli non supportano il paging,Queries against roles do not support paging.inclusa la lettura di oggetti di ruolo stessi e membri del ruolo.This includes reading role objects themselves as well as role members.
  • Le query su un elenco di risorse, ad esempio una ricerca per tutti gli utenti di un tenant (/users), supportano le operazioni di paging.Resource listing, such as a search for all users in a tenant (/users), queries do support paging.Ad esempio: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
  • Il paging non è supportato per ricerche su collegamenti, ad esempio nel caso di query sui membri dei gruppi.Paging is not supported for link searches, such as for querying group members.Ad esempio: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.For example: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Ordinamento Sort order

  • Il set di risultati di una query per tutti gli utenti viene ordinato in base alla proprietà UserPrincipalName.The result set of a query for all users is ordered by the UserPrincipalName property.Ad esempio: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.Ad esempio: https://graph.windows.net/contoso.com/groups?api-version=1.6.For example: 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.The order of the results of queries other than for top-level resources is indeterminate.

Query comuni Common queries

Le sezioni seguenti mostrano alcuni esempi di query comuni che è possibile eseguire con l'API Graph.The following sections show some examples of common queries you can perform with the Graph API.

Esecuzione di query su risorse di primo livelloQuerying top-level resources

Le query seguenti indicano come accedere a risorse di primo livello con l'API Graph usando contoso.com come tenant di esempio.The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant.Si noti che per eseguire query su un tenant è necessaria un'intestazione di autorizzazione contenente un token di connessione valido ricevuto da Azure AD.Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.

Risorsa di primo livelloTop-Level ResourceRisultati della queryQuery ResultsURI (per contoso.com)URI (for contoso.com)
Risorse di primo livelloTop-level resourcesViene restituito l'elenco di URI delle risorse di livello superiore per i servizi directory (elencati anche di seguito)Returns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
Informazioni sulla societàCompany informationVengono restituite le informazioni sulla societàReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
ContattiContactsRestituisce le informazioni sui contatti aziendaliReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsersUsersVengono restituite le informazioni sugli utentiReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
GruppiGroupsVengono restituiti i dati dei gruppiReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
Ruoli della directoryDirectory RolesRestituisce tutti i ruoli della directory attivati nel tenantReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusSubscribedSkusVengono restituite le sottoscrizioni del tenantReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadati di directoryDirectory metadataViene 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 directoryReturns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Altre operazioni di queryOther query operations

La tabella seguente mostra alcuni esempi aggiuntivi di query eseguite con l'API Graph usando contoso.com come tenant di esempio.The following table shows some additional example Graph API queries using contoso.com as the example tenant.

Operazione di queryQuery OperationURI (per contoso.com)URI (for contoso.com)
Elencare tutti gli utenti e gruppiList all Users and Groupshttps://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 userPrincipalNameRetrieve individual User by specifying the objectId or userPrincipalNamehttps://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"Request and Filter for a user with displayName equal to “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"Request and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filtrare per i valori givenName e surname.Filter for givenName and surname values.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 objectIdRetrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Recuperare la gestione di un utenteRetrieve a user’s managerhttps://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
Recuperare l'elenco di report diretti di un utenteRetrieve a user’s direct reports listhttps://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 utenteRetrieve a list of links to a user’s direct reportshttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Recuperare l'elenco di appartenenze di un gruppoRetrieve membership list of a grouphttps://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.Retrieve a list of links to the members of a group.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)Retrieve a user’s group membership (not transitive)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)Retrieve a list of the groups that the user is a member of (not transitive)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"Request and filter for groups with displayName >= "az" and <= "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 B2CReturn all local account users in an Azure Active Directory B2C tenanthttps://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 B2CReturn local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://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.Note: White space in the query string should be URL-encoded before sending a request.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.For example, the following query string, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Risorse aggiuntive Additional resources

© 2018 Microsoft