Ressources nommées de manière unique
Cet article compare les stratégies clés uniques des ressources dans les API Microsoft Azure et les API Microsoft Graph et les modifications apportées aux API Microsoft Graph pour les permettre d’utiliser dans l’infrastructure déclarative en tant que fichiers de modèle de code, tels que les fichiers Bicep. Il explique également comment ces modifications peuvent être utilisées pour référencer les ressources Microsoft Graph existantes créées via des mécanismes autres que le déploiement de fichiers Bicep.
Important
Microsoft Graph Bicep est actuellement en préversion. Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.
Clés de ressources Azure et Microsoft Graph
Les API Microsoft Azure et Microsoft Graph utilisent des mécanismes subtilement différents pour créer des ressources. Ces différences deviennent plus évidentes lorsque vous tentez de déclarer ces deux ressources dans les mêmes fichiers de modèle Bicep.
Le modèle standard de l’API Microsoft Azure pour créer des ressources consiste à utiliser la méthode HTTP PUT avec une clé unique fournie par le client appelée name. Cette opération idempotente crée la ressource avec la valeur fournie name s’il n’existe pas, ou met à jour (remplacer) s’il existe :
PUT /resourceCollection/{nameValue}
Le modèle standard de l’API Microsoft Graph pour créer des ressources consiste à utiliser la méthode HTTP POST. Cette méthode n’est pas idempotente et retourne une clé d’ID unique générée par le service appelée id.
POST /resourceCollection
Les mises à jour des ressources existantes sont effectuées à l’aide de la méthode HTTP PATCH, qui contrairement à PUT n’utilise pas de sémantique de remplacement.
La sémantique de création de Microsoft Graph sert bien la plupart des développeurs, mais ne répond pas à deux exigences clés pour les modèles de fichiers déclaratifs :
- Répétabilité : un déploiement de fichiers de modèle doit être exécuté plusieurs fois avec le même résultat, que l’environnement de déploiement correspond aux ressources déclarées dans le fichier de modèle. Cette répétabilité n’est pas possible pour les méthodes non-idempotentes comme POST.
- Clés ou noms fournis par le client : la création et la gestion d’un fichier de modèle déclaratif nécessitent la déclaration de noms de ressources (ou clés fournies par le client) à l’avance. Pour la plupart des API Microsoft Graph, les clés fournies par le client ne sont pas possibles.
Clés fournies par le client Microsoft Graph
Certaines ressources Microsoft Graph prennent en charge une propriété de clé fournie par le client, ce qui permet à un mécanisme « upsert » idempotent de créer la ressource si elle n’existe pas ou de la mettre à jour si elle le fait. Cette propriété de clé fournie par le client est plus susceptible d’être une autre clé, mais il s’agit parfois de la clé primaire.
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
Lorsque la ressource est créée à l’aide d’une autre clé, une valeur générée par le service est définie pour la propriété de clé primaire.
Seules les ressources qui suivent ce modèle sont exposées en tant que types Microsoft Graph Bicep, avec quelques exceptions.
Le tableau suivant répertorie les propriétés de clé fournies par le client pour les ressources Microsoft Graph prises en charge dans les fichiers Bicep :
| Ressource Microsoft Graph | Propriété de clé fournie par le client |
|---|---|
| Applications | uniqueName |
| Informations d’identification d’identité fédérée | nom |
| Rôle d’application affecté à | Implicite à partir des valeurs de propriété qui identifient de manière unique l’objet |
| Groupes | uniqueName |
| Octrois d’autorisations OAuth2 | Implicite à partir des valeurs de propriété qui identifient de manière unique l’objet |
| Principaux de service | ID_application |
Ressources Microsoft Graph existantes
Vous pouvez référencer les ressources Microsoft Graph existantes dans les modèles Bicep par la propriété de clé fournie par le client prise en charge. Les ressources créées via HTTP POST peuvent ne pas avoir cette propriété définie et nécessiter un remplissage unique.
Une fois définie, la propriété de clé fournie par le client permet à la ressource d’être déclarée dans un fichier Bicep pour le redéploiement. Pour lire les propriétés de la ressource sans redéployer, utilisez le mot clé existant .
Important
La propriété de clé fournie par le client ne peut pas être modifiée une fois définie.