Esercizio: Definire le risorse figlio

  • 10 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.

Si sta iniziando a lavorare sulle richieste del team Ricerca e sviluppo e si decide di iniziare creando un database Azure Cosmos DB per i dati di test del drone. In questo esercizio si crea l'account Azure Cosmos DB e due risorse figlio, una usando la proprietà parent e l'altra come risorsa annidata.

Durante il processo:

  • Creare un file Bicep che distribuisce un account Cosmos DB.
  • Aggiungere un database e un contenitore, che sono risorse figlio dell'account Cosmos DB.
  • Distribuire il modello e 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 un modello Bicep che contiene un account Azure Cosmos DB

Innanzitutto, creare un nuovo modello Bicep con un account Azure Cosmos DB. A questo scopo:

  1. Aprire Visual Studio Code.

  2. Creare un nuovo file denominato main.bicep.

  3. 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.

  4. Aggiungere il contenuto seguente al file. È consigliabile immetterlo manualmente anziché copiarlo e incollarlo. In questo modo, è possibile vedere come gli strumenti semplificano la scrittura dei file Bicep.

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

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: cosmosDBAccountName
  location: location
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
  }
}

    Suggerimento

    Poiché Bicep è rigoroso rispetto alla posizione in cui vengono inserite le interruzioni di riga, assicurarsi di aggiungere interruzioni di riga solo nelle posizioni indicate di seguito.

    Questo modello Bicep distribuisce un account Azure Cosmos DB che rappresenta la risorsa padre creata nella sezione successiva.

  5. Salvare le modifiche apportate al file.

Aggiungi un database

Successivamente, si crea il database, che è una risorsa figlio dell'account Azure Cosmos DB.

  1. Nella parte superiore del file, tra i due parametri esistenti, aggiungere il parametro seguente:

    param cosmosDBDatabaseThroughput int = 400

  2. Nelle dichiarazioni dei parametri aggiungere la variabile seguente:

    var cosmosDBDatabaseName = 'FlightTests'

  3. Aggiungere la definizione di risorsa seguente nella parte inferiore del file, sotto la definizione di risorsa dell'account Azure Cosmos DB.

    resource cosmosDBDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = {
  parent: cosmosDBAccount
  name: cosmosDBDatabaseName
  properties: {
    resource: {
      id: cosmosDBDatabaseName
    }
    options: {
      throughput: cosmosDBDatabaseThroughput
    }
  }
}

    Si noti che questo codice distribuisce il database, che è una risorsa figlio, usando la proprietà parent. Si noti anche che il codice usa il tipo di risorsa completo, con la versione dell'API specificata in modo esplicito.

  4. Salvare le modifiche apportate al file.

Aggiungere un contenitore

A questo punto si aggiunge un'altra risorsa figlio. Questa volta la risorsa viene aggiunta come risorsa annidata invece di usare la proprietà parent.

  1. Nella parte superiore del file, sotto la definizione della variabile cosmosDBDatabaseName, aggiungere le variabili seguenti:

    var cosmosDBContainerName = 'FlightTests'
var cosmosDBContainerPartitionKey = '/droneId'

  2. Nella parte inferiore del file, all'interno della definizione della risorsa di database e prima della parentesi graffa di chiusura (}), aggiungere la definizione di risorsa annidata seguente:

    resource container 'containers' = {
  name: cosmosDBContainerName
  properties: {
    resource: {
      id: cosmosDBContainerName
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerPartitionKey
        ]
      }
    }
    options: {}
  }
}

    Si noti che è stato usato un tipo di risorsa breve, containers, poiché Bicep individua che appartiene al tipo di risorsa padre. Bicep individua che il tipo di risorsa completo è Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers. Poiché non è stata specificata una versione dell'API, Bicep usa la versione della risorsa padre, 2020-04-01.

    Al termine, il modello Bicep completo sarà simile all’esempio seguente:

    param cosmosDBAccountName string = 'toyrnd-${uniqueString(resourceGroup().id)}'
param cosmosDBDatabaseThroughput int = 400
param location string = resourceGroup().location

var cosmosDBDatabaseName = 'FlightTests'
var cosmosDBContainerName = 'FlightTests'
var cosmosDBContainerPartitionKey = '/droneId'

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: cosmosDBAccountName
  location: location
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
  }
}

resource cosmosDBDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = {
  parent: cosmosDBAccount
  name: cosmosDBDatabaseName
  properties: {
    resource: {
      id: cosmosDBDatabaseName
    }
    options: {
      throughput: cosmosDBDatabaseThroughput
    }
  }

  resource container 'containers' = {
    name: cosmosDBContainerName
    properties: {
      resource: {
        id: cosmosDBContainerName
        partitionKey: {
          kind: 'Hash'
          paths: [
            cosmosDBContainerPartitionKey
          ]
        }
      }
      options: {}
    }
  }
}

  3. Salvare le modifiche apportate al file.

Distribuire il modello in Azure

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.

  1. Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.

  2. Se la shell visualizzata sul lato destro della finestra del terminale è bash, significa che è aperta la shell corretta ed è possibile passare alla sezione successiva.

    Screenshot della finestra del terminale di Visual Studio Code con l'opzione bash visualizzata.

  3. Se viene visualizzata una shell diversa da bash, selezionare l'elenco a discesa delle shell e quindi Azure Cloud Shell (Bash).

    Screenshot della finestra del terminale di Visual Studio Code, con l'elenco a discesa della shell del terminale e l'opzione Git Bash (predefinita) selezionata.

  4. Nell'elenco delle shell del terminale selezionare bash.

    Screenshot della finestra del terminale di Visual Studio Code con il terminale bash selezionato.

  5. 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

Accedere ad Azure

  1. Nel terminale di Visual Studio Code accedere ad Azure eseguendo il comando seguente:

    az login

  2. Nel browser visualizzato accedere al proprio account Azure.

    Il terminale di Visual Studio Code mostra un elenco delle sottoscrizioni associate a questo account.

  3. 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.

  4. Ottenere gli ID della sottoscrizione Concierge Subscription.

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

  5. 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>"

Distribuire il modello in Azure

Eseguire il codice seguente dal terminale integrato in Visual Studio Code per distribuire il modello Bicep in Azure. Il completamento di questa operazione può richiedere un minuto o due, prima di visualizzare una distribuzione corretta.

az deployment group create --template-file main.bicep

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.

  1. Dal menu Terminale scegliere Nuovo terminale. La finestra del terminale si apre solitamente nella parte inferiore della schermata.

  2. Se la shell visualizzata sul lato destro della finestra del terminale è PowerShell o pwsh, la shell corretta è aperta ed è possibile passare alla sezione successiva.

    Screenshot della finestra del terminale di Visual Studio Code con l'opzione pwsh visualizzata nell'elenco a discesa della shell.

  3. Se viene visualizzata una shell diversa da powershell o pwsh, selezionare l'elenco a discesa delle shell e quindi PowerShell.

    Screenshot della finestra del terminale di Visual Studio Code, con l'elenco a discesa della shell del terminale visualizzato e PowerShell selezionato.

  4. Nell'elenco delle shell del terminale selezionare powershell o pwsh.

    Screenshot della finestra del terminale di Visual Studio Code con il terminale PowerShell selezionato.

  5. 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.

Accedere ad Azure usando Azure PowerShell

  1. Nel terminale di Visual Studio Code eseguire il comando seguente:

    Connect-AzAccount

    Verrà aperta una finestra del browser per accedere all'account Azure.

  2. 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.

  3. 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.

  4. 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

  5. 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>

Distribuire il modello in Azure

Distribuire il modello in Azure usando il comando di Azure PowerShell seguente nel terminale. Il completamento di questa operazione può richiedere un minuto o due, prima di visualizzare una distribuzione corretta.

New-AzResourceGroupDeployment -TemplateFile main.bicep

Verificare la distribuzione

  1. 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.

  2. Nella home page selezionare Gruppi di risorse. Viene visualizzato il riquadro Gruppi di risorse.

  3. Selezionare [nome gruppo di risorse sandbox].

  4. In Panoramica viene visualizzata una distribuzione completata.

    Screenshot dell'interfaccia del portale di Azure per la panoramica del gruppo di risorse con la sezione delle distribuzioni che mostra una distribuzione completata.

  5. Selezionare 1 completata per visualizzare i dettagli della distribuzione.

    Screenshot dell'Interfaccia del portale di Azure per le distribuzioni con una distribuzione completata.

  6. Selezionare la distribuzione denominata main per visualizzare le risorse distribuite e quindi selezionare Dettagli della distribuzione per espanderla. In questo caso, sono elencati un account, un database e un contenitore Cosmos DB.

    Screenshot dell'interfaccia del portale di Azure per la distribuzione specifica con tre risorse Cosmos DB elencate.

  7. Lasciare aperta la pagina nel browser in modo da poter controllare di nuovo le distribuzioni in un secondo momento.