API REST di Resource ManagerResource Manager REST APIs

Ogni chiamata ad Azure Resource Manager, ogni modello sviluppato e ogni account di archiviazione configurato sono basati su una o più chiamate all'API REST di Azure Resource Manager.Behind every call to Azure Resource Manager, behind every deployed template, behind every configured storage account there are one or more calls to the Azure Resource Manager's RESTful API. Questo argomento è dedicato a tali API e spiega come chiamarle senza usare alcun SDK.This topic is devoted to those APIs and how you can call them without using any SDK at all. Questa opzione è molto utile se si vuole il controllo completo di tutte le richieste ad Azure oppure se l'SDK per il linguaggio preferito non è disponibile o non supporta le operazioni che si vuole eseguire.This approach is useful if you want full control of requests to Azure, or if the SDK for your preferred language is not available or doesn't support the operations you need.

Questo articolo non esamina ogni API esposta in Azure, ma usa alcune operazioni come esempio per illustrare come connettersi a esse.This article does not go through every API that is exposed in Azure, but rather uses some operations as examples of how you connect to them. Una volta acquisite le nozioni di base, è possibile leggere Azure Resource Manager REST API Reference (Informazioni di riferimento sull'API REST di Azure Resource Manager) che contiene informazioni dettagliate su come usare le altre API.After you understand the basics, you can read the Azure Resource Manager REST API Reference to find detailed information on how to use the rest of the APIs.

AutenticazioneAuthentication

L'autenticazione per Resource Manager viene gestita da Azure Active Directory (AD).Authentication for Resource Manager is handled by Azure Active Directory (AD). Per connettersi a un'API, prima di tutto è necessario eseguire l'autenticazione con Azure AD per ricevere un token di autenticazione che è possibile passare a ogni richiesta.To connect to any API, you first need to authenticate with Azure AD to receive an authentication token that you can pass on to every request. Poiché si descrive una chiamata reale direttamente all'API REST, si presuppone che non si desideri eseguire l'autenticazione tramite una richiesta di nome utente e password.As we are describing a pure call directly to the REST APIs, we assume that you don't want to authenticate by being prompted for a username and password. Si suppone inoltre che l'utente non usi i meccanismi di autenticazione a due fattori.We also assume you are not using two factor authentication mechanisms. Verranno quindi create una cosiddetta applicazione Azure AD e un'entità servizio che verranno usate per l'accesso.Therefore, we create what is called an Azure AD Application and a service principal that are used to log in. Si ricordi tuttavia che Azure AD supporta diverse procedure di autenticazione e che tutte possono essere usate per recuperare il token di autenticazione necessario per le richieste API successive.But remember that Azure AD support several authentication procedures and all of them could be used to retrieve that authentication token that we need for subsequent API requests. Per istruzioni dettagliate, vedere Creare un'applicazione e un'entità servizio di Azure AD.Follow Create Azure AD Application and Service Principal for step by step instructions.

Generazione di un token di accessoGenerating an Access Token

L'autenticazione in Azure AD viene eseguita chiamando Azure AD, all'indirizzo login.microsoftonline.com. Per eseguire l'autenticazione, sono necessarie le informazioni seguenti:Authentication against Azure AD is done by calling out to Azure AD, located at login.microsoftonline.com. To authenticate, you need to have the following information:

  • ID tenant di Azure AD (nome della directory di Azure AD usata per l'accesso, spesso, ma non necessariamente, lo stesso della società)Azure AD Tenant ID (the name of that Azure AD you are using to log in, often the same as your company but not necessary)
  • ID applicazione (ottenuto durante il passaggio di creazione dell'applicazione Azure AD)Application ID (taken during the Azure AD application creation step)
  • Password (selezionata durante la creazione dell'applicazione Azure AD)Password (that you selected while creating the Azure AD Application)

Nella richiesta HTTP seguente verificare che "Azure AD Tenant ID", "Application ID" e "Password" vengano sostituiti con i valori corretti.In the following HTTP request, make sure to replace "Azure AD Tenant ID", "Application ID" and "Password" with the correct values.

Richiesta HTTP generica:Generic HTTP Request:

POST /<Azure AD Tenant ID>/oauth2/token?api-version=1.0 HTTP/1.1 HTTP/1.1
Host: login.microsoftonline.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&resource=https%3A%2F%2Fmanagement.core.windows.net%2F&client_id=<Application ID>&client_secret=<Password>

se l'autenticazione riesce, verrà restituita una risposta simile alla seguente:... will (if authentication succeeds) result in a response similar to the following response:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1448199959",
  "not_before": "1448196059",
  "resource": "https://management.core.windows.net/",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...86U3JI_0InPUk_lZqWvKiEWsayA"
}

(access_token nella risposta precedente è stato abbreviato per renderlo più leggibile)(The access_token in the preceding response have been shortened to increase readability)

Generazione del token di accesso con Bash:Generating access token using Bash:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&resource=https://management.core.windows.net/&client_id=<application id>&client_secret=<password you selected for authentication>" https://login.microsoftonline.com/<Azure AD Tenant ID>/oauth2/token?api-version=1.0

Generazione del token di accesso con Powershell:Generating access token using PowerShell:

Invoke-RestMethod -Uri https://login.microsoftonline.com/<Azure AD Tenant ID>/oauth2/token?api-version=1.0 -Method Post
 -Body @{"grant_type" = "client_credentials"; "resource" = "https://management.core.windows.net/"; "client_id" = "<application id>"; "client_secret" = "<password you selected for authentication>" }

La risposta contiene un token di accesso, informazioni sul periodo di validità del token e informazioni sulla risorsa per cui è possibile usare il token.The response contains an access token, information about how long that token is valid, and information about what resource you can use that token for. Il token di accesso ricevuto nella precedente chiamata HTTP deve attraversare tutte le richieste nell'API di Gestione risorse.The access token you received in the previous HTTP call must be passed in for all request to the Resource Manager API. Viene passato come un valore di intestazione denominato "Autorizzazione" con il valore "Bearer YOUR_ACCESS_TOKEN".You pass it as a header value named "Authorization" with the value "Bearer YOUR_ACCESS_TOKEN". Si noti lo spazio tra "Bearer" e il token di accesso.Notice the space between "Bearer" and your access token.

Come si può osservare dal risultato HTTP precedente, il token è valido per un periodo di tempo specifico durante il quale è consigliabile memorizzarlo nella cache per poterlo usare di nuovo.As you can see from the above HTTP Result, the token is valid for a specific period of time during which you should cache and reuse that same token. Anche se è possibile eseguire l'autenticazione in Azure AD per ogni chiamata API, non sarebbe per nulla efficiente.Even if it is possible to authenticate against Azure AD for each API call, it would be highly inefficient.

Chiamata alle API REST di Gestione risorseCalling Resource Manager REST APIs

In questo articolo vengono usate alcune API per illustrare l'utilizzo di base delle operazioni REST.This topic only uses a few APIs to explain the basic usage of the REST operations. Per informazioni su tutte le operazioni, vedere Azure Resource Manager REST APIs (API REST di Azure Resource Manager).For information about all the operations, see Azure Resource Manager REST APIs.

Elenco di tutte le sottoscrizioniList all subscriptions

Una delle operazioni più semplici da eseguire consiste nell'elencare le sottoscrizioni disponibili a cui è possibile accedere.One of the simplest operations you can do is to list the available subscriptions that you can access. Nella richiesta seguente è possibile osservare che il token di accesso viene passato come intestazione:In the following request, you see how the access token is passed in as a header:

Sostituire YOUR_ACCESS_TOKEN con il token di accesso vero e proprio.(Replace YOUR_ACCESS_TOKEN with your actual Access Token.)

GET /subscriptions?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Il risultato sarà un elenco di sottoscrizioni a cui questa entità servizio può accedere... and as a result, you get a list of subscriptions that this service principal is allowed to access

(Gli ID sottoscrizione seguenti sono stati abbreviati per renderli più leggibili)(Subscription IDs have been shortened for readability)

{
  "value": [
    {
      "id": "/subscriptions/3a8555...555995",
      "subscriptionId": "3a8555...555995",
      "displayName": "Azure Subscription",
      "state": "Enabled",
      "subscriptionPolicies": {
        "locationPlacementId": "Internal_2014-09-01",
        "quotaId": "Internal_2014-09-01"
      }
    }
  ]
}

Elencare tutti i gruppi di risorse in una sottoscrizione specificaList all resource groups in a specific subscription

Tutte le risorse disponibili con le API di Gestione risorse vengono annidate in un gruppo di risorse.All resources available with the Resource Manager APIs are nested inside a resource group. È possibile eseguire query in Gestione risorse per gruppi di risorse esistenti nella sottoscrizione usando la richiesta HTTP GET seguente.You can query Resource Manager for existing resource groups in your subscription using the following HTTP GET request. Si noti che questa volta l'ID sottoscrizione viene passato come parte dell'URL.Notice how the subscription ID is passed in as part of the URL this time.

(Sostituire YOUR_ACCESS_TOKEN e SUBSCRIPTION_ID con il token di accesso e l'ID sottoscrizione effettivi)(Replace YOUR_ACCESS_TOKEN and SUBSCRIPTION_ID with your actual access token and subscription ID)

GET /subscriptions/SUBSCRIPTION_ID/resourcegroups?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

La risposta ottenuta dipenderà dalla presenza o meno di gruppi di risorse definiti e, se presenti, dal numero dei gruppi.The response you get depends on whether you have any resource groups defined and if so, how many.

(Gli ID sottoscrizione seguenti sono stati abbreviati per renderli più leggibili)(Subscription IDs have been shortened for readability)

{
    "value": [
        {
            "id": "/subscriptions/3a8555...555995/resourceGroups/myfirstresourcegroup",
            "name": "myfirstresourcegroup",
            "location": "eastus",
            "properties": {
                "provisioningState": "Succeeded"
            }
        },
        {
            "id": "/subscriptions/3a8555...555995/resourceGroups/mysecondresourcegroup",
            "name": "mysecondresourcegroup",
            "location": "northeurope",
            "tags": {
                "tagname1": "My first tag"
            },
            "properties": {
                "provisioningState": "Succeeded"
            }
        }
    ]
}

Creare un gruppo di risorseCreate a resource group

Finora, le query sono state eseguite in API di Gestione risorse solo per informazioni.So far, we've only been querying the Resource Manager APIs for information. È ora di creare delle risorse iniziando dalla più semplice, il gruppo di risorse.It's time we create some resources, and let's start by the simplest of them all, a resource group. La richiesta HTTP seguente crea un gruppo di risorse in un'area/percorso di propria scelta e aggiunge un tag.The following HTTP request creates a resource group in a region/location of your choice, and adds a tag to it.

Sostituire YOUR_ACCESS_TOKEN, SUBSCRIPTION_ID, RESOURCE_GROUP_NAME con il token di accesso, l'ID sottoscrizione e il nome del gruppo di risorse effettivi che si vuole creare.(Replace YOUR_ACCESS_TOKEN, SUBSCRIPTION_ID, RESOURCE_GROUP_NAME with your actual Access Token, Subscription ID and name of the Resource Group you want to create)

PUT /subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "location": "northeurope",
  "tags": {
    "tagname1": "test-tag"
  }
}

Se l'operazione riesce, si ottiene una risposta simile alla seguente:If successful, you get a response that is similar to the following response:

{
  "id": "/subscriptions/3a8555...555995/resourceGroups/RESOURCE_GROUP_NAME",
  "name": "RESOURCE_GROUP_NAME",
  "location": "northeurope",
  "tags": {
    "tagname1": "test-tag"
  },
  "properties": {
    "provisioningState": "Succeeded"
  }
}

È stato creato un gruppo di risorse in Azure.You've successfully created a resource group in Azure. Congratulazioni.Congratulations!

Distribuire risorse in un gruppo di risorse usando un modello di Gestione risorseDeploy resources to a resource group using a Resource Manager Template

Con Gestione risorse, è possibile distribuire le risorse usando i modelli.With Resource Manager, you can deploy your resources using templates. Un modello definisce diverse risorse e le relative dipendenze.A template defines several resources and their dependencies. In questa sezione si presuppone che l'utente abbia familiarità con i modelli di Gestione risorse e verrà illustrato come fare in modo che la chiamata API inizi la distribuzione.For this section, we assume you are familiar with Resource Manager templates, and we just show you how to make the API call to start deployment. Per altre informazioni sulla creazione dei modelli, vedere Authoring Azure Resource Manager templates (Creazione di modelli di Gestione risorse).For more information about constructing templates, see Authoring Azure Resource Manager templates.

La distribuzione di un modello non è molto diversa dalla chiamata alle altre API.Deployment of a template doesn't differ much to how you call other APIs. Un aspetto importante è che la distribuzione di un modello può richiedere molto tempo.One important aspect is that deployment of a template can take quite a long time. La chiamata di API viene restituita e spetta all'utente in qualità di sviluppatore eseguire query per lo stato della distribuzione per scoprire quando la distribuzione viene eseguita.The API call just returns, and it's up to you as developer to query for status of the deployment to find out when the deployment is done. Per ulteriori informazioni, vedere Track asynchronous Azure operations (Tenere traccia delle operazioni asincrone di Azure).For more information, see Track asynchronous Azure operations.

Per questo esempio, verrà usato un modello esposto pubblicamente disponibile su GitHub.For this example, we use a publicly exposed template available on GitHub. Il modello che utilizziamo distribuisce una VM Linux nell'area degli Stati Uniti occidentali.The template we use deploys a Linux VM to the West US region. Anche se questo esempio usa un modello disponibile in un repository pubblico come GitHub, è possibile scegliere di passare il modello completo come parte della richiesta.Even though this example uses a template available in a public repository like GitHub, you can instead pass the full template as part of the request. Si noti che nell'ambito della richiesta vengono forniti i valori dei parametri che vengono usati nel modello distribuito.Note that we provide parameter values in the request that are used inside the deployed template.

(Sostituire SUBSCRIPTION_ID, RESOURCE_GROUP_NAME, DEPLOYMENT_NAME, YOUR_ACCESS_TOKEN, GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME, ADMIN_USER_NAME,ADMIN_PASSWORD e DNS_NAME_FOR_PUBLIC_IP con i valori appropriati per la richiesta)(Replace SUBSCRIPTION_ID, RESOURCE_GROUP_NAME, DEPLOYMENT_NAME, YOUR_ACCESS_TOKEN, GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME, ADMIN_USER_NAME, ADMIN_PASSWORD and DNS_NAME_FOR_PUBLIC_IP to values appropriate for your request)

PUT /subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME/providers/microsoft.resources/deployments/DEPLOYMENT_NAME?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "properties": {
    "templateLink": {
      "uri": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-simple-linux-vm/azuredeploy.json",
      "contentVersion": "1.0.0.0",
    },
    "mode": "Incremental",
    "parameters": {
        "newStorageAccountName": {
          "value": "GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME"
        },
        "adminUsername": {
          "value": "ADMIN_USER_NAME"
        },
        "adminPassword": {
          "value": "ADMIN_PASSWORD"
        },
        "dnsNameForPublicIP": {
          "value": "DNS_NAME_FOR_PUBLIC_IP"
        },
        "ubuntuOSVersion": {
          "value": "15.04"
        }
    }
  }
}

La lunga risposta JSON per questa richiesta è stata omessa per migliorare la leggibilità della documentazione.The long JSON response for this request has been omitted to improve readability of this documentation. La risposta contiene informazioni sulla distribuzione basata sui modelli appena creati.The response contains information about the templated deployment that you created.

Passaggi successiviNext steps