Uniquely named resources
This article compares resource unique key strategies in Microsoft Azure APIs and Microsoft Graph APIs and the changes made to Microsoft Graph APIs to enable them to be used in declarative infrastructure as code template files, such as Bicep files. It also explains how these changes can be used to reference existing Microsoft Graph resources created via mechanisms other than Bicep file deployment.
Important
Microsoft Graph Bicep is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
Azure and Microsoft Graph resource keys
Microsoft Azure and Microsoft Graph APIs use subtly different mechanisms to create resources. These differences become more apparent when attempting to declare both these resources in the same Bicep template files.
Microsoft Azure API's standard pattern to create resources is to use the HTTP PUT method with a client-provided unique key called name. This idempotent operation creates the resource with the provided name value if it doesn't exist, or update (replace) if it does exist:
PUT /resourceCollection/{nameValue}
Microsoft Graph API's standard pattern to create resources is to use the HTTP POST method. This method isn't idempotent and returns a service-generated unique ID key called id.
POST /resourceCollection
Updates to existing resources are accomplished using the HTTP PATCH method, which unlike PUT doesn't use a replacement semantic.
The Microsoft Graph creation semantics serve most developers well, but doesn't meet two key requirements for declarative file templates:
- Repeatability: A template file deployment should be run multiple times with the same outcome, that the deployment environment matches the resources declared in the template file. This repeatability isn't possible for nonidempotent methods like POST.
- Client-provided keys or names: Authoring and maintaining a declarative template file necessitates declaring resource names (or client-provided keys) upfront. For most Microsoft Graph APIs, client-provided keys aren't possible.
Microsoft Graph client-provided keys
Some Microsoft Graph resources support a client-provided key property, enabling an idempotent "upsert" mechanism to create the resource if it doesn't exist or update it if it does. This client-provided key property is more likely an alternate key, but sometimes it's the primary key.
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
When the resource is created using an alternate key, a service-generated value is set for the primary key property.
Only resources following this pattern are exposed as Microsoft Graph Bicep types, with few exceptions.
The following table lists the client-provided key properties for Microsoft Graph resources supported in Bicep files:
| Microsoft Graph resource | Client-provided key property |
|---|---|
| Applications | uniqueName |
| Federated identity credentials | name |
| App role assigned to | Implied from the property values that uniquely identify the object |
| Groups | uniqueName |
| OAuth2 permission grants | Implied from the property values that uniquely identify the object |
| Service principals | appId |
Existing Microsoft Graph resources
You can reference existing Microsoft Graph resources in Bicep templates by the supported client-provided key property. Resources created via HTTP POST might not have this property set and require a one-time backfill.
Once set, the client-provided key property allows the resource to be declared in a Bicep file for redeployment. To read properties of the resource without redeploying, use the existing keyword.
Important
The client-provided key property cannot be changed once set.