Panoramica delle operazioni | Concetti relativi all'API Graph

  • Articolo

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. L'API di Azure AD Graph espone endpoint REST a cui si inviano le richieste HTTP per eseguire operazioni usando il servizio. 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. 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).

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.

È 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. 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. L'applicazione deve poter gestire le risposte ricevute dall'API Graph.

Le sezioni in questo argomento consentono di comprendere il formato delle richieste e delle risposte usate con l'API Graph.

Autenticazione e autorizzazione

A ogni richiesta all'API Graph deve essere allegato un token di connessione emesso da Azure Active Directory. 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. Questo token viene trasmesso nell'intestazione Authorization della richiesta. Ad esempio (il token è stato abbreviato):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

L'API Graph esegue l'autorizzazione in base agli ambiti di autorizzazione OAuth 2.0 presenti nel token. Per altre informazioni sugli ambiti di autorizzazione esposti dall'API Graph, vedere Ambiti di autorizzazione dell'API Graph.

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. Per informazioni sull'aggiunta e sulla configurazione di un'app, vedere Integrazione di applicazioni con Azure Active Directory.

Azure AD Usa il protocollo di autenticazione OAuth 2.0. 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.

Definizione del percorso degli endpoint

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. Gli endpoint sono espressi sotto forma di URL.

Di seguito viene descritto il formato di base di un endpoint API Graph:

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

L'URL contiene i componenti seguenti:

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. Per altre informazioni, vedere la sezione Parametri di query OData di questo argomento.

Identificatore del tenant {tenant_id}

È possibile specificare il tenant di destinazione di una richiesta in uno dei quattro modi seguenti:

  • Tramite l'ID oggetto del tenant. GUID assegnato al momento della creazione del tenant. Si trova nella proprietà objectId dell'oggetto TenantDetail. L'URL seguente mostra come definire il percorso della raccolta di risorse degli utenti usando l'ID oggetto del tenant:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Tramite il nome di dominio verificato (registrato). Uno dei nomi di dominio registrati per il tenant. Si trovano nella proprietà verifiedDomains dell'oggetto TenantDetail. L'URL seguente mostra come definire il percorso di una raccolta di risorse degli utenti di un tenant il cui dominio è contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Tramite l'uso dell'alias myOrganization. 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. L'alias non fa distinzione tra maiuscole e minuscole. Sostituisce l'ID dell'oggetto o il dominio del tenant nell'URL. Quando si usa l'alias, l'API Graph deriva il tenant dalle attestazioni presentate nel token associato alla richiesta. L'URL seguente mostra come definire il percorso della raccolta di risorse degli utenti di un tenant usando questo alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Tramite l'uso dell'alias me. 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. L'alias non fa distinzione tra maiuscole e minuscole. Sostituisce l'ID dell'oggetto o il dominio del tenant nell'URL. Quando si usa l'alias, l'API Graph deriva l'utente dalle attestazioni presentate nel token associato alla richiesta. L'URL seguente consente di definire il percorso per l'utente connesso usando l'alias:
    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. Per altre informazioni, vedere l'articolo relativo alle operazioni dell'utente connesso.

Percorso della risorsa {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.

Destinazione Percorso Spiegazione
Metadati del servizio /$metadata Restituisce il documento dei metadati del servizio. L'esempio seguente indica che la destinazione sono i metadati del servizio usando il tenant contoso.com:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Nota: nessuna autenticazione è necessaria per leggere i metadati del servizio.
Raccolta di risorse /{resource_collection} Indica che la destinazione è una raccolta di risorse, ad esempio utenti o gruppi nel 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. 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. L'esempio seguente indica che la destinazione è la raccolta di utenti:
https://graph.windows.net/myorganization/users?api-version=1.6
Singola risorsa /{resource_collection}/{resource_id} Indica che la destinazione è una risorsa specifica in un tenant, ad esempio un utente, un contatto aziendale o un gruppo. Per la maggior parte delle risorse, l'resource_id è l'ID oggetto. Alcune risorse consentono identificatori aggiuntivi; ad esempio, gli utenti possono essere specificati anche dal nome dell'entità utente (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. L'esempio seguente indica che la destinazione è l'utente john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Proprietà di navigazione (oggetti) /{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. È possibile usare questo percorso per restituire gli oggetti a cui fa riferimento la proprietà di navigazione di destinazione. L'esempio seguente indica che la destinazione è il responsabile di 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.
Proprietà di navigazione (collegamenti) /{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. È possibile usare questo modello di definizione del percorso per le operazioni di lettura e di modifica di una proprietà di navigazione. Per le operazioni di lettura, gli oggetti a cui fa riferimento la proprietà vengono restituiti come uno o più collegamenti nel corpo della risposta. Per le operazioni di scrittura, gli oggetti sono specificati come uno o più collegamenti nel corpo della richiesta. L'esempio seguente indica che la destinazione è la proprietà manager di john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funzioni o azioni esposte nel tenant /{function_name} Indica che la destinazione è una funzione o un'azione esposta nel tenant. Le funzioni e le azioni vengono in genere richiamate con una richiesta POST e possono includere il testo di una richiesta. L'esempio seguente indica che la destinazione è la funzione isMemberOf:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funzioni o azioni esposte in una risorsa. /{resource_collection}/{resource_id}/{function_name} Indica che la destinazione è una funzione o un'azione esposta in una risorsa. Le funzioni e le azioni vengono in genere richiamate con una richiesta POST e possono includere il testo di una richiesta. L'esempio seguente indica che la destinazione è la funzione getMemberGroups:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Versione dell'API Graph {api-version}

Usare il parametro di query api-version per indicare che la destinazione è una versione specifica dell'API Graph per un'operazione. Questo parametro è obbligatorio.

Il parametro api-version può avere uno dei seguenti valori:

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

Ad esempio l'URL seguente indica che la destinazione è la raccolta di utenti che usa l'API Graph versione 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.

Parametri di query OData

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.

L'API Graph supporta i parametri di query OData seguenti:

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken e 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.

Intestazioni di richiesta e risposta

La tabella seguente mostra le intestazioni HTTP comuni usate nelle richieste con l'API Graph e non intende essere completa.

Intestazione della richiesta Descrizione
Autorizzazione Obbligatorio. Token di connessione rilasciato da Azure Active Directory. Per altre informazioni, vedere Autenticazione e autorizzazione in questo argomento.
Content-Type Obbligatorio se è presente il corpo della richiesta. Tipo di supporto del contenuto nel corpo della richiesta. Usare application/json. È possibile includere i parametri nel tipo di supporto.
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.
Content-Length Obbligatorio se è presente il corpo della richiesta. Lunghezza della richiesta in byte.

La tabella seguente mostra le intestazioni HTTP comuni restituite nelle risposte dall'API Graph e non intende essere completa.

Intestazione della risposta Descrizione
Content-Type Tipo di dati multimediali del contenuto nel corpo della risposta. Il valore predefinito è application/json. Per impostazione predefinita, le richieste di foto di anteprima utente restituiscono image/jpeg.
Percorso Restituito nelle risposte alle richieste POST che creano una nuova risorsa (oggetto) nella directory. Contiene l'URI della risorsa appena creata.
ocp-aad-diagnostics-server-name Identificatore del server che ha eseguito l'operazione richiesta.
ocp-aad-session-key Chiave che identifica la sessione corrente con il servizio directory.

Come minimo, è consigliabile eseguire le operazioni seguenti per ogni richiesta:

  1. Registrare un timestamp preciso dell'invio della richiesta.
  2. Inviare e registrare l'client-request-id.
  3. Registrare il codice di risposta HTTP e request-id.

Le informazioni fornite in questi log saranno d'aiuto nel risolvere i problemi quando si chiede assistenza a Microsoft.

Testi di richieste e risposte

I testi delle richieste POST, PATCH e PUT possono essere inviati in payload JSON o XML. Le risposte del server possono essere restituite nei payload JSON o XML. È possibile specificare il payload nei testi delle richieste usando l'intestazione della richiesta Content-Type e nelle risposte usando l'intestazione della richiesta Accept.

È 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.

Funzionalità avanzate

Le sezioni precedenti hanno illustrato la formattazione delle richieste e risposte di base con l'API Graph. 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.

Queste funzionalità comprendono:

  • Elaborazione batch: l'API Graph supporta l'invio in batch. 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. Per altre informazioni sull'elaborazione batch con l'API Graph, vedere Elaborazione batch.
  • Query differenziale: l'API Graph supporta l'esecuzione di query differenziali. La query differenziale consente di restituire le modifiche a entità specifiche in un tenant tra le richieste emesse in momenti diversi. Questa funzionalità viene spesso usata per sincronizzare un archivio locale con le modifiche nel tenant. Per altre informazioni sulla query differenziale con l'API Graph, vedere Query differenziale.

Risorse aggiuntive