Condividi tramite


Guida introduttiva: Creare e distribuire il primo file Bicep con le risorse di Microsoft Graph

In questa guida introduttiva si crea un file Bicep che dichiara un gruppo di sicurezza Microsoft Entra e un'identità del servizio gestita (MSI), che rappresenta rispettivamente una risorsa di Microsoft Graph e una risorsa di Azure. Aggiungere quindi l'identità del servizio gestito come proprietario del gruppo. Si apprende anche come l'estensione Bicep semplifica lo sviluppo fornendo sicurezza dei tipi, convalida della sintassi e completamento automatico. Infine, si distribuisce il file Bicep usando un utente connesso.

Importante

Questo articolo di avvio rapido usa i riferimenti ai tipi dinamici anziché i tipi predefiniti deprecati e verranno ritirati il 24 gennaio 2025. Fino alla data di ritiro, i tipi predefiniti, contrassegnati da extension microsoftGraph, coesisteranno con i nuovi tipi dinamici. Se uno dei file Bicep esistenti usa tipi predefiniti, passare all'uso dei tipi dinamici per evitare eventuali problemi di distribuzione dei file Bicep futuri.

Importante

Microsoft Graph Bicep è attualmente in anteprima. Vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello generale.

Prerequisiti

Aggiungere un gruppo di applicazioni Microsoft Graph

Avviare VS Code e creare due nuovi file, main.bicep e bicepconfig.json nella stessa cartella.

Successivamente, per poter dichiarare le risorse di Microsoft Graph in un file Bicep, è necessario abilitare la funzionalità di anteprima di Bicep e specificare le versioni del tipo Bicep di Microsoft Graph configurando bicepconfig.json.

Questo esempio usa le risorse v1.0 e dichiara un nome di estensione descrittivo "microsoftGraphV1" per fare riferimento alla versione del br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview tipo nella Registro artefatti Microsoft.

{
    "experimentalFeaturesEnabled": {
        "extensibility": true
    },
    // specify an alias for the version of the v1.0 dynamic types package you want to use
    "extensions": {
      "microsoftGraphV1": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview"
    }
}

È anche possibile dichiarare le risorse di Microsoft Graph dalla versione beta e dalla versione 1.0 nello stesso file Bicep aggiungendo un altro riferimento a una versione di tipo beta dalla Registro artefatti Microsoft.

In main.bicep digitare extension microsoftGraphV1, dove microsoftGraphV1 è il nome descrittivo per fare riferimento al pacchetto dei tipi dinamici nel Registro artefatti Microsoft. L'istruzione extension consente al compilatore Bicep di sapere che sono inclusi i tipi di Microsoft Graph definiti in bicepconfig.json. Nella riga successiva definire una risorsa usando la resource parola chiave . Digitare resource exampleGroup e aggiungere uno spazio.

extension microsoftGraphV1

resource exampleGroup

Quando si aggiunge uno spazio dopo il nome simbolico, viene visualizzato un elenco di tipi di risorse. Continuare a digitare il gruppo fino a quando non è possibile selezionare Microsoft.Graph/Groups nelle opzioni disponibili.

Screenshot della selezione dei gruppi di Microsoft Graph per il tipo di risorsa.

Suggerimento

Se non vengono visualizzate le opzioni di intellisense in VS Code, assicurarsi di aver installato l'estensione Bicep come specificato in Prerequisiti. Se l'estensione è stata installata, concedere al servizio di linguaggio Bicep un po' di tempo per avviarsi dopo aver aperto il file Bicep. Una notifica nell'angolo in basso a destra indica che il servizio è in fase di avvio. Quando la notifica scompare, il servizio è in esecuzione.

Dopo aver selezionato Microsoft.Graph/Groups, vengono presentate le versioni API disponibili, beta o v1.0. Selezionare sempre v1.0 a meno che non sia disponibile o le proprietà delle risorse necessarie siano disponibili solo in versione beta. Per questa guida introduttiva, usare v1.0.

Screenshot della selezione della versione dell'API per il tipo di risorsa.

Dopo l’offerta singola per il tipo di risorsa, aggiungere = e uno spazio. Vengono visualizzate le opzioni per l'aggiunta di proprietà alla risorsa. Selezionare required-properties (Proprietà obbligatorie).

Screenshot dell'aggiunta di proprietà obbligatorie.

Questa opzione aggiunge tutte le proprietà per il tipo di risorsa che sono necessarie per la distribuzione. Dopo aver selezionato questa opzione, il gruppo ha le proprietà seguenti:

resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
  displayName: 
  mailEnabled: 
  mailNickname: 
  securityEnabled: 
  uniqueName: 
}

Specificare i valori per tali proprietà, impostando mailEnabled su false e securityEnabled su true. uniqueName rappresenta una chiave fornita dal client non modificabile per questa risorsa di gruppo.

Aggiungere una risorsa di identità gestita

Vs Code con l'estensione Bicep semplifica lo sviluppo fornendo frammenti predefiniti, ad esempio un frammento di codice che crea un'identità gestita. In main.bicep digitare man e quindi selezionare res-managed-identity dall'elenco e quindi premere [TAB] o [INVIO].

Screenshot dell'aggiunta di un frammento di risorsa.

Nota: i frammenti di risorsa per le risorse estendibili, ad esempio le risorse di Microsoft Graph, non sono attualmente supportati.

Il file Bicep contiene ora il codice seguente:

resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
  name: 'name'
  location: location
}

È possibile correggere l'errore di definizione del parametro mancante aggiungendo una definizione di parametro per location. Nella definizione dell'estensione aggiungere param location string = resourceGroup().location. Per altre informazioni sulla funzione usata qui, vedere resourceGroup(). Modificare il nome dell'identità gestita da name a exampleManagedIdentity.

Rendere l'identità gestita un proprietario della risorsa del gruppo

exampleGroup Nella risorsa creare una nuova riga in uniqueName, digitare ow, che mostra i proprietari come unica opzione di proprietà corrispondente, quindi premere [TAB] o [INVIO].

Screenshot dell'aggiunta di una proprietà owners.

La proprietà owners è una matrice, quindi aggiungere [] e ora fare riferimento all'ID entità dell'identità gestita usando intellisense, digitando m e selezionando managedIdentity (il nome simbolico per l'identità gestita), digitando un oggetto e selezionando le proprietà, digitando un altro elemento e selezionando principalId.

Screenshot del riferimento all'identità gestita.

Il file main.bicep dovrebbe ora essere simile al seguente:

extension microsoftGraphV1

param location string = resourceGroup().location

resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
  displayName: 'My example group'
  mailEnabled: false
  mailNickname: 'my-example-group'
  securityEnabled: true
  uniqueName: 'myExampleGroup'
  owners: [managedIdentity.properties.principalId]
}

resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
  name: 'exampleManagedIdentity'
  location: location
}

Distribuire il file Bicep usando un utente connesso

Distribuire il file Bicep accedendo all'interfaccia della riga di comando di Azure o ad Azure PowerShell usando gli esempi seguenti. Gli esempi dell'interfaccia della riga di comando di Azure in questa documentazione usano la console Bash.

## Sign in to Azure CLI
az login

## Create a resource group
az group create --name exampleRG --location eastus

## Deploy the Bicep file
az deployment group create --resource-group exampleRG --template-file main.bicep

Al termine della distribuzione, visualizzerai un messaggio che indica che la distribuzione è stata completata.

Nota

A causa di ritardi di replica, l'aggiunta dell'identità del servizio gestito come proprietario del gruppo Microsoft Entra potrebbe causare l'esito negativo della distribuzione. Attendere un po' e quindi distribuire di nuovo lo stesso file Bicep.

Pulire le risorse

Quando le risorse non sono più necessarie, usare l'interfaccia della riga di comando di Azure o il modulo di Azure PowerShell per eliminare il gruppo di risorse dell'argomento di avvio rapido.

Nota

I gruppi di risorse sono un concetto di Azure e non hanno alcun impatto sulle risorse di Microsoft Graph. Le risorse di Microsoft Graph devono essere pulite con una richiesta aggiuntiva a Microsoft Graph. Per questo è possibile usare l'interfaccia della riga di comando di Azure o Azure PowerShell, l'interfaccia della riga di comando di Microsoft Graph o Microsoft Graph PowerShell.

Gli esempi seguenti illustrano i comandi per eliminare prima la risorsa di Azure, quindi la risorsa di Microsoft Graph usando l'interfaccia della riga di comando di Azure e Azure PowerShell.

## Delete the resource group
az group delete --name exampleRG

## Delete the Microsoft Graph group
az rest --method delete --url 'https://graph.microsoft.com/v1.0/groups%28uniqueName=%27myExampleGroup%27%29'

Passaggio successivo