Table of contents

Contrôle de version | Concepts de l’API Graph

Bryan Lamos|Dernière mise à jour: 07/09/2016
|
1 Contributeur

S’applique à : API Graph | Azure Active Directory (AD)

Cette rubrique offre un aperçu des différences de version pour les entités et les opérations de l’API Azure Active Directory (AD) Graph. Vous devez spécifier la version de l’opération à utiliser en incluant le paramètre de chaîne de requête api-version dans votre demande. Les demandes sans paramètre api-version sont rejetées et renvoient une réponse Demande incorrecte (400). Si votre service appelle une version antérieure d’une opération, vous pouvez choisir de continuer d’appeler la version antérieure, ou bien modifier votre code pour appeler une version plus récente. Les différences de fonctionnalités entre les versions sont décrites dans la documentation pour l’entité sur laquelle vous effectuez l’appel.

Important

La fonctionnalité d’API Azure AD Graph est également disponible au moyen de Microsoft Graph, une API unifiée qui intègre aussi des API d’autres services Microsoft tels que Outlook, OneDrive, OneNote, Planner et Office Graph, tous accessibles par le biais d’un seul point de terminaison à l’aide d’un seul jeton d’accès.

À partir de la version 1.5 de l’API Azure AD Graph, la valeur du paramètre api-version est spécifiée en tant que valeur numérique pour les versions mises à la disposition générale. L’URL suivante montre comment interroger les ressources de niveau supérieur pour le domaine de locataire contoso.com en utilisant la version 1.5 de l’API Graph :https://graph.windows.net/contoso.com?api-version=1.5. Pour les versions précédentes de l’API Graph, la valeur du paramètre api-version est indiquée en tant que chaîne de date au format suivant : AAAA-MM-JJ. L’URL suivante montre comment interroger les ressources de niveau supérieur du même locataire à l’aide de la version 2013-11-08 de l’API Graph : https://graph.windows.net/contoso.com?api-version=2013-11-08. Pour les fonctionnalités en version préliminaire, la valeur du paramètre api-version est spécifiée à l’aide de la chaîne « beta » comme suit : https://graph.windows.net/contoso.com?api-version=beta.

Contrat, contrôle de version et modifications avec rupture des API

Nous incrémenterons le numéro de version des API pour toutes les modifications avec rupture afin de protéger les applications clientes. Nous pourrons également choisir d’incrémenter la version d’API pour les modifications sans rupture (par exemple, si nous ajoutons des fonctionnalités importantes).

Ainsi, en quoi consiste une modification avec rupture ?

  • Suppression ou changement de nom des API ou paramètres d’API
  • Changements de comportement d’API existantes
  • Changements de codes d’erreur et de contrats d’erreurs
  • Tout ce qui violerait le principe de moindre surprise.

Remarque : l’ajout de nouveaux champs JSON aux réponses ne constitue pas une modification avec rupture. Pour les développeurs qui génèrent leurs propres proxys clients (tels que des clients WCF), notre conseil est que vos applications clientes doivent être prêtes à recevoir les propriétés et les types dérivés non définis précédemment par le service de l’API graphique. Bien que l’API Graph ne soit pas encore conforme à la norme OData V4 au moment de la rédaction de ce document, elle suit toujours les instructions de la section Model Versioning dans la spécification OData V4.

Lorsque nous incrémentons la version majeure de l’API (par exemple, de 1.5 à 2.0), nous signalons que toute prise en charge de clients existants utilisant la version 1.x ou des versions antérieures est déconseillée et cessera d’être prise en charge après 12 mois. Pour plus d’informations, consultez Politique de support Microsoft applicable aux services en ligne.

Versions prises en charge

Les versions suivantes ont été publiées pour l’API Graph.

Version bêta

Les fonctionnalités de l’API Graph actuellement en version préliminaire se trouvent dans la section Fonctionnalités préliminaires de la rubrique Concepts de l’APi Graph ou sur le Blog de l’équipe Graph. Les fonctionnalités bêta nécessitent le paramètre de chaîne de requête « api-version=beta » Quand l’équipe de l’API graphique estime qu’une fonctionnalité en version préliminaire est prête pour la mise à la disposition générale, nous ajoutons cette fonctionnalité à la dernière version à la disposition générale (ou bien, si elle constitue une modification avec rupture, nous incrémentons le numéro de version). Nous ne garantissons pas qu’une fonctionnalité en version préliminaire sera nécessairement mise à la disposition générale.

Pour la version bêta, nous essaierons d’éviter autant que possible les modifications avec rupture, mais nous ne pouvons pas le garantir. Les applications clientes utilisant la version bêta devraient faire l’objet de modifications avec rupture de temps à autre. Veuillez consulter Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Version 1.6

Cette section répertorie les modifications apportées dans la version 1.6 de l’API Graph.

La version 1.6 de l’API Graph introduit les modifications de fonctionnalités suivantes :

  • Ajout de la prise en charge des utilisateurs de compte local Azure Active Directory B2C Cela implique de nouvelles propriétés de l’entité User et un nouveau type complexe SignInName pour prendre en charge la connexion du compte local aux clients Azure Active Directory B2C. Pour plus d’informations sur Azure Active Directory B2C, consultez Documentation Azure Active Directory B2C.

  • Ajout de la prise en charge de la découverte de service avec l’entité ServiceEndpoint et la propriété de navigation serviceEndpoints sur les entités Application et ServicePrincipal.

  • Ajout de la prise en charge du comportement d’application personnalisé pouvant être appelé par des services consommateurs avec les types AddIn et KeyValue et la propriété addIns sur les entités Application et ServicePrincipal.

  • Ajout de la prise en charge pour l’authentification sans mot de passe avec l’entité TrustedCAsForPasswordlessAuth, le type CertificateAuthorityInformation et la propriété trustedCAsForPasswordlessAuth sur l’entité TenantDetail.

  • Ajout de l’action changePassword pouvant être appelée pour donner à l’utilisateur connecté les moyens de modifier son mot de passe.

  • Les versions 2.1.x du client Graph requièrent l’API Graph 1.6 alors que les versions 2.0.x requièrent l’API Graph 1.5.

Modifications d’entités

EntitéDescription de la modification
ApplicationAjout de la propriété addIns qui définit le comportement personnalisé qu’un service consommateur peut utiliser pour appeler une application dans des contextes spécifiques.

Ajout de la propriété de navigation serviceEndpoints, qui contient la collection de points de terminaison de service qui sont disponibles pour la découverte.
LicenseDetailNouvelle entité qui contient les détails des licences pour un utilisateur.
ServiceEndpointNouvelle entité qui contient des informations de découverte de service.
ServicePrincipalAjout de la propriété addIns qui définit le comportement personnalisé qu’un service consommateur peut utiliser pour appeler une application dans des contextes spécifiques.

Ajout de la propriété de navigation serviceEndpoints, qui contient la collection de points de terminaison de service qui sont disponibles pour la découverte.
SubscribedSkuAjout de la propriété appliesTo.
TenantDetailAjout de la propriété trustedCAsForPasswordlessAuth, qui contient l’ensemble des autorités de certification utilisées pour valider la chaîne d’approbation lors de l’exécution de l’authentification sans mot de passe.
TrustedCAsForPasswordlessAuthNouvelle entité qui représente un ensemble d’autorités de certification utilisées pour valider la chaîne d’approbation lors de l’exécution de l’authentification sans mot de passe.
[Utilisateur]Ajout de la propriété creationType, permettant d’indiquer que l’utilisateur est un compte local.

Ajout de la propriété signInNames qui contient la collection des noms de connexion utilisée par un utilisateur de compte local pour se connecter à un locataire Azure Active Directory B2C. Cette propriété est renommée à partir de alternativeSignInNamesInfo dans la version bêta.

Ajout de la propriété de navigation licenseDetails.

Modifications de types complexes

TypeDescription de la modification
AddInNouveau type utilisé pour définir le comportement personnalisé qu’un service consommateur peut utiliser pour appeler une application dans des contextes spécifiques.
CertificateAuthorityInformationNouveau type représentant une autorité de certification utilisée pour valider la chaîne d’approbation lors de l’exécution de l’authentification sans mot de passe.
KeyValueNouveau type contenant une paire clé-valeur qui définit un paramètre qu’un service consommateur peut utiliser ou appeler sur une application spécifiée dans un AddIn.
ServicePlanInfoAjout de la propriété appliesTo.

Ajout de la propriété provisioningStatus.
SignInNameNouveau type destiné à contenir des informations sur un nom de connexion utilisable par un utilisateur de compte local pour se connecter à un locataire Azure Active Directory B2C. Ce type est renommé à partir de LogonIdentifier dans la version bêta.

Modifications d’actions et de fonctions

FonctionDescription de la modification
changePasswordNouvelle action pouvant être appelée pour donner à l’utilisateur connecté les moyens de modifier son mot de passe.

Version 1.5

Cette section répertorie les modifications pour la version 1.5 de l’API Graph.

La version 1.5 de l’API Graph introduit les modifications de fonctionnalités suivantes :

  • L’espace de noms du schéma de l’API Graph est passé de Microsoft.WindowsAzure.ActiveDirectory à Microsoft.DirectoryServices. Ceci affecte l’ensemble des entités et types complexes exposés par l’API Graph.

  • Les extensions de schémas d’annuaires sont à présent prises en charge. Ceci vous permet d’ajouter des propriétés requises par votre application aux objets d’annuaire. Les entités suivantes prennent en charge les extensions de schéma : User, Group, TenantDetail, Device, Application et ServicePrincipal. Pour prendre en charge les extensions de schémas d’annuaires : l’entité ExtensionProperty a été ajoutée, la propriété de navigation extensionProperties a été ajoutée à l’entité Application et une nouvelle fonction, getAvailableExtensionProperties,a été ajoutée pour retourner les propriétés d’extension inscrites pour les objets d’annuaire pris en charge. Pour plus d’informations sur l’extension des schémas d’annuaires, consultez Extensions de schéma d’annuaire.

  • La méthode de représentation des autorisations a été modifiée afin d’être parfaitement en phase avec les concepts de OAuth 2.0 ainsi qu’avec la méthode de représentation des autorisations dans d’autres composants Azure. L’entité Permission a été supprimée et remplacée par l’entité OAuth2PermissionGrant. Cette entité représente les étendues d’autorisations OAuth 2.0 déléguées arrivant dans une revendication d’étendue de jeton d’accès OAuth 2.0. De plus, la nouvelle entité AppRoleAssignment représente les rôles d’application pouvant être assignés aux utilisateurs, groupes et principaux de service. Deux types complexes associés ont également été ajoutés : AppRole et OAuth2Permission. Cette modification a entraîné un changement de nom de certaines propriétés, tandis que d’autres ont été ajoutées aux entités suivantes : Application, Group, ServicePrincipal et User.

  • L’entité Role a été renommée en DirectoryRole.

  • L’entité RoleTemplate a été renommée en DirectoryRoleTemplate.

Les tableaux suivants répertorient les fonctions, entités et types complexes ajoutés, modifiés ou supprimés dans cette version.

Modifications d’entités

EntitéDescription de la modification
ApplicationMise à jour de la propriété appId de Edm.Guid vers Edm.String.

Ajout de la propriété appRoles, qui contient la collection des rôles d’application qu’une application peut déclarer. Ces rôles peuvent être assignés à des utilisateurs, des groupes ou des principaux de service.

Ajout de la propriété groupMembershipClaims, un masque de bits configurant la revendication « groups » émise dans un jeton d’accès d’utilisateur ou OAuth 2.0 que votre application attend. Les valeurs de masque de bits sont les suivantes : 0 : aucun, 1 : groupes de sécurité et rôles Azure AD, 2 : réservé et 4 : réservé. Le fait de définir le masque de bits sur 7 permet d’obtenir l’ensemble des groupes de sécurité, groupes de distribution et rôles Azure AD auxquels appartient l’utilisateur connecté.

Ajout de la propriété knownClientApplications, contenant une liste des applications clientes liées à cette application de ressource. Le consentement pour les applications clientes connues entraîne un consentement implicite pour l’application de ressource via un dialogue de consentement combiné (affichant les étendues d’autorisation requises par le client et la ressource).

Ajout de la propriété oauth2AllowImplicitFlow, qui indique si cette application web peut demander des jetons de flux implicites OAuth2.0. La valeur par défaut est false.

Ajout de la propriété oauth2AllowUrlPathMatching, spécifiant si, dans le cadre des demandes de jeton OAuth 2.0, Azure AD autorise la correspondance de chemin d’accès de l’URI de redirection par rapport aux replyUrls de l’application. La valeur par défaut est false.

Ajout de la propriété oauth2Permissions, qui contient la collection d’étendues d’autorisation OAuth 2.0 que l’API web (ressource) expose aux applications clientes. Ces étendues d’autorisation peuvent être accordées aux applications clientes durant le consentement.

Ajout de la propriété oauth2RequiredPostResponse, qui spécifie si, dans le cadre des demandes de jeton OAuth 2.0, Azure AD autorise les demandes POST, au lieu des demandes GET. La valeur par défaut est false, ce qui indique que seules les demandes GET sont autorisées.

Ajout de la propriété requiredResourceAccess, qui indique les ressources auxquelles l’application demande à avoir accès, ainsi que l’ensemble des étendues d’autorisation OAuth et des rôles d’application dont elle a besoin dans chacune de ces ressources. Cette pré-configuration des accès aux ressources requises détermine le déroulement du consentement de l’utilisateur final.

Ajout de la propriété de navigation extensionProperties, contenant les propriétés d’extension associées à l’application.
AppRoleAssignmentNouvelle entité utilisée pour enregistrer l’assignation d’un utilisateur ou d’un groupe à une application. Dans ce cas, la vignette de l’application s’affiche sur le panneau d’accès aux applications de l’utilisateur. Cette entité peut aussi être utilisée pour accorder à une autre application (modélisée en tant que principal de service) un droit d’accès à une application de ressource dans un rôle particulier.
CoordonnéesAjout de la propriété sipProxyAddress, qui indique l’adresse du protocole d’initiation de session (SIP) de VoIP pour le contact.
DirectoryObjectAjout de la propriété deletionTimestamp, qui indique l’heure à laquelle un objet d’annuaire a été supprimé. Elle s’applique uniquement aux objets d’annuaire qui peuvent être restaurés. À l’heure actuelle, seule l’entité Application la prend en charge.
DirectoryRoleAuparavant nommée Role.

Ajout de la propriété roleTemplateId
DirectoryRoleTemplateAuparavant nommée RoleTemplate.
ExtensionPropertyNouvelle entité permettant à une application de définir et d’utiliser un jeu de propriétés supplémentaires qui peuvent être ajoutées à des objets d’annuaire (utilisateurs, groupes, détails des locataires, appareils, applications et principaux du service) sans que l’application exige un magasin de données externe.
[Groupe]Ajout de la propriété onPremisesSecurityIdentifier, contenant l’identificateur de sécurité (SID) local du groupe synchronisé depuis un site local vers le cloud.

Ajout de la propriété de navigation appRoleAssignments pointant vers le jeu d’applications (principaux du service) auquel le groupe est assigné.
OAuth2PermissionGrantNouvelle entité indiquant une étendue d’autorisation déléguée OAuth2.0. L’étendue d’autorisation déléguée OAuth peut être demandée par les applications clientes (via la collection requiredResourceAccess) appelant cette application de ressource. Remplace l’entité Permission, qui a été supprimée de cette version.
AutorisationRenommée en OAuth2PermissionGrant.
RôleRenommée en DirectoryRole.
RoleTemplateRenommée en DirectoryRoleTemplate.
ServicePrincipalAjout de la propriété appDisplayName, indiquant le nom d’affichage exposé par l’application associée.

Ajout de la propriété appRoleAssignmentRequired, indiquant si un AppRoleAssignment à un utilisateur ou un groupe est exigé avant qu’Azure AD émette un jeton pour l’utilisateur ou l’accès à l’application.

Ajout de la propriété appRoles, contenant les rôles d’application exposés par l’application associée. Pour plus d’informations, consultez la définition de propriété appRoles sur l’entité Application.

Ajout de la propriété oauth2Permissions, contenant les autorisations OAuth 2.0 exposées par l’application associée. Pour plus d’informations, consultez la définition de propriété oauth2Permisions sur l’entité Application.

Ajout de la propriété preferredTokenSigningKeyThumbprint. À usage interne uniquement. Ne pas écrire cette propriété ou en dépendre. Pourra être supprimé dans les versions ultérieures.

Ajout de la propriété de navigation appRoleAssignedTo, pointant vers le jeu d’applications auquel le principal du service est assigné.

Ajout de la propriété de navigation appRoleAssignments, pointant vers le jeu de principaux (utilisateurs, groupes et principaux du service) assignés à ce principal de service.

Ajout de la propriété de navigation oauth2PermissionGrants, pointant vers le jeu d’allocations d’emprunt d’identité d’utilisateur associées à ce principal du service.

Suppression de la propriété de navigation permissions
TenantDetailSuppression de la propriété tenantType.
[Utilisateur]Ajout de la propriété onPremisesSecurityIdentifier, contenant l’identificateur de sécurité (SID) local pour l’utilisateur synchronisé depuis un site local vers le cloud.

Ajout de la propriété sipProxyAddress, spécifiant l’adresse du protocole d’initiation (SIP) VoIP pour l’utilisateur.

Ajout de la propriété de navigation appRoleAssignments pointant vers le jeu d’applications (principaux du service) auquel cet utilisateur est assigné.

Ajout de la propriété de navigation oauth2PermissionGrants, pointant vers le jeu d’allocations d’emprunt d’identité d’utilisateur OAuth 2.0 associées à cet utilisateur.

Suppression de la propriété de navigation permissions.

Modifications de types complexes

TypeDescription de la modification
AppRoleNouveau type indiquant les rôles d’application pouvant être requis par les applications clientes appelant cette application, ou pouvant être utilisées pour assigner l’application aux utilisateurs ou aux groupes dans l’un des rôles d’application spécifiés.
OAuth2PermissionNouveau type représentant une étendue d’autorisation OAuth 2.0. L’étendue d’autorisation OAuth 2.0 indiquée peut être demandée par les applications clientes (via la collection requiredResourceAccess) appelant cette application de ressource.
RequiredResourceAccessNouveau type spécifiant le jeu d’étendues d’autorisation OAuth 2.0 et les rôles d’application sous la ressource indiquée à laquelle cette application doit accéder.
ResourceAccessNouveau type représentant une autorisation requise par cette application.

Modifications d’actions et de fonctions

FonctionDescription de la modification
getAvailableExtensionPropertiesNouvelle fonction retournant la liste complète des propriétés d’extension inscrites dans un annuaire. Les propriétés d’extension peuvent être inscrites pour les entités suivantes : User, Group, Device, TenantDetail, Application et ServicePrincipal.
getMemberObjectsNouvelle fonction retournant tous les objets Group et DirectoryRole dont un utilisateur, contact, groupe ou principal du service est membre transitif.
getObjectsByObjectIdsNouvelle fonction qui renvoie les objets d’annuaire spécifiés dans une liste d’ID d’objet. Vous pouvez également spécifier les collections de ressources (utilisateurs, groupes, etc.) à examiner en spécifiant le paramètre types facultatif.
restoreNouvelle action de service permettant de restaurer une application supprimée.

Version 2013-11-08

Cette section répertorie les modifications apportées dans la version du 11-08-2013 de l’API Graph.

Les tableaux suivants répertorient les fonctions, entités et types complexes ajoutés, modifiés ou supprimés dans cette version.

Modifications d’entités

EntitéDescription de la modification
ApplicationAjout de la propriété de navigation owners, pointant vers le jeu d’objets d’annuaire propriétaires de l’application. Les propriétaires sont un ensemble d’utilisateurs non administrateurs autorisés à modifier cet objet. Héritée de DirectoryObject.
DeviceConfigurationNouvelle entité représentant la configuration d’un appareil.
DirectoryObjectAjout de la propriété de navigation createdOnBehalfOf, pointant vers l’objet d’annuaire pour le compte duquel cet objet a été créé.

Ajout de la propriété de navigation createdObjects, pointant vers le jeu d’objets d’annuaire créés par l’objet actuel.

Ajout de la propriété de navigation owners, pointant vers le jeu d’objets d’annuaire propriétaires de l’objet actuel. Les propriétaires sont un ensemble d’utilisateurs non administrateurs autorisés à modifier cet objet.

Ajout de la propriété de navigation ownedObjects, pointant vers le jeu d’objets d’annuaire possédés par l’objet actuel.

Important: Les entités dérivant de DirectoryObject héritent de ses propriétés et peuvent aussi hériter de ses propriétés de navigation.
[Groupe]Ajout de la propriété de navigation owners, pointant vers le jeu d’objets d’annuaire propriétaires du groupe. Les propriétaires sont un ensemble d’utilisateurs non administrateurs autorisés à modifier cet objet. Héritée de DirectoryObject.
RôleAjout de la propriété de navigation ownedObjects, pointant vers le jeu d’objets d’annuaire possédés par le rôle actuel. Héritée de DirectoryObject. L’entité Role est renommée en DirectoryRole à compter de la version 1.5. Pour plus d’informations sur Role, consultez DirectoryRole.
ServicePrincipalAjout de la propriété appOwnerTenantID.

Ajout de la propriété authenticationPolicy. À usage interne uniquement. Ne pas utiliser. Supprimé dans la version 1.5.

Ajout de la propriété de navigation createdObjects, pointant vers le jeu d’objets d’annuaire créés par le principal du service. Héritée de DirectoryObject.

Ajout de la propriété de navigation owners, pointant vers le jeu d’objets d’annuaire propriétaires du principal du service. Les propriétaires sont un ensemble d’utilisateurs non administrateurs autorisés à modifier cet objet. Héritée de DirectoryObject.

Ajout de la propriété de navigation ownedObjects, pointant vers le jeu d’objets d’annuaire possédés par le principal du service. Héritée de DirectoryObject.
[Utilisateur]Ajout de la propriété immutableId, qui associe un compte d’utilisateur Active Directory local à son objet d’utilisateur Azure AD. Cette propriété doit être spécifiée lors de la création d’un compte d’utilisateur dans Graph si vous utilisez un domaine fédéré pour la propriété userPrincipalName (UPN) de l’utilisateur.

Ajout de la propriété userType, une valeur de chaîne permettant de classer les types d’utilisateur dans votre annuaire, par exemple, en « Membre » et « Invité ».

Ajout de la propriété de navigation createdObjects, pointant vers le jeu d’objets d’annuaire créés par l’utilisateur. Héritée de DirectoryObject.

Ajout de la propriété de navigation ownedObjects, pointant vers le jeu d’objets d’annuaire possédés par l’utilisateur. Héritée de DirectoryObject.

Modifications de types complexes

TypeDescription de la modification
ServicePrincipalAuthenticationPolicyÀ usage interne uniquement. Ne pas utiliser. Supprimé dans la version 1.5.

Modifications d’actions et de fonctions

FonctionDescription de la modification
assignLicenseNouvelle action de service qui met à jour un utilisateur avec une liste de licences à ajouter et/ou supprimer.

Version 2013-04-05

Il s’agit de la version de base de l’API Graph.

Ressources supplémentaires

© 2017 Microsoft