Informazioni di riferimento sulle API REST di Azure

Benvenuti nella documentazione di riferimento sull'API REST di Azure.

Le API di trasferimento di stato rappresentativo (REST) sono endpoint di servizio che supportano un set di operazioni (metodi) HTTP che offrono l'accesso con diritti di creazione, recupero, aggiornamento o eliminazione per le risorse del servizio. In questo articolo viene descritto:

• Come chiamare le API REST di Azure con curl
• Componenti di base di una coppia di richieste/risposta api REST.
• Come registrare l'applicazione client con Microsoft Entra ID per proteggere le richieste REST.
• Panoramica della creazione e dell'invio di una richiesta REST e della gestione della risposta.

Suggerimento

La maggior parte delle API REST del servizio di Azure include librerie client che forniscono un'interfaccia nativa per l'uso dei servizi di Azure:

.NET | Java | | Node.jsPython | Andare | C++

Come chiamare le API REST di Azure con curl

Il processo descritto nel post di blog seguente illustra come chiamare un'API REST di Azure usando curl. È possibile usare curl negli script automatici. Ad esempio, negli scenari di automazione DevOps.

Chiamata all'API REST di Azure tramite curl

Componenti della richiesta-risposta di un'API REST

La coppia richiesta-risposta di un'API REST può essere suddivisa in cinque componenti:

1. L'URI della richiesta, costituito da: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Anche se l'URI della richiesta è incluso nell'intestazione del messaggio di richiesta, viene qui considerato come elemento distinto perché la maggior parte dei linguaggi o dei framework richiede di passarlo separatamente dal messaggio di richiesta.

   • Schema URI: indica il protocollo usato per trasmettere la richiesta. Ad esempio, http o https.
   • Host dell'URI: specifica il nome di dominio o l'indirizzo IP del server in cui l'endpoint del servizio REST è ospitato, ad esempio graph.microsoft.com.
   • Percorso della risorsa: specifica la risorsa o la raccolta di risorse che può includere più segmenti usati dal servizio per determinare la selezione di queste risorse. Ad esempio, beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners è possibile usare per eseguire query sull'elenco dei proprietari di un'applicazione specifica all'interno dell'insieme di applicazioni.
   • Stringa di query (facoltativo): fornisce parametri semplici aggiuntivi, ad esempio la versione dell'API o i criteri di selezione delle risorse.

2. Campi dell'intestazione del messaggio di richiesta HTTP:

   • Un metodo HTTP obbligatorio (noto anche come operazione o verbo), che indica al servizio quale tipo di operazione si sta richiedendo. Le API REST di Azure supportano metodi GET, HEAD, PUT, POST e PATCH.
   • Campi di intestazione aggiuntivi facoltativi, come richiesto dall'URI e dal metodo HTTP specificati. Ad esempio, un'intestazione di autorizzazione che fornisce un token di connessione contenente informazioni sull'autorizzazione client per la richiesta.

3. Campi facoltativi del corpo del messaggio di richiesta HTTP per supportare l'operazione URI e HTTP. Le operazioni POST contengono ad esempio oggetti con codifica MIME che vengono passati come parametri complessi. Per le operazioni POST o PUT, il tipo di codifica MIME per il corpo deve essere specificato anche nell'intestazione della richiesta Content-type. Alcuni servizi richiedono l'uso di un tipo MIME specifico, ad esempio application/json.

4. Campi di intestazione del messaggio di risposta HTTP:

   • Un codice di stato HTTP, compreso tra codici di riuscita 2xx e codici di errore 4xx o 5xx. In alternativa, può essere restituito un codice di stato definito dal servizio, come indicato nella documentazione dell'API.
   • Campi di intestazione aggiuntivi facoltativi eventualmente necessari per supportare la risposta della richiesta, ad esempio un'intestazione della risposta Content-type.

5. Campi facoltativi del corpo del messaggio di risposta HTTP:

   • Gli oggetti della risposta con codifica MIME vengono restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati. In genere, questi oggetti vengono restituiti in un formato strutturato, ad esempio JSON o XML, come indicato dall'intestazione della risposta Content-type. Ad esempio, quando si richiede un token di accesso da Microsoft Entra ID, viene restituito nel corpo della risposta come access_token elemento, uno di diversi oggetti associati nome/valore in una raccolta dati. In questo esempio viene inclusa anche un'intestazione di risposta di Content-Type: application/json .

Registrare l'applicazione client con Microsoft Entra ID

La maggior parte dei servizi di Azure (ad esempio provider di Resource Manager di Azure e il modello di distribuzione classica) richiede il codice client per l'autenticazione con credenziali valide prima di poter chiamare l'API del servizio. L'autenticazione è coordinata tra i vari attori Microsoft Entra ID e fornisce al client un token di accesso come prova dell'autenticazione. Il token viene quindi inviato al servizio di Azure nell'intestazione di autorizzazione HTTP delle richieste dell'API REST successive. Le attestazioni del token forniscono anche informazioni al servizio, consentendogli di convalidare il client ed eseguire qualsiasi autorizzazione necessaria.

Se si usa un'API REST che non usa l'autenticazione integrata Microsoft Entra oppure è già stato registrato il client, passare alla sezione Crea la richiesta.

Prerequisiti

L'applicazione client deve rendere nota la configurazione dell'identità Microsoft Entra ID prima della registrazione in un tenant di Microsoft Entra. Prima di registrare il client con Microsoft Entra ID, prendere in considerazione i prerequisiti seguenti:

• Se non si ha ancora un tenant Microsoft Entra, vedere Configurare un tenant Microsoft Entra.

• In conformità al framework di autorizzazione OAuth2, Microsoft Entra ID supporta due tipi di client. La comprensione di ogni elemento consente di decidere quale è più appropriato per lo scenario:

  • i client web/riservati vengono eseguiti in un server Web e possono accedere alle risorse sotto la propria identità (ad esempio un servizio o un daemon) o ottenere l'autorizzazione delegata per accedere alle risorse sotto l'identità di un utente connesso (ad esempio un'app Web). Solo un client Web può mantenere e presentare in modo sicuro le proprie credenziali durante l'autenticazione Microsoft Entra per acquisire un token di accesso.
  • i client nativi/pubblici vengono installati ed eseguiti in un dispositivo. Possono accedere alle risorse solo sotto l'autorizzazione delegata usando l'identità dell'utente connesso per acquisire un token di accesso per conto dell'utente.

• Il processo di registrazione crea due oggetti correlati nel tenant Microsoft Entra in cui viene registrata l'applicazione: un oggetto applicazione e un oggetto entità servizio. Per altre informazioni su questi componenti e su come vengono usati in fase di esecuzione, vedere Oggetti applicazione e entità servizio in Microsoft Entra ID.

È ora possibile registrare l'applicazione client con Microsoft Entra ID.

Registrazione client

Per registrare un client che accede a un'API REST di Azure Resource Manager, vedere Usare il portale per creare Microsoft Entra'applicazione e entità servizio che possono accedere alle risorse. L'articolo (disponibile anche nelle versioni di PowerShell e dell'interfaccia della riga di comando per la registrazione automatica) illustra come:

• Registrare l'applicazione client con Microsoft Entra ID.
• Impostare le richieste di autorizzazione per consentire al client di accedere all'API di Resource Manager di Azure.
• Configurare le impostazioni di Resource Manager Role-Based Controllo di accesso (RBAC) di Azure per l'autorizzazione del client.

Se il client accede a un'API diversa da un'API Resource Manager di Azure, fare riferimento a:

• Registrare un'applicazione con Microsoft Identity Platform
  • Registrare l'applicazione client con Microsoft Entra ID, nella sezione "Registrare un'applicazione".
  • Creare una chiave privata (se si sta registrando un client Web), nella sezione "Aggiungi credenziali".
• Configurare un'applicazione per esporre un'API Web
  • Aggiungere autorizzazioni all'API Web, esponendole come ambiti
• Configurare un'applicazione client per accedere a un'API Web
  • Aggiungere richieste di autorizzazione, come richiesto dagli ambiti definiti per l'API, nella sezione "Aggiungere autorizzazioni per accedere all'API Web".

Dopo aver completato la registrazione dell'applicazione client, passare al codice client in cui si crea la richiesta REST e gestire la risposta.

Creare la richiesta

Questa sezione illustra i primi tre componenti descritti in precedenza. È prima necessario acquisire il token di accesso da Microsoft Entra ID, che si usa per assemblare l'intestazione del messaggio di richiesta.

Acquisire un token di accesso

Dopo aver eseguito una registrazione client valida, è possibile integrare con Microsoft Entra ID per acquisire un token di accesso:

• Endpoint di servizio OAuth2 indipendenti dalla piattaforma e dal linguaggio, che vengono usati in questo articolo. Le istruzioni fornite in questa sezione presuppongono nulla sulla piattaforma o sullo script del client quando si usano gli endpoint OAuth Microsoft Entra. L'unico requisito è che è possibile inviare/ricevere richieste HTTPS a/da Microsoft Entra ID e analizzare il messaggio di risposta.
• La piattaforma e le librerie di autenticazione Microsoft specifiche del linguaggio (MSAL), oltre l'ambito di questo articolo. Le librerie forniscono wrapper asincroni per le richieste dell'endpoint OAuth2 e funzionalità di gestione dei token affidabili, ad esempio la memorizzazione nella cache e la gestione dei token di aggiornamento. Per altre informazioni, vedere Panoramica di Microsoft Authentication Library (MSAL).

I due endpoint Microsoft Entra usati per autenticare il client e acquisire un token di accesso vengono definiti endpoint OAuth2 /authorize e /token . Il modo in cui vengono usati dipende dalla registrazione dell'applicazione e dal tipo di flusso di concessione di autorizzazione OAuth2 necessario per supportare l'applicazione in fase di esecuzione. Ai fini di questo articolo, si presuppone che il client usi uno dei flussi di concessione di autorizzazione seguenti: codice di autorizzazione o credenziali client. Per acquisire un token di accesso usato nelle sezioni rimanenti, seguire le istruzioni per il flusso che corrisponde meglio allo scenario.

Concessione del codice di autorizzazione (client interattivi)

Questa concessione viene usata dai client Web e nativi, che richiedono credenziali da un utente connesso per delegare l'accesso alle risorse all'applicazione client. Usa l'endpoint /authorize per ottenere un codice di autorizzazione (in risposta all'accesso/consenso dell'utente), seguito dall'endpoint /token per scambiare il codice di autorizzazione per un token di accesso.

1. Prima di tutto, il client deve richiedere un codice di autorizzazione da Microsoft Entra ID. Per informazioni dettagliate sul formato della richiesta HTTPS GET all'endpoint /authorize e sui messaggi di richiesta/risposta, vedere Richiedere un codice di autorizzazione. L'URI contiene i parametri query-string seguenti, specifici dell'applicazione client:

   • client_id: GUID assegnato all'applicazione client durante la registrazione, noto anche come ID applicazione.

   • redirect_uri: versione con codifica URL di uno degli URI di risposta/reindirizzamento specificati durante la registrazione dell'applicazione client. Il valore passato deve corrispondere esattamente al valore di registrazione.

   • resource: URI identificatore con codifica URL specificato dall'API REST che si sta chiamando. Le API Web/REST (note anche come applicazioni di risorse) possono esporre uno o più URI ID applicazione nella configurazione. Ad esempio:

     • Le API del provider di Resource Manager di Azure (e modello di distribuzione classica) usano https://management.core.windows.net/.
     • Per altre risorse, vedere la documentazione dell'API o la configurazione dell'applicazione di risorse nella portale di Azure. Per altre informazioni, vedere la identifierUris proprietà dell'oggetto applicazione di Microsoft API Graph.

   La richiesta all'endpoint /authorize attiva innanzitutto un prompt di accesso per autenticare l'utente. La risposta restituita viene recapitata come reindirizzamento (302) all'URI specificato in redirect_uri. Il messaggio di intestazione della risposta contiene un location campo contenente l'URI di reindirizzamento seguito da un code parametro di query. Il code parametro contiene il codice di autorizzazione necessario per il passaggio 2.

2. Successivamente, il client deve riscattare il codice di autorizzazione per un token di accesso. Per informazioni dettagliate sul formato della richiesta HTTPS POST all'endpoint /token e agli esempi di richiesta/risposta, vedere Richiedere un token di accesso. Poiché si tratta di una richiesta POST, è possibile creare un pacchetto dei parametri specifici dell'applicazione nel corpo della richiesta. Oltre ad alcuni dei parametri menzionati in precedenza (insieme ad altri nuovi), si passerà:

   • code: questo parametro di query contiene il codice di autorizzazione ottenuto nel passaggio 1.

   • client_secret: è necessario questo parametro solo se il client è configurato come applicazione Web. Si tratta dello stesso valore segreto/chiave generato in precedenza, nella registrazione client.

Concessione delle credenziali client (client non interattivi)

Questa concessione viene usata solo dai client Web, consentendo all'applicazione di accedere direttamente (nessuna delega utente) usando le credenziali del client, fornite al momento della registrazione. La concessione viene in genere usata dai client non interattivi (nessuna interfaccia utente) eseguita come servizio o daemon. Richiede solo l'endpoint /token per acquisire un token di accesso.

Le interazioni client/risorse per questa concessione sono simili al passaggio 2 della concessione del codice di autorizzazione. Per informazioni dettagliate sul formato della richiesta HTTPS POST all'endpoint /token e agli esempi di richiesta/risposta, vedere la sezione "Ottenere un token" in Microsoft Identity Platform e il flusso di credenziali client OAuth 2.0.

Assemblare il messaggio di richiesta

La maggior parte dei linguaggi di programmazione o dei framework e degli ambienti di scripting semplifica l'assemblaggio e l'invio del messaggio di richiesta. In genere forniscono una classe Web/HTTP o un'API che astrae la creazione o la formattazione della richiesta, semplificando la scrittura del codice client (la HttpWebRequest classe in .NET Framework, ad esempio). Per brevità, e a causa della maggior parte dell'attività viene gestita per l'utente, questa sezione illustra solo gli elementi importanti della richiesta.

URI richiesta

Poiché le informazioni riservate vengono trasmesse e ricevute, tutte le richieste REST richiedono il protocollo HTTPS per lo schema URI, fornendo la richiesta e la risposta a un canale sicuro. Le informazioni , ovvero il codice di autorizzazione Microsoft Entra, il token di accesso/connessione e i dati di richiesta/risposta sensibili, vengono crittografati da un livello di trasporto inferiore, garantendo la privacy dei messaggi.

Il resto dell'URI della richiesta del servizio (l'host, il percorso della risorsa e tutti i parametri di stringa di query necessari) sono determinati dalla specifica dell'API REST correlata. Ad esempio, le API del provider di Azure Resource Manager usano https://management.azure.com/e il modello di distribuzione classica di Azure usa https://management.core.windows.net/. Entrambi richiedono un api-version parametro di stringa di query.

Intestazione della richiesta

L'URI della richiesta viene unito nell'intestazione del messaggio di richiesta, insieme a eventuali campi aggiuntivi richiesti dalla specifica dell'API REST del servizio e dalla specifica HTTP. La richiesta potrebbe richiedere i seguenti campi di intestazione comuni:

• Authorization: contiene il token di connessione OAuth2 per proteggere la richiesta, come acquisito in precedenza da Microsoft Entra ID.
• Content-Type: in genere impostato su "application/json" (coppie nome/valore in formato JSON) e specifica il tipo MIME del corpo della richiesta.
• Host: nome di dominio o indirizzo IP del server in cui è ospitato l'endpoint del servizio REST.

Testo della richiesta

Come accennato in precedenza, il corpo del messaggio di richiesta è facoltativo, a seconda dell'operazione specifica richiesta e dei relativi requisiti di parametro. Se necessario, la specifica DELL'API per il servizio richiesto specifica anche la codifica e il formato.

Il corpo della richiesta è separato dall'intestazione in base a una riga vuota, formattata in base al Content-Type campo intestazione. Un esempio di corpo formattato "application/json" viene visualizzato come segue:

{
  "<name>": "<value>"
}

Inviare la richiesta

Dopo aver creato l'URI della richiesta del servizio e aver creato l'intestazione e il corpo del messaggio di richiesta correlati, è possibile inviare la richiesta all'endpoint del servizio REST.

Ad esempio, è possibile inviare un metodo di richiesta HTTPS GET per un provider di Resource Manager di Azure usando i campi di intestazione della richiesta simili ai seguenti (si noti che il corpo della richiesta è vuoto):

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

È anche possibile inviare un metodo di richiesta HTTPS PUT per un provider di Resource Manager di Azure usando campi di intestazione e corpo della richiesta simili all'esempio seguente:

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

Dopo aver eseguito la richiesta, viene restituita l'intestazione del messaggio di risposta e il corpo facoltativo.

Elaborare il messaggio di risposta

Il processo termina con le ultime due dei cinque componenti.

Per elaborare la risposta, analizzare l'intestazione della risposta e, facoltativamente, il corpo della risposta (a seconda della richiesta). Nell'esempio HTTPS GET fornito nella sezione precedente è stato usato l'endpoint /subscriptions per recuperare l'elenco di sottoscrizioni per un utente. Supponendo che la risposta abbia esito positivo, è necessario ricevere campi di intestazione della risposta simili all'esempio seguente:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

Si dovrebbe ricevere un corpo di risposta che contiene un elenco di sottoscrizioni di Azure e le relative singole proprietà codificate in formato JSON, simile a:

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Analogamente, per l'esempio HTTPS PUT, è necessario ricevere un'intestazione di risposta simile alla seguente, confermando che l'operazione PUT per aggiungere "ExampleResourceGroup" ha avuto esito positivo:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

Si dovrebbe ricevere un corpo della risposta che conferma il contenuto del gruppo di risorse appena aggiunto codificato in formato JSON, simile a:

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Come per la richiesta, la maggior parte dei linguaggi di programmazione e dei framework semplifica l'elaborazione del messaggio di risposta. In genere restituiscono queste informazioni all'applicazione seguendo la richiesta, consentendo di elaborarla in un formato tipizzato/strutturato. Principalmente, si è interessati a confermare il codice di stato HTTP nell'intestazione della risposta e analizzare il corpo della risposta in base alla specifica API (o ai Content-Type campi dell'intestazione della risposta).Content-Length

Operazioni asincrone, limitazione e paging

Il modello Create/Send/Process-Response illustrato in questo articolo è sincrono e si applica a tutti i messaggi REST. Tuttavia, alcuni servizi supportano anche un modello asincrono, che richiede un'elaborazione aggiuntiva delle intestazioni di risposta per monitorare o completare la richiesta asincrona. Per ulteriori informazioni, vedere Track asynchronous Azure operations (Tenere traccia delle operazioni asincrone di Azure).

Resource Manager applica un limite al numero di richieste di lettura e scrittura all'ora per impedire a un'applicazione di inviare troppe richieste. Se l'applicazione supera tali limiti, le richieste vengono limitate. L'intestazione della risposta include il numero di richieste rimanenti per l'ambito. Per altre informazioni, vedere Throttling Resource Manager requests (Limitazione delle richieste di Resource Manager).

Alcune operazioni di elenco restituiscono una proprietà denominata nextLink nel corpo della risposta. Questa proprietà viene visualizzata quando i risultati sono troppo grandi da restituire in una risposta. In genere, la risposta include la proprietà nextLink quando l'operazione di elenco restituisce più di 1.000 elementi. Quando nextLink non è presente nei risultati, i risultati restituiti vengono completati. Quando nextLink contiene un URL, i risultati restituiti fanno solo parte del set di risultati totale.

La risposta è nel formato:

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

Per ottenere la pagina successiva dei risultati, inviare una richiesta GET all'URL nella proprietà nextLink. L'URL include un token di continuazione per indicare dove si trovano i risultati. Continuare a inviare richieste all'URL nextLink finché non contiene più un URL nei risultati restituiti.

Resilienza delle API di Azure

Le API REST di Azure sono progettate per la resilienza e la disponibilità continua. Le operazioni del piano di controllo (richieste inviate a management.azure.com) nell'API REST sono:

• Sono distribuite tra le aree. Alcuni servizi sono disponibili a livello di area.

• Sono distribuite tra le zone di disponibilità (oltre che tra le aree) in località con più zone di disponibilità.

• Non dipendono da un singolo data center logico.

• Non vengono mai disattivate per attività di manutenzione.

Contenuti correlati

È tutto. Dopo aver registrato l'applicazione Microsoft Entra e avere una tecnica modulare per acquisire un token di accesso e gestire le richieste HTTP, è abbastanza facile replicare il codice per sfruttare le nuove API REST. Per altre informazioni sulla registrazione dell'applicazione e sul modello di programmazione Microsoft Entra, vedere la documentazione Microsoft Identity Platform.

Per informazioni sui test delle richieste/risposte HTTP, vedere:

• Fiddler. Fiddler è un proxy di debug Web gratuito in grado di intercettare le richieste REST, semplificando la diagnosi dei messaggi di richiesta-risposta HTTP.
• JWT.ms, che semplificano il dump delle attestazioni nel token di connessione in modo da poter convalidare il contenuto.