Unieke benoemde resources
In dit artikel worden unieke strategieën voor resources in Microsoft Azure-API's en Microsoft Graph-API's en de wijzigingen in Microsoft Graph API's vergeleken, zodat ze kunnen worden gebruikt in declaratieve infrastructuur als codesjabloonbestanden, zoals Bicep-bestanden. Ook wordt uitgelegd hoe deze wijzigingen kunnen worden gebruikt om te verwijzen naar bestaande Microsoft Graph-resources die zijn gemaakt via andere mechanismen dan bicep-bestandsimplementatie.
Belangrijk
Microsoft Graph Bicep is momenteel in PREVIEW. Raadpleeg de Aanvullende voorwaarden voor Microsoft Azure-previews voor juridische voorwaarden die van toepassing zijn op Azure-functies die in bèta of preview zijn of die anders nog niet algemeen beschikbaar zijn.
Azure- en Microsoft Graph-resourcesleutels
Microsoft Azure- en Microsoft Graph-API's maken gebruik van subtly verschillende mechanismen om resources te maken. Deze verschillen worden duidelijker wanneer u probeert beide resources in dezelfde Bicep-sjabloonbestanden te declareren.
Het standaardpatroon van de Microsoft Azure-API voor het maken van resources is het gebruik van de HTTP PUT-methode met een door de client geleverde unieke sleutel met de naam name. Met deze idempotente bewerking maakt u de resource met de opgegeven name waarde als deze niet bestaat of werkt u deze bij (vervang) als deze bestaat:
PUT /resourceCollection/{nameValue}
Het standaardpatroon van Microsoft Graph API voor het maken van resources is het gebruik van de HTTP POST-methode. Deze methode is niet idempotent en retourneert een door de service gegenereerde unieke id-sleutel met de naam id.
POST /resourceCollection
Updates voor bestaande resources worden uitgevoerd met behulp van de HTTP PATCH-methode, die in tegenstelling tot PUT geen semantische vervanging gebruikt.
De semantiek voor het maken van Microsoft Graph biedt de meeste ontwikkelaars goed, maar voldoet niet aan twee belangrijke vereisten voor declaratieve bestandssjablonen:
- Herhaalbaarheid: een implementatie van een sjabloonbestand moet meerdere keren worden uitgevoerd met hetzelfde resultaat, dat de implementatieomgeving overeenkomt met de resources die in het sjabloonbestand zijn gedeclareerd. Deze herhaalbaarheid is niet mogelijk voor niet-idempotente methoden zoals POST.
- Door de client geleverde sleutels of namen: het ontwerpen en onderhouden van een declaratief sjabloonbestand vereist dat resourcenamen (of door de client geleverde sleutels) vooraf worden gedeclareert. Voor de meeste Microsoft Graph API's zijn door de client geleverde sleutels niet mogelijk.
Door de Microsoft Graph-client geleverde sleutels
Sommige Microsoft Graph-resources ondersteunen een door de client geleverde sleuteleigenschap, waardoor een idempotent upsert-mechanisme wordt ingeschakeld om de resource te maken als deze niet bestaat of bijwerkt als dit wel het geval is. Deze door de client geleverde sleuteleigenschap is waarschijnlijk een alternatieve sleutel, maar soms is dit de primaire sleutel.
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
Wanneer de resource wordt gemaakt met behulp van een alternatieve sleutel, wordt een door de service gegenereerde waarde ingesteld voor de eigenschap primaire sleutel.
Alleen resources die dit patroon volgen, worden weergegeven als Microsoft Graph Bicep-typen, met enkele uitzonderingen.
De volgende tabel bevat de door de client geleverde sleuteleigenschappen voor Microsoft Graph-resources die worden ondersteund in Bicep-bestanden:
| Microsoft Graph-resource | Door de client geleverde sleuteleigenschap |
|---|---|
| Toepassingen | uniqueName |
| Federatieve identiteitsreferenties | name |
| App-rol toegewezen aan | Geïmpliceerd op basis van de eigenschapswaarden waarmee het object uniek wordt geïdentificeerd |
| Groepen | uniqueName |
| OAuth2-machtiging verleent | Geïmpliceerd op basis van de eigenschapswaarden waarmee het object uniek wordt geïdentificeerd |
| Service-principals | appId |
Bestaande Microsoft Graph-resources
U kunt verwijzen naar bestaande Microsoft Graph-resources in Bicep-sjablonen door de ondersteunde sleuteleigenschap van de client. Resources die zijn gemaakt via HTTP POST, hebben deze eigenschap mogelijk niet ingesteld en vereisen een eenmalige backfill.
Zodra de sleuteleigenschap is ingesteld, kan de resource worden gedeclareerd in een Bicep-bestand voor opnieuw implementeren. Als u eigenschappen van de resource wilt lezen zonder opnieuw te implementeren, gebruikt u het bestaande trefwoord.
Belangrijk
De door de client geleverde sleuteleigenschap kan niet worden gewijzigd nadat deze is ingesteld.