Esercizio - Creare e distribuire una specifica di modello

7 minuti

Nota

La prima volta che si attiva una sandbox e si accettano le condizioni, l'account Microsoft viene associato a una nuova directory di Azure denominata Microsoft Learn Sandbox. Si viene aggiunti anche a una sottoscrizione speciale denominata Concierge Subscription.

Nell'azienda di giocattoli, il team usa Azure già da un po' di tempo e sono stati creati molti modelli usati quotidianamente. Si decide di usare un modello per creare una specifica di modello. Si inizia con il modello usato per creare gli account di Azure Cosmos DB.

Il team ha deciso che è necessario configurare il backup continuo per tutti gli account di Azure Cosmos DB. Quindi si vuole includere i backup nella configurazione predefinita degli account di Azure Cosmos DB di cui viene effettuato il provisioning tramite la specifica di modello.

In questo esercizio si pubblica il modello di Azure Cosmos DB come specifica di modello.

Durante il processo, si eseguiranno queste operazioni:

Creare un modello da usare come specifica di modello.
Aggiornare il modello assicurandosi che i parametri siano facili da comprendere e da usare.
Pubblicare la specifica di modello.
Verificare la specifica di modello usando il portale di Azure.
Distribuire la specifica di modello per testarla.
Verificare la distribuzione.

In questo esercizio viene usata l'estensione Bicep per Visual Studio Code. Assicurarsi di installare questa estensione in Visual Studio Code.

Creare il modello

Si inizia con uno dei modelli creati dal team. Il modello distribuisce un account di Azure Cosmos DB e lo configura per abilitare il backup continuo.

Aprire Visual Studio Code.
Creare un nuovo file denominato main.bicep.
Salvare il file vuoto in modo che Visual Studio Code possa caricare gli strumenti di Bicep.

È possibile selezionare File>Salva con nome oppure premere CTRL+S in Windows (⌘+S in macOS). Assicurarsi di ricordare dove è stato salvato il file. Ad esempio, è possibile creare una cartella scripts in cui salvarlo.

Copiare il codice seguente in main.bicep:

param location string = resourceGroup().location
param cosmosDBAccountName string = 'toy-${uniqueString(resourceGroup().id)}'

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2021-04-15' = {
  name: cosmosDBAccountName
  kind: 'GlobalDocumentDB'
  location: location
  properties: {
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    locations: [
      {
        locationName: location
        failoverPriority: 0
        isZoneRedundant: false
      }
    ]
    databaseAccountOfferType: 'Standard'
    enableAutomaticFailover: false
    enableMultipleWriteLocations: false
    backupPolicy: {
      type: 'Continuous'
    }
  }
}

Si noti che backupPolicy è stato impostato su Continuous. Questo valore configura Azure Cosmos DB per eseguire i backup dei dati in modo continuo invece che periodicamente.

Salvare il file.

Aprire Visual Studio Code.
Creare un nuovo file denominato azuredeploy.json.
Salvare il file vuoto in modo che Visual Studio Code carichi gli strumenti del modello di Azure Resource Manager (modello di ARM).

È possibile selezionare File>Salva con nome oppure premere CTRL+S in Windows (⌘+S in macOS). Assicurarsi di ricordare dove è stato salvato il file. Ad esempio, è possibile creare una cartella scripts in cui salvarlo.

Copiare il codice seguente in azuredeploy.json:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "cosmosDBAccountName": {
      "type": "string",
      "defaultValue": "[concat('toy-', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2021-04-15",
      "name": "[parameters('cosmosDBAccountName')]",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "consistencyPolicy": {
          "defaultConsistencyLevel": "Session"
        },
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "enableAutomaticFailover": false,
        "enableMultipleWriteLocations": false,
        "backupPolicy": {
          "type": "Continuous"
        }
      }
    }
  ]
}

Si noti che backupPolicy è stato impostato su Continuous. Questo valore configura Azure Cosmos DB per eseguire i backup dei dati in modo continuo invece che periodicamente.

Salvare il file.

Facilitare la comprensione dei parametri

Quando si usano le specifiche di modello, è importante considerare come gli altri usano il modello. Questa revisione è particolarmente importante per i parametri perché è soprattutto attraverso di essi che gli altri utenti interagiscono con il codice. I parametri nel modello del team non includono descrizioni o altri suggerimenti su come devono essere usati, quindi si aggiungono qui queste informazioni.

Aggiornare la definizione del parametro location aggiungendo una descrizione:

@description('The Azure region into which the Cosmos DB resources should be deployed.')
param location string = resourceGroup().location

Aggiornare la definizione del parametro cosmosDBAccountName per aggiungere una descrizione e per specificare la lunghezza minima e massima del nome:

@description('The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens.')
@minLength(3)
@maxLength(44)
param cosmosDBAccountName string = 'toy-${uniqueString(resourceGroup().id)}'

Salvare il file.

Aggiornare la definizione del parametro location aggiungendo una descrizione:

"location": {
  "type": "string",
  "defaultValue": "[resourceGroup().location]",
  "metadata": {
    "description": "The Azure region into which the Cosmos DB resources should be deployed."
  }
},

Aggiornare la definizione del parametro cosmosDBAccountName per aggiungere una descrizione e per specificare la lunghezza minima e massima del nome:

"cosmosDBAccountName": {
  "type": "string",
  "defaultValue": "[concat('toy-', uniqueString(resourceGroup().id))]",
  "maxLength": 44,
  "minLength": 3,
  "metadata": {
    "description": "The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens."
  }
}

Salvare il file.

Per distribuire questo modello in Azure, è necessario accedere all'account Azure dal terminale di Visual Studio Code. Assicurarsi che sia installata l'interfaccia della riga di comando di Azure e ricordarsi di accedere con lo stesso account usato per attivare la sandbox.

Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.
Se la shell visualizzata sul lato destro della finestra del terminale è bash, significa che è aperta la shell corretta ed è possibile passare alla sezione successiva.
Se viene visualizzata una shell diversa da bash, selezionare l'elenco a discesa delle shell e quindi Azure Cloud Shell (Bash).
Nell'elenco delle shell del terminale selezionare bash.
Nel terminale passare alla directory in cui è stato salvato il modello. Se, ad esempio, il salvataggio del modello è stato eseguito nella cartella templates, è possibile usare questo comando:
```
cd templates
```

Installare Bicep

Eseguire il comando seguente per assicurarsi che sia installata la versione più recente di Bicep:

az bicep install && az bicep upgrade

Nel terminale di Visual Studio Code accedere ad Azure eseguendo il comando seguente:
```
az login
```
Nel browser visualizzato accedere al proprio account Azure.

Il terminale di Visual Studio Code mostra un elenco delle sottoscrizioni associate a questo account.
Impostare la sottoscrizione predefinita per tutti i comandi dell'interfaccia della riga di comando di Azure eseguiti in questa sessione.
```
az account set --subscription "Concierge Subscription"
```
Nota

Se di recente sono state usate più sandbox, il terminale potrebbe mostrare più istanze di Concierge Subscription. In questo caso, attenersi ai due passaggi seguenti per impostarne una come predefinita. Se il comando precedente ha avuto esito positivo ed è elencata una sola Concierge Subscription, ignorare i due passaggi successivi.

Ottenere gli ID della sottoscrizione Concierge Subscription.

 az account list \
   --refresh \
   --query "[?contains(name, 'Concierge Subscription')].id" \
   --output table

Impostare la sottoscrizione predefinita usando l'ID sottoscrizione. Sostituire {your subscription ID} con l'ID della sottoscrizione Concierge Subscription più recente.
```
az account set --subscription {your subscription ID}
```

Impostare il gruppo di risorse predefinito

Se si usa l'interfaccia della riga di comando di Azure, in questo esercizio è possibile impostare il gruppo di risorse predefinito e omettere il parametro dal resto dei comandi dell'interfaccia della riga di comando di Azure. Impostare come gruppo di risorse predefinito quello creato nell'ambiente sandbox.

az configure --defaults group="<rgn>[sandbox resource group name]</rgn>"

Per distribuire questo modello in Azure, accedere all'account Azure dal terminale di Visual Studio Code. Assicurarsi che sia stato installato Azure PowerShell e di accedere allo stesso account con cui è stata attivata la sandbox.

Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.
Se la shell visualizzata sul lato destro della finestra del terminale è PowerShell o pwsh, la shell corretta è aperta ed è possibile passare alla sezione successiva.
Se viene visualizzata una shell diversa da powershell o pwsh, selezionare l'elenco a discesa delle shell e quindi PowerShell.
Nell'elenco delle shell del terminale selezionare powershell o pwsh.
Nel terminale passare alla directory in cui è stato salvato il modello. Se, ad esempio, il salvataggio del modello è stato eseguito nella cartella templates, è possibile usare questo comando:
```
Set-Location -Path templates
```

Installare l'interfaccia della riga di comando di Bicep

Per usare Bicep da Azure PowerShell, installare l'interfaccia della riga di comando di Bicep.

Nel terminale di Visual Studio Code eseguire il comando seguente:
```
Connect-AzAccount
```
Verrà aperta una finestra del browser per accedere all'account Azure.
Una volta effettuato l'accesso ad Azure, il terminale mostra un elenco delle sottoscrizioni associate all'account.

Se è stata attivata la sandbox, viene visualizzata una sottoscrizione denominata Concierge Subscription. Usarla nella parte rimanente dell'esercizio.
Impostare la sottoscrizione predefinita per tutti i comandi di Azure PowerShell eseguiti in questa sessione.
```
$context = Get-AzSubscription -SubscriptionName 'Concierge Subscription'
Set-AzContext $context
```
Nota

Se di recente sono state usate più sandbox, il terminale potrebbe mostrare più istanze di Concierge Subscription. In questo caso, attenersi ai due passaggi seguenti per impostarne una come predefinita. Se il comando precedente ha avuto esito positivo ed è elencata una sola Concierge Subscription, ignorare i due passaggi successivi.
Ottenere l'ID sottoscrizione. Eseguendo il comando seguente vengono elencate le sottoscrizioni e i rispettivi ID. Cercare Concierge Subscription e quindi copiare l'ID dalla seconda colonna. Il risultato sarà simile a: aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e.
```
Get-AzSubscription
```
Modificare la sottoscrizione attiva impostandola su Concierge Subscription. Assicurarsi di sostituire {Your subscription ID} con l'ID copiato.
```
$context = Get-AzSubscription -SubscriptionId {Your subscription ID}
Set-AzContext $context
```

Impostare il gruppo di risorse predefinito

In questo esercizio è possibile impostare il gruppo di risorse predefinito e omettere il parametro dal resto dei comandi di Azure PowerShell. Impostare come predefinito il gruppo di risorse creato automaticamente nell'ambiente sandbox.

Set-AzDefault -ResourceGroupName <rgn>[sandbox resource group name]</rgn>

Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.
Se la shell visualizzata sul lato destro della finestra del terminale è bash, significa che è aperta la shell corretta ed è possibile passare alla sezione successiva.
Se viene visualizzata una shell diversa da bash, selezionare l'elenco a discesa delle shell e quindi Azure Cloud Shell (Bash).
Nell'elenco delle shell del terminale selezionare bash.
Nel terminale passare alla directory in cui è stato salvato il modello. Se, ad esempio, il salvataggio del modello è stato eseguito nella cartella templates, è possibile usare questo comando:
```
cd templates
```

Nel terminale di Visual Studio Code accedere ad Azure eseguendo il comando seguente:
```
az login
```
Nel browser visualizzato accedere al proprio account Azure.

Il terminale di Visual Studio Code mostra un elenco delle sottoscrizioni associate a questo account.
Impostare la sottoscrizione predefinita per tutti i comandi dell'interfaccia della riga di comando di Azure eseguiti in questa sessione.
```
az account set --subscription "Concierge Subscription"
```
Nota

Se di recente sono state usate più sandbox, il terminale potrebbe mostrare più istanze di Concierge Subscription. In questo caso, attenersi ai due passaggi seguenti per impostarne una come predefinita. Se il comando precedente ha avuto esito positivo ed è elencata una sola Concierge Subscription, ignorare i due passaggi successivi.

Ottenere gli ID della sottoscrizione Concierge Subscription.

 az account list \
   --refresh \
   --query "[?contains(name, 'Concierge Subscription')].id" \
   --output table

Impostare la sottoscrizione predefinita usando l'ID sottoscrizione. Sostituire {your subscription ID} con l'ID della sottoscrizione Concierge Subscription più recente.
```
az account set --subscription {your subscription ID}
```

Impostare il gruppo di risorse predefinito

az configure --defaults group="<rgn>[sandbox resource group name]</rgn>"

Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.
Se la shell visualizzata sul lato destro della finestra del terminale è PowerShell o pwsh, la shell corretta è aperta ed è possibile passare alla sezione successiva.
Se viene visualizzata una shell diversa da powershell o pwsh, selezionare l'elenco a discesa delle shell e quindi PowerShell.
Nell'elenco delle shell del terminale selezionare powershell o pwsh.
Nel terminale passare alla directory in cui è stato salvato il modello. Se, ad esempio, il salvataggio del modello è stato eseguito nella cartella templates, è possibile usare questo comando:
```
Set-Location -Path templates
```

Nel terminale di Visual Studio Code eseguire il comando seguente:
```
Connect-AzAccount
```
Verrà aperta una finestra del browser per accedere all'account Azure.
Una volta effettuato l'accesso ad Azure, il terminale mostra un elenco delle sottoscrizioni associate all'account.

Se è stata attivata la sandbox, viene visualizzata una sottoscrizione denominata Concierge Subscription. Usarla nella parte rimanente dell'esercizio.
Impostare la sottoscrizione predefinita per tutti i comandi di Azure PowerShell eseguiti in questa sessione.
```
$context = Get-AzSubscription -SubscriptionName 'Concierge Subscription'
Set-AzContext $context
```
Nota

Se di recente sono state usate più sandbox, il terminale potrebbe mostrare più istanze di Concierge Subscription. In questo caso, attenersi ai due passaggi seguenti per impostarne una come predefinita. Se il comando precedente ha avuto esito positivo ed è elencata una sola Concierge Subscription, ignorare i due passaggi successivi.
Ottenere l'ID sottoscrizione. Eseguendo il comando seguente vengono elencate le sottoscrizioni e i rispettivi ID. Cercare Concierge Subscription e quindi copiare l'ID dalla seconda colonna. Il risultato sarà simile a: aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e.
```
Get-AzSubscription
```
Modificare la sottoscrizione attiva impostandola su Concierge Subscription. Assicurarsi di sostituire {Your subscription ID} con l'ID copiato.
```
$context = Get-AzSubscription -SubscriptionId {Your subscription ID}
Set-AzContext $context
```

Impostare il gruppo di risorse predefinito

Set-AzDefault -ResourceGroupName <rgn>[sandbox resource group name]</rgn>

Pubblicare il modello come specifica di modello

Pubblicare la specifica di modello usando questo cmdlet di Azure PowerShell nel terminale di Visual Studio Code:

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Location westus `
  -DisplayName 'Cosmos DB account' `
  -Description "This template spec creates a Cosmos DB account that meets our company's requirements." `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Location westus `
  -DisplayName 'Cosmos DB account' `
  -Description "This template spec creates a Cosmos DB account that meets our company's requirements." `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Pubblicare la specifica di modello usando questo comando dell'interfaccia della riga di comando di Azure nel terminale di Visual Studio Code:

az ts create \
  --name ToyCosmosDBAccount \
  --location westus \
  --display-name "Cosmos DB account" \
  --description "This template spec creates a Cosmos DB account that meets our company's requirements." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name ToyCosmosDBAccount \
  --location westus \
  --display-name "Cosmos DB account" \
  --description "This template spec creates a Cosmos DB account that meets our company's requirements." \
  --version 1.0 \
  --template-file azuredeploy.json

Usare il portale di Azure per verificare la specifica di modello

Passare al portale di Azure e assicurarsi di trovarsi nella sottoscrizione dell'ambiente sandbox.
1. Selezionare l'avatar nell'angolo superiore destro della pagina.
2. Selezionare Cambia directory. Nell'elenco scegliere la directory Microsoft Learn Sandbox.
Nel pannello di sinistra selezionare Gruppi di risorse.
Selezionare [nome gruppo di risorse sandbox]. Si noti che la specifica di modello è inclusa nell'elenco delle risorse:
Selezionare ToyCosmosDBAccount per aprire la specifica di modello. Sono visibili le versioni e il file modello.

Distribuire la specifica di modello

Per semplicità, si distribuisce la specifica di modello nello stesso gruppo di risorse sandbox in cui la specifica di modello è archiviata. Le specifiche di modello vengono in genere conservate in un gruppo di risorse diverso. I passaggi sono tuttavia gli stessi in entrambi i modi.

Ottenere l'ID risorsa della versione della specifica di modello eseguendo il comando di Azure PowerShell seguente:
```
$templateSpecVersionResourceId = (`
   Get-AzTemplateSpec `
      -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
      -Name ToyCosmosDBAccount `
      -Version 1.0 `
   ).Versions[0].Id
```
Si noti che si usa la proprietà Versions. Quando si distribuisce una specifica di modello, è necessario fare riferimento all'ID risorsa dell'esatta versione della specifica di modello da usare.
Pubblicare la specifica di modello usando questo cmdlet di Azure PowerShell nel terminale di Visual Studio Code:
```
New-AzResourceGroupDeployment -TemplateSpecId $templateSpecVersionResourceId
```

Ottenere l'ID risorsa della versione della specifica di modello eseguendo il comando dell'interfaccia della riga di comando di Azure seguente:

id=$(az ts show \ 
 --name ToyCosmosDBAccount \
 --resource-group "<rgn>[sandbox resource group name]</rgn>" \
 --version "1.0" \
 --query "id")

Distribuire la specifica di modello usando questo comando dell'interfaccia della riga di comando di Azure nel terminale di Visual Studio Code:
```
az deployment group create --template-spec $id
```

Il completamento della distribuzione può richiedere un minuto o due.

Verificare la distribuzione

Nel browser tornare al portale di Azure. Passare al gruppo di risorse in uso.
Accanto a Distribuzioni selezionare il collegamento 1 Riuscita per visualizzare i dettagli della distribuzione.
Selezionare la distribuzione.

Il nome della distribuzione potrebbe essere diverso da quello riportato nell'esempio.
Selezionare Dettagli distribuzione per espandere la sezione. Verificare che sia distribuito un account Azure Cosmos DB.

Esercizio - Creare e distribuire una specifica di modello

Creare il modello

Facilitare la comprensione dei parametri

Accedere ad Azure

Installare Bicep

Accedere ad Azure

Impostare il gruppo di risorse predefinito

Installare l'interfaccia della riga di comando di Bicep

Accedere ad Azure usando Azure PowerShell

Impostare il gruppo di risorse predefinito

Accedere ad Azure

Impostare il gruppo di risorse predefinito

Accedere ad Azure usando Azure PowerShell

Impostare il gruppo di risorse predefinito

Pubblicare il modello come specifica di modello

Usare il portale di Azure per verificare la specifica di modello

Distribuire la specifica di modello

Verificare la distribuzione

Commenti e suggerimenti