Distribuire le risorse con i modelli di ARM e l'API REST di Resource Manager

  • Articolo

Questo articolo descrive come usare l'API REST di Resource Manager con i modelli di Resource Manager (modelli di ARM) per distribuire le risorse in Azure.

È possibile includere il modello nel corpo della richiesta o come collegamento a un file. Quando si usa un file, può trattarsi di un file locale oppure di un file esterno disponibile tramite un URI. Quando il modello si trova in un account di archiviazione, è possibile limitare l'accesso al modello e fornire un token di firma di accesso condiviso in fase di distribuzione.

Autorizzazioni necessarie

Per distribuire un file Bicep o un modello di ARM, è necessario l'accesso in scrittura alle risorse distribuite e l'accesso per tutte le operazioni sul tipo di risorsa Microsoft.Resources/deployments. Ad esempio, per distribuire una macchina virtuale, sono necessarie le autorizzazioni Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. L'operazione di simulazione ha gli stessi requisiti di autorizzazione.

Per un elenco dei ruoli e delle autorizzazioni, vedere Ruoli predefiniti di Azure.

Ambito di distribuzione

Puoi destinare la tua distribuzione a un gruppo di gestione, una sottoscrizione di Azure, un gruppo di risorse o un tenant. A seconda dell'ambito della distribuzione, vengono usati comandi diversi.

Gli esempi contenuti in questo articolo usano distribuzioni di gruppi di risorse.

Distribuire con l'API REST

  1. Impostare parametri e intestazioni comuni, tra cui i token di autenticazione.

  2. Se stai eseguendo la distribuzione in un gruppo di risorse che non esiste, crea il gruppo di risorse. Specificare l'ID sottoscrizione, il nome del nuovo gruppo di risorse e il percorso per la soluzione. Per ulteriori informazioni, vedere Create a resource group (Creare un gruppo di risorse).

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2020-06-01

    Con un corpo della richiesta del tipo:

    {
 "location": "West US",
 "tags": {
   "tagname1": "tagvalue1"
 }
}

  3. Prima di distribuire il modello, puoi visualizzare in anteprima le modifiche che il modello apporterà al tuo ambiente. Usa l'operazione di simulazione per verificare che il modello apporti le modifiche previste. La simulazione convalida anche il modello per gli errori.

  4. Per distribuire un modello, specificare l'ID della sottoscrizione, il nome del gruppo di risorse e il nome della distribuzione nell'URI della richiesta.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2020-10-01

    Nel corpo della richiesta specificare un collegamento al modello e al file dei parametri. Per altre informazioni sul file dei parametri, vedere Creare il file di parametri di Resource Manager.

    Nota che mode è impostata su Incrementale. Per eseguire una distribuzione completa, imposta mode su Complete (Completo). Quando si utilizza la modalità di completamento, fare attenzione a non eliminare inavvertitamente le risorse non presenti nel modello.

    {
 "properties": {
   "templateLink": {
     "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
     "contentVersion": "1.0.0.0"
   },
   "parametersLink": {
     "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
     "contentVersion": "1.0.0.0"
   },
   "mode": "Incremental"
 }
}

    Se vuoi registrare il contenuto della risposta, il contenuto della richiesta o entrambi, includi debugSetting nella richiesta.

    {
 "properties": {
   "templateLink": {
     "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
     "contentVersion": "1.0.0.0"
   },
   "parametersLink": {
     "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
     "contentVersion": "1.0.0.0"
   },
   "mode": "Incremental",
   "debugSetting": {
     "detailLevel": "requestContent, responseContent"
   }
 }
}

    È possibile impostare l'account di archiviazione per l'utilizzzo di un token di firma di accesso condiviso (SAS). Per ulteriori informazioni, vedi Delegating Access with a Shared Access Signature (Delega dell'accesso con una firma di accesso condiviso).

    Se è necessario fornire un valore sensibile per un parametro (ad esempio una password), aggiungere tale valore a un insieme di credenziali delle chiavi. Recuperare l'insieme di credenziali delle chiavi durante la distribuzione, come illustrato nell'esempio precedente. Per altre informazioni, vedere Usare Azure Key Vault per passare valori di parametro protetti durante la distribuzione.

  5. Anziché eseguire il collegamento ai file per il modello e i parametri, è possibile includerli nel corpo della richiesta. L'esempio seguente illustra il corpo della richiesta con il modello e i parametri inline:

    {
   "properties": {
   "mode": "Incremental",
   "template": {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "storageAccountType": {
         "type": "string",
         "defaultValue": "Standard_LRS",
         "allowedValues": [
           "Standard_LRS",
           "Standard_GRS",
           "Standard_ZRS",
           "Premium_LRS"
         ],
         "metadata": {
           "description": "Storage Account type"
         }
       },
       "location": {
         "type": "string",
         "defaultValue": "[resourceGroup().location]",
         "metadata": {
           "description": "Location for all resources."
         }
       }
     },
     "variables": {
       "storageAccountName": "[format('{0}standardsa', uniquestring(resourceGroup().id))]"
     },
     "resources": [
       {
         "type": "Microsoft.Storage/storageAccounts",
         "apiVersion": "2022-09-01",
         "name": "[variables('storageAccountName')]",
         "location": "[parameters('location')]",
         "sku": {
           "name": "[parameters('storageAccountType')]"
         },
         "kind": "StorageV2",
         "properties": {}
       }
     ],
     "outputs": {
       "storageAccountName": {
         "type": "string",
         "value": "[variables('storageAccountName')]"
       }
     }
   },
   "parameters": {
     "location": {
       "value": "eastus2"
     }
   }
 }
}

  6. Per ottenere lo stato della distribuzione del modello, usare Distribuzione - Ottenere.

    GET https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01

Eseguire la distribuzione con ARMClient

ARMClient è uno strumento da riga di comando semplice per richiamare l'API di Azure Resource Manager. Per installare lo strumento, vedi ARMClient.

Per elencare le tue sottoscrizioni:

armclient GET /subscriptions?api-version=2021-04-01

Per elencare i tuoi gruppi di risorse:

armclient GET /subscriptions/<subscription-id>/resourceGroups?api-version=2021-04-01

Sostituisci <subscription-id> con il tuo ID sottoscrizione Azure.

Per creare un gruppo di risorse nell'area Stati Uniti centrali:

armclient PUT /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>?api-version=2021-04-01  "{location: 'central us', properties: {}}"

In alternativa, è possibile inserire il corpo in un file JSON denominato CreateRg.json:

{
  "location": "Central US",
  "properties": { }
}

armclient PUT /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>?api-version=2021-04-01 '@CreateRg.json'

Per ulteriori informazioni, vedi ARMClient: uno strumento da riga di comando per l'API di Azure.

Nome distribuzione

Puoi assegnare un nome alla tua distribuzione, ExampleDeploymentad esempio.

Ogni volta che esegui una distribuzione, viene aggiunta una voce alla cronologia di distribuzione del gruppo di risorse con il nome della distribuzione. Se si esegue un'altra distribuzione e si assegna lo stesso nome, la voce precedente viene sostituita con la distribuzione corrente. Se si desidera mantenere voci univoche nella cronologia di distribuzione, assegnare a ogni distribuzione un nome univoco.

Per creare un nome univoco, è possibile assegnare un numero casuale. In alternativa, aggiungere un valore di data.

Se si eseguono distribuzioni simultanee nello stesso gruppo di risorse con lo stesso nome di distribuzione, viene completata solo l'ultima distribuzione. Tutte le distribuzioni con lo stesso nome che non sono state completate vengono sostituite dall'ultima distribuzione. Ad esempio, se si esegue una distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage1 e allo stesso tempo si esegue un'altra distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage2, si distribuisce un solo account di archiviazione. L'account di archiviazione risultante è denominato storage2.

Tuttavia, se si esegue una distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage1 e subito dopo aver completato l'esecuzione di un'altra distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage2, si dispone di due account di archiviazione. Uno è denominato storage1 e l'altro è denominato storage2. Tuttavia, nella cronologia della distribuzione è presente una sola voce.

Quando si specifica un nome univoco per ogni distribuzione, è possibile eseguirli simultaneamente senza conflitti. Se si esegue una distribuzione denominata newStorage1 che distribuisce un account di archiviazione denominato storage1 e allo stesso tempo si esegue un'altra distribuzione denominata newStorage2 che distribuisce un account di archiviazione denominato storage2, sono presenti due account di archiviazione e due voci nella cronologia di distribuzione.

Per evitare conflitti con distribuzioni simultanee e per garantire voci univoche nella cronologia di distribuzione, assegnare a ogni distribuzione un nome univoco.

Passaggi successivi