Table of contents

Panoramica delle operazioni | Concetti relativi all'API GraphOperations overview | Graph API concepts

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

L'API Graph di Azure Active Directory (Azure AD) è un servizio conforme alla specifica OData 3.0 che consente di leggere e modificare oggetti, ad esempio utenti, gruppi e contatti, in un tenant.The Azure Active Directory (AD) Graph API is an OData 3.0 compliant service that you can use to read and modify objects such as users, groups, and contacts in a tenant.L'API di Azure AD Graph espone endpoint REST a cui si inviano le richieste HTTP per eseguire operazioni usando il servizio.Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service.Le sezioni seguenti forniscono informazioni generali su come formattare le richieste e cosa aspettarsi nelle risposte quando si usa l'API Graph per leggere e scrivere le risorse di directory, chiamare le funzioni o le azioni della directory o eseguire query nella directory.The following sections provide general information about how to format requests and what to expect in responses when you use the Graph API to read and write directory resources, call directory functions or actions, or perform queries against the directory.Per informazioni più dettagliate su come eseguire operazioni specifiche nelle risorse della directory, vedere l'argomento appropriato in Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph).For more detailed information about performing specific operations directory resources, see the appropriate operations topic in the Azure AD Graph API reference.

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.

È necessario definire il percorso di una richiesta riuscita all'API Graph verso un endpoint valido ed eseguirne la formattazione correttamente, vale a dire che deve contenere eventuali intestazioni obbligatorie e, se necessario, un payload JSON nel corpo della richiesta.A successful request to the Graph API must be addressed to a valid endpoint and be well-formatted, that is, it must contain any required headers and, if necessary, a JSON payload in the request body.L'app che effettua la richiesta deve includere un token ricevuto da Azure AD che dimostra che è autorizzato ad accedere alle risorse di destinazione della richiesta.The app making the request must include a token received from Azure AD that proves that it is authorized to access the resources targeted by the request.L'applicazione deve poter gestire le risposte ricevute dall'API Graph.The app must be able to handle any responses received from the Graph API.

Le sezioni in questo argomento consentono di comprendere il formato delle richieste e delle risposte usate con l'API Graph.The sections in this topic will help you understand the format of requests and responses used with the Graph API.

Autenticazione e autorizzazione Authentication and authorization

A ogni richiesta all'API Graph deve essere allegato un token di connessione emesso da Azure Active Directory.Every request to the Graph API must have a bearer token issued by Azure Active Directory attached.Il token trasporta informazioni relative all'app, all'utente connesso (nel caso di autorizzazioni delegate), all'autenticazione e alle operazioni nella directory che l'app è autorizzata a eseguire.The token carries information about your app, the signed-in user (in the case of delegated permissions), authentication, and the operations on the directory that your app is authorized to perform.Questo token viene trasmesso nell'intestazione Authorization della richiesta.This token is carried in the Authorization header of the request.Ad esempio (il token è stato abbreviato):For example (the token has been shortened for brevity):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

L'API Graph esegue l'autorizzazione in base agli ambiti di autorizzazione OAuth 2.0 presenti nel token.The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token.Per altre informazioni sugli ambiti di autorizzazione esposti dall'API Graph, vedere Ambiti di autorizzazione dell'API Graph.For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

Per far sì che l'app esegua l'autenticazione con Azure AD e chiami l'API Graph, è necessario aggiungerla al tenant e configurarla in modo da richiedere le autorizzazioni (ambiti di autorizzazione OAuth 2.0) per Windows Azure Active Directory.In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows Azure Active Directory.Per informazioni sull'aggiunta e sulla configurazione di un'app, vedere Integrazione di applicazioni con Azure Active Directory.For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

Azure AD Usa il protocollo di autenticazione OAuth 2.0.Azure AD uses the OAuth 2.0 authentication protocol.Altre informazioni su OAuth 2.0 in Azure AD, inclusi i flussi e i token di accesso supportati, sono disponibili nell'articolo OAuth 2.0 in Azure AD.You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

Definizione del percorso degli endpoint Endpoint addressing

Per eseguire operazioni con l'API Graph, si inviano richieste HTTP con un metodo supportato ( in genere GET, POST, PATCH, PUT o DELETE) a un endpoint che fa riferimento al servizio, a una raccolta di risorse, a una risorsa specifica, a una proprietà di navigazione di una risorsa oppure a una funzione o azione esposta dal servizio.To perform operations with the Graph API, you send HTTP requests with a supported method - typically GET, POST, PATCH, PUT, or DELETE -- to an endpoint that targets the service, a resource collection, an individual resource, a navigation property of a resource, or a function or action exposed by the service.Gli endpoint sono espressi sotto forma di URL.Endpoints are expressed as URLs.

Di seguito viene descritto il formato di base di un endpoint API Graph:The following describes the basic format of a Graph API endpoint:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

L'URL contiene i componenti seguenti:The following components comprise the URL:

Nota: in alcuni casi, durante la lettura delle raccolte di risorse, è possibile aggiungere parametri di query OData alla richiesta per filtrare, ordinare ed eseguire il paging del set di risultati.Note: In some cases, when reading resource collections, OData query parameters can be added to the request to filter, order, and page the result set.Per altre informazioni, vedere la sezione Parametri di query OData di questo argomento.For more information, see the OData query parameters section in this topic.

Identificatore del tenant {tenant_id} Tenant identifier {tenant_id}

È possibile specificare il tenant di destinazione di una richiesta in uno dei quattro modi seguenti:You can specify the target tenant of a request in one of four ways:

  • Tramite l'ID oggetto del tenant.By tenant object ID.GUID assegnato al momento della creazione del tenant.The GUID that was assigned when the tenant was created.Si trova nella proprietà objectId dell'oggetto TenantDetail.This can be found in the objectId property of the TenantDetail object.L'URL seguente mostra come definire il percorso della raccolta di risorse degli utenti usando l'ID oggetto del tenant:The following URL shows how to address the users resource collection by using the tenant object ID:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Tramite il nome di dominio verificato (registrato).By verified (registered) domain name.Uno dei nomi di dominio registrati per il tenant.One of the domain names that are registered for the tenant.Si trovano nella proprietà verifiedDomains dell'oggetto TenantDetail.These can be found in the verifiedDomains property of the TenantDetail object.L'URL seguente mostra come definire il percorso di una raccolta di risorse degli utenti di un tenant il cui dominio è contoso.com:The following URL shows how to address the users resource collection of a tenant that has the domain contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Tramite l'uso dell'alias myOrganization.By using the myOrganization alias.Questo alias è disponibile solo quando si usa l'autenticazione di tipo Concessione del codice di autorizzazione OAuth (in 3 fasi), cioè quando si usa un ambito di autorizzazione delegata.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.L'alias non fa distinzione tra maiuscole e minuscole.The alias is not case sensitive.Sostituisce l'ID dell'oggetto o il dominio del tenant nell'URL.It replaces the object ID or tenant domain in the URL.Quando si usa l'alias, l'API Graph deriva il tenant dalle attestazioni presentate nel token associato alla richiesta.When the alias is used, Graph API derives the tenant from the claims presented in the token attached to the request.L'URL seguente mostra come definire il percorso della raccolta di risorse degli utenti di un tenant usando questo alias:The following URL shows how to address the users resource collection of a tenant using this alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.https://graph.windows.net/myorganization/users?api-version=1.6.

  • Tramite l'uso dell'alias me.By using the me alias.Questo alias è disponibile solo quando si usa l'autenticazione di tipo Concessione del codice di autorizzazione OAuth (in 3 fasi), cioè quando si usa un ambito di autorizzazione delegata.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.L'alias non fa distinzione tra maiuscole e minuscole.The alias is not case sensitive.Sostituisce l'ID dell'oggetto o il dominio del tenant nell'URL.It replaces the object ID or tenant domain in the URL.Quando si usa l'alias, l'API Graph deriva l'utente dalle attestazioni presentate nel token associato alla richiesta.When the alias is used, Graph API derives the user from the claims presented in the token attached to the request.L'URL seguente consente di definire il percorso per l'utente connesso usando l'alias:The following URL to address the signed-in user using this alias:
    https://graph.windows.net/me?api-version=1.6.https://graph.windows.net/me?api-version=1.6.

Nota: l'alias me viene usato esclusivamente per indicare la destinazione delle operazioni rispetto all'utente connesso.Note: You use me alias solely to target operations against the signed-in user.Per altre informazioni, vedere l'articolo relativo alle operazioni dell'utente connesso.For more information, see Signed-in User Operations.

Percorso della risorsa {resource_path} Resource path {resource_path}

Specificare il {resource_path} in modo diverso a seconda che si usi una raccolta di risorse, una singola risorsa, una proprietà di navigazione di una risorsa, una funzione o un'azione esposte nel tenant o una funzione o un'azione esposte in una risorsa.You specify the {resource_path} differently depending on whether you are targeting a resource collection, an individual resource, a navigation property of a resource, a function or action exposed on the tenant, or a function or action exposed on a resource.

DestinazioneTargetPercorsoPathSpiegazioneExplanation
Metadati del servizioService Metadata/$metadataRestituisce il documento dei metadati del servizio.Returns the service metadata document.L'esempio seguente indica che la destinazione sono i metadati del servizio usando il tenant contoso.com:The following example targets service metadata using the contoso.com tenant:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Nota: nessuna autenticazione è necessaria per leggere i metadati del servizio.Note: No authentication is necessary to read the service metadata.
Raccolta di risorseResource collection/{resource_collection}Indica che la destinazione è una raccolta di risorse, ad esempio utenti o gruppi nel tenant.Targets a resource collection, such as users or groups in the tenant.È possibile usare questo percorso per la lettura delle risorse nella raccolta e, a seconda del tipo di risorsa, per creare una nuova risorsa nel tenant.You can use this path to read resources in the collection, and, depending on the resource type, to create a new resource in the tenant.In molti casi, il set di risultati restituito da un'operazione di lettura può essere ridefinito ulteriormente con l'aggiunta di parametri di query per filtrare, ordinare o eseguire il paging dei risultati di pagina.In many cases the result set returned by a read can be further refined by the addition of query parameters to filter, order, or page the results.L'esempio seguente indica che la destinazione è la raccolta di utenti:The following example targets the user collection:
https://graph.windows.net/myorganization/users?api-version=1.6
Singola risorsaSingle resource/{resource_collection}/{resource_id}Indica che la destinazione è una risorsa specifica in un tenant, ad esempio un utente, un contatto aziendale o un gruppo.Targets a specific resource in a tenant, such as a user, organizational contact, or group.Per la maggior parte delle risorse, l'resource_id è l'ID oggetto.For most resources the resource_id is the object ID.Alcune risorse consentono identificatori aggiuntivi; ad esempio, gli utenti possono essere specificati anche dal nome dell'entità utente (UPN).Some resources allow additional specifiers; for example, users can be also specified by user principal name (UPN).A seconda della risorsa, è possibile usare questo percorso per ottenere le proprietà dichiarate della risorsa, per modificarne le proprietà dichiarate oppure per eliminare la risorsa.Depending on the resource, you can use this path to get the declared properties of the resource, to modify its declared properties, or to delete the resource.L'esempio seguente indica che la destinazione è l'utente john@contoso.com:The following example targets the user john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Proprietà di navigazione (oggetti)Navigation property (objects)/{resource_collection}/{resource_id}/{property_name}Indica che la destinazione è una proprietà di navigazione di una risorsa specifica, ad esempio il responsabile o l'appartenenza a gruppi di un utente oppure i membri di un gruppo.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.È possibile usare questo percorso per restituire gli oggetti a cui fa riferimento la proprietà di navigazione di destinazione.You can use this path to return the object or objects referenced by the target navigation property.L'esempio seguente indica che la destinazione è il responsabile di john@contoso.com:The following example targets the manager of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Nota: questo modello di definizione del percorso è disponibile solo per le operazioni di lettura.Note: This form of addressing is only available for reads.
Proprietà di navigazione (collegamenti)Navigation property (links)/{resource_collection}/{resource_id}/$links/{property_name}Indica che la destinazione è una proprietà di navigazione di una risorsa specifica, ad esempio il responsabile o l'appartenenza a gruppi di un utente oppure i membri di un gruppo.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.È possibile usare questo modello di definizione del percorso per le operazioni di lettura e di modifica di una proprietà di navigazione.You can use this form of addressing to both read and modify a navigation property.Per le operazioni di lettura, gli oggetti a cui fa riferimento la proprietà vengono restituiti come uno o più collegamenti nel corpo della risposta.On reads, the objects referenced by the property are returned as one or more links in the response body.Per le operazioni di scrittura, gli oggetti sono specificati come uno o più collegamenti nel corpo della richiesta.On writes, the objects are specified as one or more links in the request body.L'esempio seguente indica che la destinazione è la proprietà manager di john@contoso.com:The following example targets the manager property of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funzioni o azioni esposte nel tenantFunctions or actions exposed on the tenant/{function_name}Indica che la destinazione è una funzione o un'azione esposta nel tenant.Targets a function or action exposed at the tenant.Le funzioni e le azioni vengono in genere richiamate con una richiesta POST e possono includere il testo di una richiesta.Functions and actions are typically invoked with a POST Request and may include a request body.L'esempio seguente indica che la destinazione è la funzione isMemberOf:The following example targets the isMemberOf function:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funzioni o azioni esposte in una risorsa.Functions or actions exposed on a resource./{resource_collection}/{resource_id}/{function_name}Indica che la destinazione è una funzione o un'azione esposta in una risorsa.Targets a function or action exposed on a resource.Le funzioni e le azioni vengono in genere richiamate con una richiesta POST e possono includere il testo di una richiesta.Functions and actions are typically invoked with a POST Request and may include a request body.L'esempio seguente indica che la destinazione è la funzione getMemberGroups:The following example targets the getMemberGroups function:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Versione dell'API Graph {api-version} Graph API version {api-version}

Usare il parametro di query api-version per indicare che la destinazione è una versione specifica dell'API Graph per un'operazione.You use the api-version query parameter to target a specific version of the Graph API for an operation.Questo parametro è obbligatorio.This parameter is required.

Il parametro api-version può avere uno dei seguenti valori:The value for the api-version parameter can be one of the following:

  • "beta""beta"
  • "1.6""1.6"
  • "1.5""1.5"
  • "2013/11/08""2013/11/08"
  • "2013/04/05""2013/04/05"

Ad esempio l'URL seguente indica che la destinazione è la raccolta di utenti che usa l'API Graph versione 1.6:For example the following URL targets the user collection using Graph API version 1.6:

https://graph.windows.net/myorganization/users?api-version=1.6

Per altre informazioni sulle versioni e sulle modifiche di funzionalità tra le versioni, vedere Controllo delle versioni.For more information about versions and feature changes between versions, see Versioning.

Parametri di query OData OData query parameters

In molti casi durante la lettura di una raccolta di risorse è possibile filtrare, ordinare ed eseguire il paging del set di risultati associando dei parametri di query OData alla richiesta.In many cases when you read a collection of resources, you can filter, sort, and page the result set by attaching OData query parameters to your request.

L'API Graph supporta i parametri di query OData seguenti:The Graph API supports the following Odata query parameters:

  • $filter$filter
  • $batch$batch
  • $expand$expand
  • $orderby$orderby
  • $top$top
  • $skiptoken e previous-page$skiptoken and previous-page

Per altre informazioni sui parametri di query OData supportati e sulle relative limitazioni nell'API Graph, vedere Query, opzioni di paging e filtri supportati.See Supported Queries, Filters, and Paging Options for more information about supported OData query parameters and their limitations in the Graph API.

Intestazioni di richiesta e risposta Request and response headers

La tabella seguente mostra le intestazioni HTTP comuni usate nelle richieste con l'API GraphThe following table shows common HTTP headers used in requests with the Graph API.e non intende essere completa.It is not meant to be comprehensive.

Intestazione della richiestaRequest HeaderDescrizioneDescription
AutorizzazioneAuthorizationObbligatorio.Required.Token di connessione rilasciato da Azure Active Directory.A bearer token issued by Azure Active Directory.Per altre informazioni, vedere Autenticazione e autorizzazione in questo argomento.See Authentication and Authorization in this topic for more information.
Content-TypeContent-TypeObbligatorio se è presente il corpo della richiesta.Required if request body is present.Tipo di supporto del contenuto nel corpo della richiesta.The media type of the content in the request body.Usare application/json.Use application/json.È possibile includere i parametri nel tipo di supporto.Parameters may be included with the media type.
Nota: application/atom + xml e application/xml (per i collegamenti) sono supportati, ma non sono consigliati sia per motivi di prestazioni sia perché il supporto per XML verrà rimosso in una versione futura.Note: application/atom+xml and application/xml (for links) are supported but are not recommended both for performance reasons and because support for XML will be deprecated in a future release.
Content-LengthContent-LengthObbligatorio se è presente il corpo della richiesta.Required if request body is present.Lunghezza della richiesta in byte.The length of the request in bytes.

La tabella seguente mostra le intestazioni HTTP comuni restituite nelle risposte dall'API GraphThe following table shows common HTTP headers returned in responses by the Graph API.e non intende essere completa.It is not meant to be comprehensive.

Intestazione della rispostaResponse HeaderDescrizioneDescription
Content-TypeContent-TypeTipo di dati multimediali del contenuto nel corpo della risposta.The media type of the content in the response body.Il valore predefinito è application/json.The default is application/json.Per impostazione predefinita, le richieste di foto di anteprima utente restituiscono image/jpeg.Requests for user thumbnail photos return image/jpeg by default.
PercorsoLocationRestituito nelle risposte alle richieste POST che creano una nuova risorsa (oggetto) nella directory.Returned in responses to POST requests that create a new resource (object) in the directory.Contiene l'URI della risorsa appena creata.Contains the URI of the newly created resource.
ocp-aad-diagnostics-server-nameocp-aad-diagnostics-server-nameIdentificatore del server che ha eseguito l'operazione richiesta.The identifier for the server that performed the requested operation.
ocp-aad-session-keyocp-aad-session-keyChiave che identifica la sessione corrente con il servizio directory.The key that identifies the current session with the directory service.

Come minimo, è consigliabile eseguire le operazioni seguenti per ogni richiesta:At a minimum, we recommend you do the following for each request:

  1. Registrare un timestamp preciso dell'invio della richiesta.Log an accurate time stamp of the request submission.
  2. Inviare e registrare l'client-request-id.Send and log the client-request-id.
  3. Registrare il codice di risposta HTTP e request-id.Log the HTTP response code and request-id.

Le informazioni fornite in questi log saranno d'aiuto nel risolvere i problemi quando si chiede assistenza a Microsoft.Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

Testi di richieste e risposteRequest and response bodies

I testi delle richieste POST, PATCH e PUT possono essere inviati in payload JSON o XML.Request bodies for POST, PATCH, and PUT requests can be sent in JSON or XML payloads.Le risposte del server possono essere restituite nei payload JSON o XML.Server responses can be returned in JSON or XML payloads.È possibile specificare il payload nei testi delle richieste usando l'intestazione della richiesta Content-Type e nelle risposte usando l'intestazione della richiesta Accept.You can specify the payload in request bodies by using the Content-Type request header and in responses by using the Accept request header.

È fortemente consigliabile usare i payload JSON nelle richieste e nelle risposte con l'API Graph sia per motivi di prestazioni sia perché XML verrà deprecato in una versione futura.We strongly recommend that you use JSON payloads in requests and responses with the Graph API. This is both for performance reasons and because XML will be deprecated in a future release.

Funzionalità avanzateAdvanced features

Le sezioni precedenti hanno illustrato la formattazione delle richieste e risposte di base con l'API Graph.The preceding sections discussed the formatting of basic requests and responses with the Graph API.Le funzionalità più avanzate possono aggiungere ulteriori parametri delle stringhe di query o comportare testi di richiesta e risposta notevolmente diversi rispetto alle operazioni di base descritte in precedenza in questo argomento.More advanced features may add additional query string parameters or have significantly different request and response bodies than the basic operations discussed previously in this topic.

Queste funzionalità comprendono:These features include:

  • Elaborazione batch: l'API Graph supporta l'invio in batch.Batch Processing: The Graph API supports batching.L'invio di richieste in batch riduce i round trip al server e, di conseguenza, il carico di rete, contribuendo al completamento più rapido delle operazioni.Sending requests in batches reduces round trips to the server, which reduces network overhead and helps your operations complete more quickly.Per altre informazioni sull'elaborazione batch con l'API Graph, vedere Elaborazione batch.For more information about batch processing with the Graph API, see Batch Processing.
  • Query differenziale: l'API Graph supporta l'esecuzione di query differenziali.Differential Query: The Graph API supports performing differential queries.La query differenziale consente di restituire le modifiche a entità specifiche in un tenant tra le richieste emesse in momenti diversi.Differential query allows you to return changes to specific entities in a tenant between requests issued at different times.Questa funzionalità viene spesso usata per sincronizzare un archivio locale con le modifiche nel tenant.This feature is often used to sync a local store with changes on the tenant.Per altre informazioni sulla query differenziale con l'API Graph, vedere Query differenziale.For more information about differential query with the Graph API, see Differential Query.

Risorse aggiuntive Additional resources

© 2018 Microsoft