Controllo delle versioni | Concetti relativi all'API Graph
Si applica a: API Graph | Azure Active Directory (AD)
Questo argomento riepiloga le differenze tra le versioni per le entità e le operazioni dell'API Graph di Azure Active Directory (AD). È necessario specificare la versione di un'operazione da usare includendo il parametro della stringa di query api-version nella richiesta. Le richieste senza un parametro api-version verranno rifiutate e verrà restituita una risposta (400) Richiesta non valida. Se tramite il servizio viene chiamata una versione precedente di un'operazione, è possibile scegliere di continuare a chiamare tale versione precedente o modificare il codice in modo che venga chiamata una versione più recente. Eventuali differenze nelle funzionalità tra le versioni sono descritte nella documentazione per l'entità su cui si sta eseguendo la chiamata.
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.
A partire dall'API di Azure AD Graph versione 1.5, il valore del parametro api-version per le versioni GA (General Availability) viene specificato come valore numerico. L'URL seguente mostra come eseguire una query sulle risorse di livello superiore per il dominio tenant contoso.com usando l'API Graph versione 1.5: https://graph.windows.net/contoso.com?api-version=1.5. Per le versioni precedenti dell'API Graph, il valore del parametro api-version viene specificato come stringa di data nel formato seguente: AAA-MM-GG. L'URL seguente mostra come eseguire una query sulle risorse di livello superiore dello stesso tenant usando la versione 2013-11-08 dell'API Graph: https://graph.windows.net/contoso.com?api-version=2013-11-08. Per le funzionalità di anteprima, il valore del parametroapi-version viene specificato usando la stringa "beta" come mostrato di seguito: https://graph.windows.net/contoso.com?api-version=beta.
Contratto API, controllo delle versioni e modifiche di rilievo
Il numero della versione dell'API verrà incrementato per qualsiasi modifica di rilevo all'API, per proteggere le applicazioni client. È possibile che venga deciso di incrementare la versione dell'API anche per modifiche non di rilevo, ad esempio in caso di aggiunta di alcune nuove capacità di portata significativa.
Cosa si intende per modifica di rilievo?
- Rimozione o ridenominazione delle API o dei relativi parametri
- Modifiche di comportamento per un'API esistente
- Modifiche dei codici di errore e contratti relativi ai malfunzionamenti
- Qualunque variazione che possa costituire una violazione del principio della minor sorpresa (Principal of Least Astonishment)
Nota: l'aggiunta di nuovi campi JSON alle risposte non costituisce una modifica di rilievo. Per gli sviluppatori che generano proxy client (come i client WCF), la linea guida prescrive che le applicazioni client siano pronte per ricevere proprietà e tipi derivati non definiti precedentemente dal servizio API Graph. Anche se l'API Graph non è ancora conforme a OData V4 al momento della redazione del presente documento, seguirà le linee guida descritte nella sezione dedicata al controllo delle versioni nella specifica OData V4.
Quando viene incrementata la versione principale dell'API, ad esempio da 1.5 a 2.0, significa che il supporto per i client esistenti che usano le versioni 1.x o precedenti verrà deprecato e non sarà più disponibile dopo 12 mesi. Per informazioni dettagliate, vedere Criteri relativi al ciclo di vita del supporto per Microsoft Online Services.
Versioni supportate
Per l'API Graph sono state rilasciate le versioni seguenti.
Versione beta
Le funzionalità dell'API Graph attualmente in anteprima sono specificate nella sezione Funzionalità in anteprima dei concetti relativi all'API Graph oppure nel blog del team di Graph. Le funzionalità beta richiedono il parametro di stringa di query "api-version=beta". Quando il team dell'API Graph riterrà che una funzionalità di anteprima è pronta per la fase GA, la funzionalità verrà aggiunta alla versione GA più recente. Se costituisce una modifica di rilievo, verrà usato un nuovo numero di versione incrementato. Non è garantito che una funzionalità di anteprima verrà promossa alla fase GA.
Per la versione beta, verranno evitate per quanto possibile le modifiche di rilievo, ma non è possibile rilasciare garanzie in merito. Per le applicazioni client che usano la versione beta sono previste saltuarie modifiche di rilievo. Vedere le condizioni per l'utilizzo aggiuntive per le anteprime di Microsoft Azure.
Versione 1.6
Questa sezione elenca le modifiche per l'API Graph versione 1.6.
Con l'API Graph versione 1.6 vengono introdotte le modifiche di funzionalità seguenti:
Aggiunta del supporto per gli utenti account locale di Azure Active Directory B2C. Sono incluse le nuove proprietà nell'entità User e un nuovo tipo complesso SignInName per supportare l'accesso con l'account locale ai tenant di Azure Active Directory B2C. Per altre informazioni su Azure Active Directory B2C, vedere Documentazione su Azure Active Directory B2C.
Aggiunta del supporto per l'individuazione del servizio con l'entità ServiceEndpoint e la proprietà di navigazione serviceEndpoints nelle entità Application e ServicePrincipal.
Aggiunta del supporto per il comportamento dell'app personalizzata che può essere richiamato usando servizi con i tipi AddIn e KeyValue e la proprietà addIns nelle entità Application e ServicePrincipal.
Aggiunta del supporto per l'autenticazione senza password con l'entità TrustedCAsForPasswordlessAuth, il tipo CertificateAuthorityInformation e la proprietà trustedCAsForPasswordlessAuth dell'entità TenantDetail.
Aggiunta dell'azione changePassword, che può essere chiamata per consentire all'utente connesso di cambiare la password.
Le versioni del client Graph 2.1.x richiedono la versione dell'API Graph 1.6; le versioni del client Graph 2.0.x richiedono l'API Graph 1.5.
Modifiche alle entità
| Entità | Descrizione della modifica |
|---|---|
| Application | Aggiunta della proprietà addIns, che definisce il comportamento personalizzato che un servizio può usare per chiamare un'app in contesti specifici. Aggiunta della proprietà di navigazione serviceEndpoints, che contiene la raccolta di endpoint del servizio che sono disponibili per l'individuazione. |
| LicenseDetail | Nuova entità che contiene i dettagli di licenza per un utente. |
| ServiceEndpoint | Nuova entità che contiene informazioni sull'individuazione dei servizi. |
| ServicePrincipal | Aggiunta della proprietà addIns, che definisce il comportamento personalizzato che un servizio può usare per chiamare un'app in contesti specifici. Aggiunta della proprietà di navigazione serviceEndpoints, che contiene la raccolta di endpoint del servizio che sono disponibili per l'individuazione. |
| SubscribedSku | Aggiunta della proprietà appliesTo. |
| TenantDetail | Aggiunta della proprietà trustedCAsForPasswordlessAuth, che contiene il set di autorità di certificazione usate per convalidare la catena di certificati durante l'esecuzione dell'autenticazione senza password. |
| TrustedCAsForPasswordlessAuth | Nuova entità che rappresenta un set di autorità di certificazione per convalidare la catena di certificati durante l'esecuzione dell'autenticazione senza password. |
| User | Aggiunta della proprietà creationType, che viene usata per indicare che l'utente sia un account locale. Aggiunta della proprietà signInNames, che contiene la raccolta di nomi di accesso di accesso usati da un utente account locale per accedere a un tenant di Azure Active Directory B2C. Questa proprietà è stata rinominata da alternativeSignInNamesInfo nella versione beta. Aggiunta della proprietà di navigazione licenseDetails. |
Modifiche ai tipi complessi
| Tipo | Descrizione della modifica |
|---|---|
| AddIn | Nuovo tipo usato per definire il comportamento personalizzato che un servizio può usare per chiamare un'app in contesti specifici. |
| CertificateAuthorityInformation | Nuovo tipo che rappresenta un'autorità di certificazione usata per convalidare la catena di certificati durante l'esecuzione dell'autenticazione senza password. |
| KeyValue | Nuovo tipo contenente una coppia chiave-valore che definisce un parametro che un servizio consumer può usare o chiamare in un'applicazione specificata in un tipo AddIn. |
| ServicePlanInfo | Aggiunta della proprietà appliesTo. Aggiunta della proprietà provisioningStatus. |
| SignInName | Nuovo tipo che contiene informazioni su un nome di accesso che può essere usato da un utente account locale per accedere a un tenant di Azure Active Directory B2C. Questo tipo è stato rinominato da LogonIdentifier nella versione beta. |
Modifiche alle azioni e alle funzioni
| Funzione | Descrizione della modifica |
|---|---|
| changePassword | Nuova azione che può essere chiamata per consentire all'utente connesso di cambiare la password. |
Versione 1.5
Questa sezione elenca le modifiche per l'API Graph versione 1.5.
Con l'API Graph versione 1.5 vengono introdotte le modifiche di funzionalità seguenti:
Lo spazio dei nomi dello schema dell'API Graph è stato modificato da Microsoft.WindowsAzure.ActiveDirectory a Microsoft.DirectoryServices. Ciò influisce su tutti i tipi complessi e le entità esposti dall'API Graph.
È stato aggiunto il supporto per le estensioni dello schema di directory. Ciò consente di aggiungere le proprietà richieste dall'applicazione agli oggetti directory. Le entità seguenti supportano le estensioni dello schema: User, Group, TenantDetail, Device, Application e ServicePrincipal. Per supportare le estensioni dello schema di directory è stata aggiunta l'entità ExtensionProperty, è stata aggiunta la proprietà di navigazione extensionProperties all'entità Application ed è stata aggiunta una nuova funzione, getAvailableExtensionProperties, che restituisce le proprietà di estensione registrate degli oggetti directory supportati. Per altre informazioni sull'estensione dello schema di directory, vedere Estensioni dello schema di directory.
Il modo in cui vengono rappresentate le autorizzazioni è stato modificato ed è maggiormente allineato con i concetti OAuth 2.0 e con il modo in cui vengono rappresentate le autorizzazioni in altri componenti di Azure. L'entità Permission è stata rimossa e sostituita con l'entità OAuth2PermissionGrant. Questa entità rappresenta gli ambiti delle autorizzazioni delegate OAuth 2.0 che vengono recapitati in un'attestazione di ambito nel token di accesso OAuth 2.0. La nuova entità AppRoleAssignment rappresenta anche i ruoli applicazione che possono essere assegnati a utenti, gruppi ed entità servizio. Sono stati aggiunti anche due tipi complessi correlati: AppRole e OAuth2Permission. Questa modifica ha comportato la ridenominazione di alcune proprietà e l'aggiunta di altre nelle entità seguenti: Application, Group, ServicePrincipal e User.
L'entità Role è stata rinominata DirectoryRole.
L'entità RoleTemplate è stata rinominata DirectoryRoleTemplate.
Le tabelle seguenti elencano entità, tipi complessi e funzioni che sono stati aggiunti, modificati o rimossi per questa versione.
Modifiche alle entità
| Entità | Descrizione della modifica |
|---|---|
| Application | Aggiornamento della proprietà appId da Edm.Guid a Edm.String. Aggiunta della proprietà appRoles, che contiene la raccolta di ruoli applicazione che un'applicazione può dichiarare. Questi ruoli possono essere assegnati a utenti, gruppi o entità servizio. Aggiunta della proprietà groupMembershipClaims, una maschera di bit che configura l'attestazione "groups" rilasciata in un token di accesso OAuth 2.0 o utente e prevista dall'applicazione. I valori della maschera di bit sono: 0: Nessuno, 1: Gruppi di sicurezza e ruoli di Azure AD, 2: Riservato e 4: Riservato. Impostando la maschera di bit su 7, è possibile ottenere tutti i gruppi di sicurezza, i gruppi di distribuzione e i ruoli di Azure AD di cui l'utente connesso è membro. Aggiunta della proprietà knownClientApplications, che contiene un elenco delle applicazioni client associate all'applicazione della risorsa. Il consenso per le applicazioni client note comporterà il consenso implicito per l'applicazione della risorsa tramite una finestra di dialogo di consenso combinata (che mostra gli ambiti di autorizzazione OAuth richiesti dal client e dalla risorsa). Aggiunta della proprietà oauth2AllowImplicitFlow, che specifica se l'applicazione Web può richiedere token di flusso OAuth2.0 impliciti. Il valore predefinito è false. Aggiunta della proprietà oauth2AllowUrlPathMatching, che specifica se, come parte delle richieste dei token OAuth 2.0, Azure AD consentirà la ricerca della corrispondenza del percorso dell'URI di reindirizzamento in base all'oggetto replyUrls dell'applicazione. Il valore predefinito è false. Aggiunta della proprietà oauth2Permissions, che contiene la raccolta di ambiti di autorizzazione OAuth 2.0 che l'applicazione dell'API Web (risorsa) espone alle applicazioni client. Questi ambiti di autorizzazione possono essere concessi alle applicazioni client durante il consenso. Aggiunta della proprietà oauth2RequiredPostResponse, che specifica se, come parte delle richieste dei token OAuth 2.0, Azure AD consentirà le richieste POST, in opposizione alle richieste GET. Il valore predefinito è false, che specifica che sono consentite solo le richieste GET. Aggiunta della proprietà requiredResourceAccess, che specifica le risorse a cui l'applicazione richiede l'accesso e il set di ruoli applicazione e ambiti di autorizzazione OAuth necessari per ogni risorsa. Questa pre-configurazione dell'accesso alle risorse richieste è alla base dell'esperienza di consenso dell'utente finale. Aggiunta della proprietà di navigazione extensionProperties che contiene le proprietà estensione associate all'applicazione. |
| AppRoleAssignment | Nuova entità usata per registrare quando un utente o un gruppo viene assegnato a un'applicazione. In questo caso, verrà visualizzato un riquadro dell'applicazione nel pannello di accesso dell'app dell'utente. Questa entità può anche essere usata per concedere a un'altra applicazione (modellata come entità servizio) l'accesso a un'applicazione della risorsa in un ruolo specifico. |
| Contact | Aggiunta della proprietà sipProxyAddress, che specifica l'indirizzo SIP (Session Initiation Protocol) VoIP (Voice over IP) del contatto. |
| DirectoryObject | Aggiunta della proprietà deletionTimestamp, che indica l'ora in cui è stato eliminato un oggetto directory. Si applica solo agli oggetti directory che possono essere ripristinati. Attualmente è supportata solo per Application. |
| DirectoryRole | Ridenominazione da Role. Aggiunta della proprietà roleTemplateId |
| DirectoryRoleTemplate | Ridenominazione da RoleTemplate. |
| ExtensionProperty | Nuova entità che consente a un'applicazione di definire e usare un set di proprietà aggiuntive che possono essere aggiunte agli oggetti directory (utenti, gruppi, dettagli del tenant, dispositivi, applicazioni ed entità servizio) senza che l'applicazione richieda un archivio dati esterno. |
| Group | Aggiunta della proprietà onPremisesSecurityIdentifier, che contiene l'ID di sicurezza locale (SID) per il gruppo sincronizzato dall'ambiente locale al cloud. Aggiunta della proprietà di navigazione appRoleAssignments, che fa riferimento al set di applicazioni (entità servizio) a cui il gruppo è assegnato. |
| OAuth2PermissionGrant | Nuova entità che specifica un ambito delle autorizzazioni delegate OAuth2.0. L'ambito di autorizzazione deleagata OAuth specificato può essere richiesto dalle applicazioni client (con la raccolta requiredResourceAccess) che chiamano l'applicazione della risorsa. Sostituisce l'entità Permission che è stata rimossa da questa versione. |
| Permission | Ridenominazione in OAuth2PermissionGrant. |
| Ruolo | Ridenominazione in DirectoryRole. |
| RoleTemplate | Ridenominazione in DirectoryRoleTemplate. |
| ServicePrincipal | Aggiunta della proprietà appDisplayName, che specifica il nome visualizzato esposto dall'applicazione associata. Aggiunta della proprietà appRoleAssignmentRequired, che specifica se è necessario un oggetto AppRoleAssignment per un utente o un gruppo prima che Azure AD emetta un token di accesso o utente per l'applicazione. Aggiunta della proprietà appRoles, che contiene i ruoli applicazione esposti dall'applicazione associata. Per altre informazioni, vedere la definizione della proprietà appRoles nell'entità Application. Aggiunta della proprietà oauth2Permissions, che contiene le autorizzazioni OAuth 2.0 esposte dall'applicazione associata. Per altre informazioni, vedere la definizione della proprietà oauth2Permisions nell'entità Application. Aggiunta della proprietà preferredTokenSigningKeyThumbprint. Riservata solo per uso interno. Non scrivere né fare in altro modo affidamento su questa proprietà. Potrebbe essere rimossa nelle versioni future. Aggiunta della proprietà di navigazione appRoleAssignedTo, che fa riferimento al set di applicazioni a cui l'entità servizio è assegnata. Aggiunta della proprietà di navigazione appRoleAssignments, che fa riferimento al set di entità (utenti, gruppi ed entità servizio) assegnati all'entità servizio. Aggiunta della proprietà di navigazione oauth2PermissionGrants, che fa riferimento al set di autorizzazioni di rappresentazione utente associate all'entità servizio. Rimozione della proprietà di navigazione permissions |
| TenantDetail | Rimozione della proprietà tenantType. |
| User | Aggiunta della proprietà onPremisesSecurityIdentifier, che contiene l'ID di sicurezza locale (SID) per l'utente sincronizzato dall'ambiente locale al cloud. Aggiunta della proprietà sipProxyAddress, che specifica l'indirizzo SIP (Session Initiation Protocol) VoIP (Voice over IP) dell'utente. Aggiunta della proprietà di navigazione appRoleAssignments, che fa riferimento al set di applicazioni (entità servizio) a cui questo utente è assegnato. Aggiunta della proprietà di navigazione oauth2PermissionGrants, che fa riferimento al set di autorizzazioni di rappresentazione utente OAuth 2.0 associate a questo utente. Rimozione della proprietà di navigazione permissions. |
Modifiche ai tipi complessi
| Tipo | Descrizione della modifica |
|---|---|
| AppRole | Nuovo tipo che specifica i ruoli applicazione che potrebbero essere richiesti dalle applicazioni client che chiamano l'applicazione o che potrebbero venire usati per assegnare l'applicazione a utenti o gruppi in uno dei ruoli applicazione specificati. |
| OAuth2Permission | Nuovo tipo che rappresenta un ambito di autorizzazione OAuth 2.0. L'ambito di autorizzazione OAuth 2.0 specificato può essere richiesto dalle applicazioni client (con la raccolta requiredResourceAccess) che chiamano l'applicazione della risorsa. |
| RequiredResourceAccess | Nuovo tipo che specifica il set di ambiti di autorizzazione OAuth 2.0 e i ruoli app nella risorsa specificata a cui l'applicazione richiede l'accesso. |
| ResourceAccess | Nuovo tipo che rappresenta un'autorizzazione richiesta dall'applicazione. |
Modifiche alle azioni e alle funzioni
| Funzione | Descrizione della modifica |
|---|---|
| getAvailableExtensionProperties | Nuova funzione che restituisce l'elenco completo delle proprietà di estensione che sono state registrate in una directory. Le proprietà di estensione possono essere registrate per le entità seguenti: User, Group, Device, TenantDetail, Application e ServicePrincipal. |
| getMemberObjects | Nuova funzione che restituisce tutti gli oggetti Group e DirectoryRole di cui un utente, un contatto, un gruppo o un'entità servizio è membro in modo transitivo. |
| getObjectsByObjectIds | Nuova funzione che restituisce gli oggetti directory specificati in un elenco di ID oggetto. È anche possibile indicare le raccolte di risorse, ad esempio utenti, gruppi e così via, da cercare specificando il parametro types facoltativo. |
| restore | Nuova azione di servizio che consente di ripristinare un'applicazione eliminata. |
Versione 08-11-2013
Questa sezione elenca le modifiche per l'API Graph versione 2013-11-08.
Le tabelle seguenti elencano entità, tipi complessi e funzioni che sono stati aggiunti, modificati o rimossi per questa versione.
Modifiche alle entità
| Entità | Descrizione della modifica |
|---|---|
| Application | Aggiunta della proprietà di navigazione owners, che fa riferimento al set di oggetti directory proprietari dell'applicazione. I proprietari sono un set di utenti non amministratori a cui è consentito modificare questo oggetto. Ereditata da DirectoryObject. |
| DeviceConfiguration | Nuova entità che rappresenta la configurazione per un dispositivo. |
| DirectoryObject | Aggiunta della proprietà di navigazione createdOnBehalfOf, che fa riferimento all'oggetto directory per conto del quale è stato creato questo oggetto. Aggiunta della proprietà di navigazione createdObjects, che fa riferimento al set di oggetti directory creati dall'oggetto corrente. Aggiunta della proprietà di navigazione owners, che fa riferimento al set di oggetti directory proprietari dell'oggetto corrente. I proprietari sono un set di utenti non amministratori a cui è consentito modificare questo oggetto. Aggiunta della proprietà di navigazione ownedObjects, che fa riferimento al set di oggetti directory di proprietà dell'oggetto corrente. Importante: le entità che derivano da DirectoryObject ereditano le relative proprietà e possono ereditarne le proprietà di navigazione. |
| Group | Aggiunta della proprietà di navigazione owners, che fa riferimento al set di oggetti directory proprietari del gruppo. I proprietari sono un set di utenti non amministratori a cui è consentito modificare questo oggetto. Ereditata da DirectoryObject. |
| Ruolo | Aggiunta della proprietà di navigazione ownedObjects, che fa riferimento al set di oggetti directory di proprietà del ruolo. Ereditata da DirectoryObject. L'entità Role è stata rinominata DirectoryRole a partire dalla versione 1.5. Per altre informazioni sull'entità Role, vedere DirectoryRole. |
| ServicePrincipal | Aggiunta della proprietà appOwnerTenantID. Aggiunta della proprietà authenticationPolicy. Riservata solo per uso interno. Non utilizzare. Rimossa nella versione 1.5. Aggiunta della proprietà di navigazione createdObjects, che fa riferimento al set di oggetti directory creati dall'entità servizio. Ereditata da DirectoryObject. Aggiunta della proprietà di navigazione owners, che fa riferimento al set di oggetti directory proprietari dell'entità servizio. I proprietari sono un set di utenti non amministratori a cui è consentito modificare questo oggetto. Ereditata da DirectoryObject. Aggiunta della proprietà di navigazione ownedObjects, che fa riferimento al set di oggetti directory di proprietà dell'entità servizio. Ereditata da DirectoryObject. |
| User | Aggiunta della proprietà immutableId, che associa un account utente di Active Directory locale al relativo oggetto utente di Azure AD. È necessario specificare questa proprietà quando si crea un nuovo account utente in Graph usando un dominio federato per la proprietà userPrincipalName (UPN) dell'utente. Aggiunta della proprietà userType, che è un valore stringa che può essere usato per classificare i tipi di utente nella directory, ad esempio "Member" e "Guest". Aggiunta della proprietà di navigazione createdObjects, che fa riferimento al set di oggetti directory creati dall'utente. Ereditata da DirectoryObject. Aggiunta della proprietà di navigazione ownedObjects, che fa riferimento al set di oggetti directory di proprietà dell'utente. Ereditata da DirectoryObject. |
Modifiche ai tipi complessi
| Tipo | Descrizione della modifica |
|---|---|
| ServicePrincipalAuthenticationPolicy | Riservata solo per uso interno. Non utilizzare. Rimossa nella versione 1.5. |
Modifiche alle azioni e alle funzioni
| Funzione | Descrizione della modifica |
|---|---|
| assignLicense | Nuova azione di servizio che consente di aggiornare un utente con un elenco di licenze da aggiungere e/o rimuovere. |
Versione 05-04-2013
Si tratta della versione di base dell'API Graph.
Risorse aggiuntive
- Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph)