Avvio rapido per l'API Graph di Azure ADQuickstart for the Azure AD Graph API

L'API Graph di Azure Active Directory (AD) consente l'accesso a livello di codice ad Azure AD tramite endpoint dell'API REST OData.The Azure Active Directory (AD) Graph API provides programmatic access to Azure AD through OData 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, è possibile usare l'API Graph per creare un nuovo utente, visualizzare o aggiornare le proprietà dell'utente, modificare la password utente, verificare l'appartenenza ai gruppi per l'accesso basato sui ruoli e disabilitare o eliminare l'utente.For example, you can use the Graph API to create a new user, view or update user’s properties, change user’s password, check group membership for role-based access, disable, or delete the user. Per altre informazioni sulle funzionalità dell'API Graph e sugli scenari di applicazione, vedere API di Azure AD Graph e Prerequisiti dell'API di Azure AD Graph.For more information on the Graph API features and application scenarios, see Azure AD Graph API and Azure AD Graph API Prerequisites.

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.

Come creare un URL dell'API GraphHow to construct a Graph API URL

Per accedere a dati e oggetti, ovvero risorse o entità, della directory su cui eseguire operazioni CRUD, nell'API Graph è possibile usare gli URL basati sul protocollo OData (Open Data).In Graph API, to access directory data and objects (in other words, resources or entities) against which you want to perform CRUD operations, you can use URLs based on the Open Data (OData) Protocol. Gli URL usati nell'API Graph sono costituiti da quattro parti principali: radice del servizio, identificatore del tenant, percorso delle risorse e opzioni della stringa di query: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters].The URLs used in Graph API consist of four main parts: service root, tenant identifier, resource path, and query string options: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters]. Considerare questo URL di esempio: https://graph.windows.net/contoso.com/groups?api-version=1.6.Take the example of the following URL: https://graph.windows.net/contoso.com/groups?api-version=1.6.

  • Radice del servizio: nell'API Graph di Azure AD la radice del servizio è sempre https://graph.windows.net.Service Root: In Azure AD Graph API, the service root is always https://graph.windows.net.
  • Identificatore del tenant: questa sezione può corrispondere a un nome di dominio (registrato) verificato, come contoso.com nell'esempio precedente. Può anche essere un ID di oggetto tenant o l'alias "myorganization" o "me".Tenant identifier: This section can be a verified (registered) domain name, in the preceding example, contoso.com. It can also be a tenant object ID or the “myorganization” or “me” alias. Per altre informazioni, vedere Indirizzamento delle entità e delle operazioni nell'API Graph.For more information, see Addressing Entities and Operations in the Graph API).
  • Percorso della risorsa: questa sezione di URL identifica la risorsa con cui interagire (utenti, gruppi, un determinato utente o un gruppo specifico e così via). Nell'esempio sopra è l'elemento "groups" di livello principale a risolvere il set di risorse.Resource path: This section of a URL identifies the resource to be interacted with (users, groups, a particular user, or a particular group, etc.) In the example above, it is the top level “groups” to address that resource set. È anche possibile risolvere un'entità specifica, ad esempio "users/{objectId}" o "users/userPrincipalName".You can also address a specific entity, for example “users/{objectId}” or “users/userPrincipalName”.
  • Parametri di query: un punto interrogativo (?) separa la sezione relativa al percorso delle risorse da quella dei parametri di query.Query parameters: A question mark (?) separates the resource path section from the query parameters section. Il parametro di query "api-version" è obbligatorio in tutte le richieste nell'API Graph.The “api-version” query parameter is required on all requests in the Graph API. L'API Graph supporta anche le seguenti opzioni di query OData: $filter, $orderby, $expand, $top e $format.The Graph API also supports the following OData query options: $filter, $orderby, $expand, $top, and $format. Le opzioni di query seguenti non sono attualmente supportate: $count, $inlinecount e $skip.The following query options are not currently supported: $count, $inlinecount, and $skip. Per altre informazioni, vedere Query, opzioni di paging e filtri supportati nell'API Graph di Azure AD.For more information, see Supported Queries, Filters, and Paging Options in Azure AD Graph API.

Versioni dell'API GraphGraph API versions

È possibile specificare la versione per una richiesta all'API Graph nel parametro di query "api-version".You specify the version for a Graph API request in the “api-version” query parameter. Per la versione 1.5 e successive, usare un valore di versione numerico: api-version=1.6.For version 1.5 and later, you use a numerical version value; api-version=1.6. Per le versioni precedenti, si usa una stringa di data che rispetta il formato AAAA-MM-GG, ad esempio api-version=2013-11-08.For earlier versions, you use a date string that adheres to the format YYYY-MM-DD; for example, api-version=2013-11-08. Per le funzionalità di anteprima, usare la stringa "beta", ad esempio api-version=beta.For preview features, use the string “beta”; for example, api-version=beta. Per altre informazioni sulle differenze tra le versioni dell'API Graph, vedere Controllo delle versioni dell'API di Azure AD Graph.For more information about differences between Graph API versions, see Azure AD Graph API Versioning.

Metadati dell'API GraphGraph API metadata

Per restituire il file di metadati dell'API Graph, aggiungere il segmento "$metadata" dopo l'identificatore tenant nell'URL. Ad esempio, questo URL restituisce i metadati per una società demo: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6.To return the Graph API metadata file, add the “$metadata” segment after the tenant-identifier in the URL For example, the following URL returns metadata for a demo company: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6. È possibile immettere l'URL nella barra degli indirizzi di un Web browser per visualizzare i metadati.You can enter this URL in the address bar of a web browser to see the metadata. Il documento di metadati CSDL restituito descrive le entità e tipi complessi, le rispettive proprietà e le funzioni e le azioni esposte dalla versione dell'API Graph richiesta.The CSDL metadata document returned describes the entities and complex types, their properties, and the functions and actions exposed by the version of Graph API you requested. Se si omette il parametro api-version, vengono restituiti i metadati per la versione più recente.Omitting the api-version parameter returns metadata for the most recent version.

Query comuniCommon queries

Query comuni dell'API Graph di Azure AD elenca le query comuni che è possibile usare con l'API Graph di Azure AD, incluse quelle per accedere alle risorse di livello principale nella directory e le query per eseguire operazioni nella directory.Azure AD Graph API Common Queries lists common queries that can be used with the Azure AD Graph, including queries that can be used to access top-level resources in your directory and queries to perform operations in your directory.

Ad esempio, https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 restituisce informazioni sulla società per la directory contoso.com.For example, https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 returns company information for directory contoso.com.

In alternativa, https://graph.windows.net/contoso.com/users?api-version=1.6 elenca tutti gli oggetti utente presenti nella directory contoso.com.Or https://graph.windows.net/contoso.com/users?api-version=1.6 lists all user objects in the directory contoso.com.

Uso di Esplora graficoUsing the Graph Explorer

È possibile usare Esplora grafico per l'API Graph di Azure AD per eseguire query sui dati di directory durante la creazione dell'applicazione.You can use the Graph Explorer for the Azure AD Graph API to query the directory data as you build your application.

Di seguito è riportato l'output che viene visualizzato se si passa a Graph explorer, si accede e si immette https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 per visualizzare tutti gli utenti nella directory dell'utente connesso:The following is the output you would see if you were to navigate to the Graph Explorer, sign in, and enter https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 to display all the users in the signed-in user's directory:

API Graph di Azure AD explorer

Caricare Graph explorer: per caricare lo strumento, passare a https://graphexplorer.azurewebsites.net/.Load the Graph Explorer: To load the tool, navigate to https://graphexplorer.azurewebsites.net/. Fare clic su Accedi ed effettuare l'accesso con le credenziali dell'account Azure AD per eseguire Graph explorer sul tenant.Click Login and sign-in with your Azure AD account credentials to run the Graph Explorer against your tenant. Se si esegue Graph explorer nel proprio tenant, l'utente o l'amministratore devono acconsentire in fase di accesso.If you run Graph Explorer against your own tenant, either you or your administrator needs to consent during sign-in. Se si ha una sottoscrizione di Office 365, si ha automaticamente un tenant di Azure AD.If you have an Office 365 subscription, you automatically have an Azure AD tenant. Le credenziali usate per accedere a Office 365 sono, in realtà, account di Azure AD ed è possibile usare tali credenziali con Esplora grafico.The credentials you use to sign in to Office 365 are, in fact, Azure AD accounts, and you can use these credentials with Graph Explorer.

Eseguire una query: per eseguire una query, digitarla nell'apposita casella di richiesta e fare clic su OTTIENI oppure premere il tasto INVIO.Run a query: To run a query, type your query in the request text box and click GET or click the enter key. I risultati vengono visualizzati nella casella delle risposte.The results are displayed in the response box. https://graph.windows.net/myorganization/groups?api-version=1.6 elenca ad esempio tutti gli oggetti gruppo nella directory dell'utente connesso.For example, https://graph.windows.net/myorganization/groups?api-version=1.6 lists all group objects in the signed-in user's directory.

Si notino le limitazioni e le funzioni dello strumento Esplora grafico riportate di seguito:Note the following features and limitations of the Graph Explorer:

  • Funzionalità di completamento automatico in set di risorse.Autocomplete capability on resource sets. Per visualizzarla, fare clic sulla casella di richiesta (dove viene visualizzato l'URL della società).To see this functionality, click on the request text box (where the company URL appears). È possibile selezionare un set di risorse dall'elenco a discesa.You can select a resource set from the dropdown list.
  • Supporta gli alias di indirizzamento "me" e "myorganization".Supports the “me” and “myorganization” addressing aliases. Ad esempio, è possibile usare https://graph.windows.net/me?api-version=1.6 per restituire l'oggetto utente dell'utente che ha effettuato l'accesso oppure https://graph.windows.net/myorganization/users?api-version=1.6 per restituire tutti gli utenti nella directory corrente.For example, you can use https://graph.windows.net/me?api-version=1.6 to return the user object of the signed-in user or https://graph.windows.net/myorganization/users?api-version=1.6 to return all users in the current directory.
  • Una sezione di intestazioni di risposta.A response headers section. Questa sezione può essere usata per consentire la risoluzione dei problemi che si verificano durante l'esecuzione di query.This section can be used to help troubleshoot issues that occur when running queries.
  • Un visualizzatore JSON per la risposta con funzionalità di espansione e compressione.A JSON viewer for the response with expand and collapse capabilities.
  • Nessun supporto per la visualizzazione di una foto di anteprima.No support for displaying a thumbnail photo.

Uso di Fiddler per scrivere nella directoryUsing Fiddler to write to the directory

Ai fini di questa guida rapida, è possibile usare il debugger Web Fiddler per esercitarsi a eseguire operazioni di scrittura sulla directory di Azure AD.For the purposes of this Quickstart guide, you can use the Fiddler Web Debugger to practice performing ‘write’ operations against your Azure AD directory. Per altre informazioni e per l'installazione di Fiddler, vedere http://www.telerik.com/fiddler.For more information and to install Fiddler, see http://www.telerik.com/fiddler.

L'esempio seguente usa il debugger Web Fiddler per creare un nuovo gruppo di sicurezza "MyTestGroup" nella directory di Azure AD.In the example below, you use Fiddler Web Debugger to create a new security group ‘MyTestGroup’ in your Azure AD directory.

Ottenere un token di accesso: per accedere ad Azure AD Graph, è necessario che i client vengano prima correttamente autenticati in Azure AD.Obtain an access token: To access Azure AD Graph, clients are required to successfully authenticate to Azure AD first. Per altre informazioni, vedere Scenari di autenticazione per Azure AD.For more information, see Authentication Scenarios for Azure AD.

Creare ed eseguire una query: completare i passaggi seguenti.Compose and run a query: Complete the following steps:

  1. Aprire il debugger Web Fiddler e passare alla scheda Composer .Open Fiddler Web Debugger and switch to the Composer tab.
  2. Poiché si desidera creare un nuovo gruppo di sicurezza, scegliere Post come metodo HTTP dal menu a discesa.Since you want to create a new security group, select Post as the HTTP method from the pull-down menu. Per altre informazioni sulle operazioni e le autorizzazioni per un oggetto gruppo, vedere Gruppo in Riferimento all'API REST Graph di Azure AD.For more information about operations and permissions on a group object, see Group within the Azure AD Graph REST API Reference.
  3. Nel campo accanto a Post, come URL della richiesta, digitare: https://graph.windows.net/mytenantdomain/groups?api-version=1.6.In the field next to Post, type in the following as the request URL: https://graph.windows.net/mytenantdomain/groups?api-version=1.6.

    Nota

    È necessario sostituire mytenantdomain con il nome di dominio della directory di Azure AD.You must substitute mytenantdomain with the domain name of your own Azure AD directory.

  4. Nel campo appena sotto il menu a discesa Post digitare:In the field directly below Post pull-down, type the following:

    Host: graph.windows.net
    Authorization: Bearer <your access token>
    Content-Type: application/json
    

    Nota

    Sostituire il <token di accesso> con il token di accesso per la directory di Azure AD.Substitute your <your access token> with the access token for your Azure AD directory.

  5. Nel campo del corpo della richiesta digitare quanto segue:In the Request body field, type the following:

        {
            "displayName":"MyTestGroup",
            "mailNickname":"MyTestGroup",
            "mailEnabled":"false",
            "securityEnabled": true
        }
    

    Per altre informazioni sulla creazione di gruppi, vedere Crea gruppo.For more information about creating groups, see Create Group.

Per altre informazioni sulle entità e i tipi di Azure AD esposti da Graph e sulle operazioni che è possibile eseguirvi con Graph, vedere Riferimento all'API REST Graph di Azure AD.For more information on Azure AD entities and types that are exposed by Graph and information about the operations that can be performed on them with Graph, see Azure AD Graph REST API Reference.

Passaggi successiviNext steps