Distribuire le risorse con i modelli e l'API REST di Resource ManagerDeploy resources with Resource Manager templates and Resource Manager REST API

In questo articolo viene illustrato come utilizzare l'API REST di Resource Manager con i modelli di Resource Manager per distribuire le risorse in Azure.This article explains how to use the Resource Manager REST API with Resource Manager templates to deploy your resources to Azure.

Suggerimento

Per informazioni su come eseguire il debug di un errore durante la distribuzione, vedere:For help with debugging an error during deployment, see:

Il modello può essere un file locale oppure un file esterno disponibile tramite un URI.Your template can be either a local file or an external file that is available through a 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.When your template resides in a storage account, you can restrict access to the template and provide a shared access signature (SAS) token during deployment.

Distribuzioni incrementali e completeIncremental and complete deployments

Quando si distribuiscono le risorse, specificare se la distribuzione è un aggiornamento incrementale o completo.When deploying your resources, you specify that the deployment is either an incremental update or a complete update. La differenza principale tra le due modalità è il modo in cui Resource Manager gestisce le risorse esistenti nel gruppo di risorse che non sono presenti nel modello:The primary difference between these two modes is how Resource Manager handles existing resources in the resource group that are not in the template:

  • Nella modalità di completamento, Resource Manager elimina le risorse esistenti nel gruppo di risorse che non sono specificate nel modello.In complete mode, Resource Manager deletes resources that exist in the resource group but are not specified in the template.
  • Nella modalità incrementale, Resource Manager lascia invariate le risorse esistenti nel gruppo di risorse che non sono specificate nel modello.In incremental mode, Resource Manager leaves unchanged resources that exist in the resource group but are not specified in the template.

Per entrambe le modalità, Resource Manager prova a effettuare il provisioning di tutte le risorse specificate nel modello.For both modes, Resource Manager attempts to provision all resources specified in the template. Se la risorsa esiste già nel gruppo di risorse e le relative impostazioni sono identiche, l'operazione non comporta alcuna modifica.If the resource already exists in the resource group and its settings are unchanged, the operation results in no change. Se si modificano le impostazioni per una risorsa, il provisioning viene effettuato con le nuove impostazioni della risorsa.If you change the settings for a resource, the resource is provisioned with those new settings. Se si prova ad aggiornare il percorso o il tipo di una risorsa esistente, la distribuzione ha esito negativo e restituisce un errore.If you attempt to update the location or type of an existing resource, the deployment fails with an error. È invece necessario distribuire una nuova risorsa con il percorso o il tipo necessari.Instead, deploy a new resource with the location or type that you need.

Per impostazione predefinita, Resource Manager usa la modalità incrementale.By default, Resource Manager uses the incremental mode.

Per illustrare la differenza tra le modalità incrementale e completa, si consideri lo scenario seguente.To illustrate the difference between incremental and complete modes, consider the following scenario.

Il gruppo di risorse esistente contiene:Existing Resource Group contains:

  • Risorsa AResource A
  • Risorsa BResource B
  • Risorsa CResource C

Il modello definisce:Template defines:

  • Risorsa AResource A
  • Risorsa BResource B
  • Risorsa DResource D

Quando viene implementato in modalità incrementale, il gruppo di risorse contiene:When deployed in incremental mode, the resource group contains:

  • Risorsa AResource A
  • Risorsa BResource B
  • Risorsa CResource C
  • Risorsa DResource D

Quando viene implementato in modalità completa, la risorsa C viene eliminata.When deployed in complete mode, Resource C is deleted. Il gruppo di risorse contiene:The resource group contains:

  • Risorsa AResource A
  • Risorsa BResource B
  • Risorsa DResource D

Distribuire con l'API RESTDeploy with the REST API

  1. Impostare parametri e intestazioni comuni, tra cui i token di autenticazione.Set common parameters and headers, including authentication tokens.

  2. Se non è già disponibile un gruppo di risorse, crearne uno.If you do not have an existing resource group, create a resource group. Specificare l'ID sottoscrizione, il nome del nuovo gruppo di risorse e il percorso per la soluzione.Provide your subscription ID, the name of the new resource group, and location that you need for your solution. Per ulteriori informazioni, vedere Create a resource group (Creare un gruppo di risorse).For more information, see Create a resource group.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2015-01-01
    {
     "location": "West US",
     "tags": {
       "tagname1": "tagvalue1"
     }
    }
    
  3. Convalidare la distribuzione prima dell'esecuzione eseguendo l'operazione di convalida della distribuzione di un modello .Validate your deployment before executing it by running the Validate a template deployment operation. Durante il test della distribuzione, specificare i parametri esattamente come quando si esegue la distribuzione (illustrata nel passaggio successivo).When testing the deployment, provide parameters exactly as you would when executing the deployment (shown in the next step).

  4. Creare una distribuzione.Create a deployment. Fornire l'ID sottoscrizione, il nome del gruppo di risorse, il nome della distribuzione e un collegamento al modello.Provide your subscription ID, the name of the resource group, the name of the deployment, and a link to your template. Per informazioni sul file di modello, vedere File di parametri.For information about the template file, see Parameter file. Per altre informazioni sull'API REST per creare un gruppo di risorse, vedere Create a template deployment (Creare la distribuzione di un modello).For more information about the REST API to create a resource group, see Create a template deployment. Si noti che la modalità è impostata su Incrementale.Notice the mode is set to Incremental. Per eseguire una distribuzione completa, impostare mode su Complete (Completo).To run a complete deployment, set mode to Complete. Quando si utilizza la modalità di completamento, fare attenzione a non eliminare inavvertitamente le risorse non presenti nel modello.Be careful when using the complete mode as you can inadvertently delete resources that are not in your template.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2015-01-01
    {
     "properties": {
       "templateLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
         "contentVersion": "1.0.0.0"
       },
       "mode": "Incremental",
       "parametersLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
         "contentVersion": "1.0.0.0"
       }
     }
    }
    

    Per registrare il contenuto della risposta, il contenuto della richiesta o entrambi, includere debugSetting nella richiesta.If you want to log response content, request content, or both, include debugSetting in the request.

    "debugSetting": {
     "detailLevel": "requestContent, responseContent"
    }
    

    È possibile impostare l'account di archiviazione per l'utilizzzo di un token di firma di accesso condiviso (SAS).You can set up your storage account to use a shared access signature (SAS) token. Per altre informazioni, vedere Delegating Access with a Shared Access Signature (Delega dell'accesso con una firma di accesso condiviso).For more information, see Delegating Access with a Shared Access Signature.

  5. Ottenere lo stato della distribuzione del modello.Get the status of the template deployment. Per altre informazioni, vedere Get information about a template deployment (Ottenere informazioni sulla distribuzione di un modello).For more information, see Get information about a template deployment.

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

Eseguire nuovamente la distribuzione se non è riuscitaRedeploy when deployment fails

Per le distribuzioni che non vengono eseguite in modo corretto, è possibile specificare che una distribuzione precedente nella cronologia venga eseguita nuovamente in modo automatico.For deployments that fail, you can specify that an earlier deployment from your deployment history is automatically redeployed. Per usare questa opzione, le distribuzioni devono avere nomi univoci in modo che sia possibile identificarle nella cronologia.To use this option, your deployments must have unique names so they can be identified in the history. Se non si dispone di nomi univoci, la distribuzione non riuscita corrente potrebbe sovrascrivere quella eseguita in modo corretto nella cronologia.If you don't have unique names, the current failed deployment might overwrite the previously successful deployment in the history. È possibile usare questa opzione solo con le distribuzioni a livello di radice.You can only use this option with root level deployments. Le distribuzioni di un modello annidato non sono disponibili per la ridistribuzione.Deployments from a nested template aren't available for redeployment.

Per eseguire nuovamente l'ultima distribuzione con esito positivo se la distribuzione corrente non riesce, usare:To redeploy the last successful deployment if the current deployment fails, use:

"onErrorDeployment": {
  "type": "LastSuccessful",
},

Per eseguire nuovamente una distribuzione specifica se la distribuzione corrente non riesce, usare:To redeploy a specific deployment if the current deployment fails, use:

"onErrorDeployment": {
  "type": "SpecificDeployment",
  "deploymentName": "<deploymentname>"
}

La distribuzione specificata deve aver avuto esito positivo.The specified deployment must have succeeded.

File di parametriParameter file

Se si usa un file di parametri per passare i valori dei parametri durante la distribuzione, è necessario creare un file JSON con un formato simile all'esempio seguente:If you use a parameter file to pass parameter values during deployment, you need to create a JSON file with a format similar to the following example:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "webSiteName": {
            "value": "ExampleSite"
        },
        "webSiteHostingPlanName": {
            "value": "DefaultPlan"
        },
        "webSiteLocation": {
            "value": "West US"
        },
        "adminPassword": {
            "reference": {
               "keyVault": {
                  "id": "/subscriptions/{guid}/resourceGroups/{group-name}/providers/Microsoft.KeyVault/vaults/{vault-name}"
               }, 
               "secretName": "sqlAdminPassword" 
            }   
        }
   }
}

Le dimensioni del file di parametro non possono essere superiori a 64 KB.The size of the parameter file can't be more than 64 KB.

Se è necessario fornire un valore sensibile per un parametro (ad esempio una password), aggiungere tale valore a un insieme di credenziali delle chiavi.If you need to provide a sensitive value for a parameter (such as a password), add that value to a key vault. Recuperare l'insieme di credenziali delle chiavi durante la distribuzione, come illustrato nell'esempio precedente.Retrieve the key vault during deployment as shown in the previous example. Per ulteriori informazioni, vedere Passare valori protetti durante la distribuzione.For more information, see Pass secure values during deployment.

Passaggi successiviNext steps