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 di Azure AD per le operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD, Create, Read, Update, Delete) su oggetti e dati della directory.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Ad esempio, l'API Graph di Azure AD supporta le operazioni comuni seguenti per un oggetto utente:For example, Azure AD 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

È inoltre possibile eseguire operazioni simili su altri oggetti, ad esempio gruppi e applicazioni.Additionally, you can perform similar operations on other objects such as groups and applications. Per chiamare l'API Graph di Azure AD su una directory, l'applicazione deve essere registrata con Azure ADTo call Azure AD Graph API on a directory, your application must be registered with Azure AD. e deve anche disporre dei diritti di accesso all'API Graph di Azure AD.Your application must also be granted access to Azure AD Graph API. L'accesso viene in genere ottenuto tramite un flusso di consenso utente o amministratore.This access is normally achieved through a user or admin consent flow.

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

FunzionalitàFeatures

L'API Graph di Azure AD offre le funzionalità seguenti:Azure AD Graph API provides the following features:

  • Endpoint dell'API REST: l'API Graph di Azure AD è un servizio RESTful che include endpoint a cui viene eseguito l'accesso tramite richieste HTTP standard.REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. L'API Graph di Azure AD supporta i tipi di contenuto XML o JSON (JavaScript Object Notation) per le richieste e le risposte.Azure AD 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 di Azure AD deve essere autenticata aggiungendo un token JSON Web (JWT) nell'intestazione dell'autorizzazione della richiesta.Authentication with Azure AD: Every request to Azure AD 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 basata sui ruoli: per il controllo degli accessi in base al ruolo nell'API Graph di Azure AD vengono usati gruppi di sicurezza.Role-Based Authorization (RBAC): Security groups are used to perform RBAC in Azure AD 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: è possibile eseguire una query differenziale per tenere traccia delle modifiche apportate a una directory tra due momenti di tempo senza dover interrogare di frequente l'API Graph di Azure AD.Differential Query: Differential query allows you to track changes in a directory between two time periods without having to make frequent queries to Azure AD Graph API. 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: è possibile aggiungere proprietà personalizzate agli oggetti della directory senza dover usare un archivio dati esterno.Directory Extensions: You can add custom properties to directory objects without requiring an external data store. Se, ad esempio, 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 for use 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.
  • Protezione tramite ambiti di autorizzazione: l'API Graph di Azure AD espone gli ambiti di autorizzazione che consentono l'accesso sicuro ai dati di Azure AD tramite OAuth 2.0.Secured by permission scopes: Azure AD Graph API exposes permission scopes that enable secure access to Azure AD data using OAuth 2.0. Sono supportati diversi tipi di app client, tra cui:It supports a variety of client app types, including:

    • le interfacce utente a cui viene assegnato l'accesso delegato ai dati tramite l'autorizzazione da parte dell'utente connesso (delegato)user interfaces that are given delegated access to data via authorization from the signed-in user (delegated)
    • le applicazioni di servizio/daemon che operano in background senza un utente connesso e usano il controllo degli accessi in base al ruolo definito dall'applicazioneservice/daemon applications that operate in the background without a signed-in user being present and use application-defined role-based access control

      Entrambe le autorizzazioni basate su accesso delegato e applicazione rappresentano un privilegio esposto dall'API Graph di Azure AD e possono essere richieste dalle applicazioni client tramite le funzionalità per le autorizzazioni di registrazione delle applicazioni nel portale di Azure.Both delegated and application permissions represent a privilege exposed by the Azure AD Graph API and can be requested by client applications through application registration permissions features in the Azure portal. Gli ambiti di autorizzazione dell'API Graph di Azure AD forniscono informazioni sulle funzionalità disponibili per l'applicazione client.Azure AD Graph API Permission Scopes provides information on what's available for use by your client application.

ScenariScenarios

Gli scenari di applicazione dell'API Graph di Azure AD sono numerosi.Azure AD 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 di Azure AD, in modo che lo sviluppatore possa registrare l'applicazione a tenant singolo in Azure AD e configurare le autorizzazioni di lettura e scrittura per l'API Graph di Azure AD.This task requires access to Azure AD Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for Azure AD 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 di Azure AD.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 Azure AD 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 della directory e quindi l'applicazione deve chiamare l'API Graph di Azure AD.These features require access to directory objects, and so the application needs to call Azure AD Graph API. Lo sviluppatore registra l'applicazione in Azure AD, la configura per richiedere le autorizzazioni di lettura e scrittura per l'API Graph di Azure AD e quindi abilita l'accesso esterno in modo che altre organizzazioni possano fornire il consenso per l'uso dell'applicazione nella rispettiva directory.The developer registers the application in Azure AD, configures it to require read and write permissions for Azure AD 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 di Azure AD nella directory dell'utente.Granting consent will then give the application those requested permissions to Azure AD 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 REST Graph di Azure ADAzure AD Graph REST documentation

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