API Graph di Azure Active DirectoryAzure Active Directory Graph API

Importante

Per accedere alle risorse di Azure Active Directoryi è consigliabile usare Microsoft Graph anziché l'API Graph di Azure AD.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Le attività di sviluppo sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti all'API Graph di Azure AD.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. Il numero di scenari in cui potrebbe essere ancora appropriato usare l'API Graph di Azure AD è piuttosto limitato. Per altre informazioni, vedere il post Microsoft Graph o Azure AD Graph nel blog di 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.

L'API Graph di Azure Active Directory consente l'accesso a livello di codice ad Azure AD tramite endpoint dell'API REST.The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. Le applicazioni possono usare l'API Graph per le operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD, Create, Read, Update, Delete) su oggetti e dati della directory.Applications can use the Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Ad esempio, l'API Graph supporta le operazioni comuni seguenti per un oggetto utente:For example, the Graph API supports the following common operations for a user object:

  • Creare un nuovo utente nella directoryCreate a new user in a directory
  • Recuperare le proprietà dettagliate dell'utente, ad esempio i gruppi a cui appartieneGet a user’s detailed properties, such as their groups
  • Aggiornare le proprietà dell'utente, ad esempio indirizzo e numero di telefono, oppure modifica della passwordUpdate a user’s properties, such as their location and phone number, or change their password
  • Verificare l'appartenenza a gruppi di un utente per l'accesso in base al ruoloCheck a user’s group membership for role-based access
  • Disabilitare o eliminare completamente l'account di un utenteDisable a user’s account or delete it entirely

È possibile eseguire operazioni simili anche su altri oggetti, ad esempio gruppi e applicazioni.In addition to user objects, you can perform similar operations on other objects such as groups and applications. Per chiamare l'API Graph su una directory, è necessario che l'applicazione sia registrata in Azure AD e che sia configurata per consentire l'accesso alla directory.To call the Graph API on a directory, the application must be registered with Azure AD and be configured to allow access to the directory. A tale scopo, viene in genere eseguito un flusso di consenso utente o amministratore.This is normally achieved through a user or admin consent flow.

Per iniziare a usare l'API Azure Active Directory Graph, vedere la Guida rapida di Graph API oppure visualizzare la documentazione di riferimento interattiva per l’API Graph .To begin using the Azure Active Directory Graph API, see the Graph API Quickstart Guide, or view the interactive Graph API reference documentation.

FunzionalitàFeatures

L'API Graph offre le funzionalità seguenti:The Graph API provides the following features:

  • Endpoint API REST: l'API Graph è un servizio RESTful che include endpoint a cui viene eseguito l'accesso tramite richieste HTTP standard.REST API Endpoints: The Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. L'API Graph supporta i tipi di contenuto XML o JSON (JavaScript Object Notation) per le richieste e le risposte.The Graph API supports XML or Javascript Object Notation (JSON) content types for requests and responses. Per altre informazioni, vedere Riferimento all'API REST di Azure AD Graph.For more information, see Azure AD Graph REST API Reference.
  • Autenticazione con Azure AD: ogni richiesta all'API Graph deve essere autenticata mediante l'aggiunta di un token Web JSON nell'intestazione dell'autorizzazione della richiesta.Authentication with Azure AD: Every request to the Graph API must be authenticated by appending a JSON Web Token (JWT) in the Authorization header of the request. Per acquisire il token è necessario inviare una richiesta all'endpoint token di Azure AD e specificare credenziali valide.This token is acquired by making a request to Azure AD’s token endpoint and providing valid credentials. Per acquisire un token per chiamare l'API Graph, è possibile usare il flusso delle credenziali client OAuth 2.0 o il flusso di concessione del codice di autorizzazione.You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. Per altre informazioni, vedere OAuth 2.0 in Azure AD.For more information, OAuth 2.0 in Azure AD.
  • Autorizzazione in base al ruolo: vengono usati gruppi di sicurezza per il controllo degli accessi in base al ruolo nell'API Graph.Role-Based Authorization (RBAC): Security groups are used to perform RBAC in the Graph API. Se, ad esempio, si vuole stabilire se un utente può accedere a una risorsa specifica, l'applicazione può chiamare l'operazione di controllo dell'appartenenza a gruppi (transitiva) , che restituirà true o false.For example, if you want to determine whether a user has access to a specific resource, the application can call the Check Group Membership (transitive) operation, which returns true or false.
  • Query differenziale: per verificare se sono state apportate modifiche a una directory tra due intervalli di tempo senza dover interrogare di frequente l'API Graph, è possibile inviare una richiesta di query differenziale.Differential Query: If you want to check for changes in a directory between two time periods without having to make frequent queries to the Graph API, you can make a differential query request. Questo tipo di richiesta restituisce solo le modifiche apportate nel periodo trascorso tra la richiesta di query differenziale precedente e la richiesta corrente.This type of request will return only the changes made between the previous differential query request and the current request. Per altre informazioni, vedere Query differenziale dell'API Graph di Azure AD.For more information, see Azure AD Graph API Differential Query.
  • Estensioni della directory: se si sviluppa un'applicazione che deve eseguire la lettura o la scrittura di proprietà univoche per gli oggetti directory, è possibile eseguire la registrazione e usare i valori dell'estensione mediante l'API Graph.Directory Extensions: If you are developing an application that needs to read or write unique properties for directory objects, you can register and use extension values by using the Graph API. Ad esempio, se l'applicazione richiede una proprietà ID Skype per ogni utente, è possibile registrare la nuova proprietà nella directory e renderla disponibile per ogni oggetto utente.For example, if your application requires a Skype ID property for each user, you can register the new property in the directory and it will be available on every user object. Per altre informazioni, vedere Estensioni dello schema di directory dell'API Graph di Azure AD.For more information, see Azure AD Graph API Directory Schema Extensions.
  • Protetto dagli ambiti di autorizzazione: l'API Graph di AAD espone gli ambiti di autorizzazione che consentono l’accesso protetto/autorizzato ai dati AAD e supportano un'ampia gamma di tipi di applicazioni client, tra cui:Secured by permission scopes: AAD Graph API exposes permission scopes that enable secure/consented access to AAD data, and support a variety of client app types, including:

    • quelli con un'interfaccia utente a cui viene assegnato l'accesso delegato ai dati tramite l'autorizzazione da parte dell'utente connesso (delegato)those with a user interface which are given delegated access to data via authorization from the signed-in user (delegated)
    • quelli che utilizzano il controllo degli accessi in base al ruolo definito dall’applicazione, ad esempio i client di servizio/daemon (ruoli app)those that use application-define role-based access control such as service/daemon clients (app roles)

      Entrambi gli ambiti di autorizzazione delegato e ruolo app rappresentano un privilegio esposto dall'API Graph e possono essere richiesti dalle applicazioni client tramite le funzionalità delle autorizzazioni di registrazione applicazione nel portale di Azure.Both delegated and app role permission scopes represent a privilege exposed by the Graph API and can be requested by client applications through application registration permissions features in the Azure portal. I client possono verificare gli ambiti di autorizzazione concessi controllando l'attestazione di ambito ("scp") ricevuta nel token di accesso per le autorizzazioni delegate e l’attestazione dei ruoli ("roles") per le autorizzazioni del ruolo applicazione.Clients can verify the permission scopes granted to them by inspecting the scope (“scp”) claim received in the access token for delegated permissions and the roles (“roles”) claim for app role permissions. Altre informazioni sugli ambiti di autorizzazione dell'API Graph di Azure AD.Learn more about Azure AD Graph API Permission Scopes.

ScenariScenarios

Gli scenari di applicazione dell'API Graph sono numerosi.The Graph API enables many application scenarios. Ecco i più comuni:The following scenarios are the most common:

  • Applicazione line-of-business (single-tenant): in questo scenario, uno sviluppatore aziendale lavora per un'organizzazione con un abbonamento a Office 365.Line of Business (Single Tenant) Application: In this scenario, an enterprise developer works for an organization that has an Office 365 subscription. Lo sviluppatore sta creando un'applicazione Web che interagisce con Azure AD per eseguire diverse attività, ad esempio l'assegnazione di una licenza a un utente.The developer is building a web application that interacts with Azure AD to perform tasks such assigning a license to a user. Questa attività richiede l'accesso all'API Graph, in modo che lo sviluppatore possa registrare l'applicazione single-tenant in Azure AD e configurare le autorizzazioni di lettura e scrittura per l'API Graph.This task requires access to the Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for the Graph API. L'applicazione viene quindi configurata in modo da usare le proprie credenziali o quelle dell'utente che ha eseguito l'accesso per acquisire un token per chiamare l'API Graph.Then the application is configured to use either its own credentials or those of the currently sign-in user to acquire a token to call the Graph API.
  • Applicazione SaaS (multi-tenant): in questo scenario, un fornitore di software indipendente (ISV) sviluppa un'applicazione Web multi-tenant ospitata che fornisce funzionalità per la gestione degli utenti per altre organizzazioni che usano Azure AD.Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. Queste funzionalità richiedono l'accesso agli oggetti directory, quindi l'applicazione deve chiamare l'API Graph.These features require access to directory objects, and so the application needs to call the Graph API. Lo sviluppatore registra l'applicazione in Azure AD, la configura per richiedere le autorizzazioni di lettura e scrittura per l'API Graph, quindi abilita l'accesso esterno in modo che altre organizzazioni possano fornire il consenso per l'uso dell'applicazione nella propria directory.The developer registers the application in Azure AD, configures it to require read and write permissions for the Graph API, and then enables external access so that other organizations can consent to use the application in their directory. Quando un utente in un'altra organizzazione esegue l'autenticazione nell'applicazione per la prima volta, viene visualizzata una finestra di dialogo di consenso con le autorizzazioni richieste dall'applicazione.When a user in another organization authenticates to the application for the first time, they are shown a consent dialog with the permissions the application is requesting. Se si concede il consenso, l'applicazione riceverà le autorizzazioni richieste per l'API Graph nella directory dell'utente.Granting consent will then give the application those requested permissions to the Graph API in the user’s directory. Per altre informazioni sul framework di consenso, vedere Panoramica del framework di consenso.For more information on the consent framework, see Overview of the Consent Framework.

Vedere ancheSee Also

Guida introduttiva per l'API Graph di Azure ADAzure AD Graph API Quickstart Guide

Documentazione di riferimento all'API Graph di Azure ADAD Graph REST documentation

Guida per gli sviluppatori di Azure Active DirectoryAzure Active Directory developer's guide