Condividi tramite

Informazioni di riferimento sulle API REST

  • Articolo

Informazioni di riferimento sull'API REST di Azure.

Le API REST (Representational State Transfer) sono endpoint di servizio che supportano set di operazioni HTTP (metodi), che forniscono l'accesso create/retrieve/update/delete alle risorse del servizio. Le sezioni seguenti illustrano:

  • Componenti di base di una coppia di richiesta/risposta api REST
  • Come registrare l'applicazione client con Azure Active Directory (Azure AD) per proteggere le richieste REST
  • Panoramica della creazione e dell'invio di una richiesta REST e della gestione della risposta

Nota

La maggior parte delle API REST del servizio di Azure ha una libreria DELL'SDK client corrispondente, che gestisce automaticamente gran parte del codice client. Vedere:

Azure .NET SDK
Azure Java SDK
SDK dell'interfaccia della riga di comando di Azure 2.0

Componenti della richiesta-risposta di un'API REST

Una coppia di richiesta/risposta API REST può essere separata in 5 componenti:

  1. L'URI della richiesta, costituito da: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Si noti che questa operazione viene chiamata separatamente, perché la maggior parte dei linguaggi o dei framework richiede di passarlo separatamente dal messaggio di richiesta, ma è effettivamente incluso nell'intestazione del messaggio di richiesta.
    • Schema URI: indica il protocollo usato per trasmettere la richiesta. Ad esempio, http o https.
    • Host URI: il nome di dominio o l'indirizzo IP del server in cui è ospitato l'endpoint del servizio REST, ad esempio graph.microsoft.com
    • Percorso risorsa: specifica la risorsa o la raccolta di risorse, che può includere più segmenti usati dal servizio per determinare la selezione di tali risorse. Ad esempio: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners può essere usato per eseguire query sull'elenco dei proprietari di un'applicazione specifica all'interno della raccolta di applicazioni.
    • Stringa di query (facoltativa): usata per fornire parametri semplici aggiuntivi, ad esempio la versione dell'API, i criteri di selezione delle risorse e così via.
  2. Campi di intestazione del messaggio di richiesta HTTP
    • Metodo HTTP obbligatorio (noto anche come operazione o verbo), che indica al servizio il tipo di operazione richiesto. Le API REST di Azure supportano i metodi GET, HEAD, PUT, POST e PATCH.
    • Campi di intestazione aggiuntivi facoltativi richiesti dall'URI e dal metodo HTTP specificati. Ad esempio, un'intestazione authorization che fornisce un token di connessione contenente le informazioni di autorizzazione client per la richiesta.
  3. Campi facoltativi del corpo del messaggio di richiesta HTTP per supportare l'operazione URI e HTTP. Ad esempio, le operazioni POST contengono oggetti con codifica MIME passati come parametri complessi. Il tipo di codifica MIME per il corpo deve essere specificato anche nell'intestazione della Content-type richiesta per le operazioni POST/PUT. Si noti che alcuni servizi richiedono l'uso di un tipo MIME specifico, ad esempio application/json.
  4. Campi di intestazione del messaggio di risposta HTTP
    • Codice di stato HTTP, compreso tra codici di esito positivo 2xx e codici di errore 4xx/5xx. In alternativa, può essere restituito un codice di stato definito dal servizio, come indicato nella documentazione dell'API.
    • Campi di intestazione aggiuntivi facoltativi necessari per supportare la risposta della richiesta, ad esempio un'intestazione di Content-type risposta.
  5. Campi facoltativi del corpo del messaggio di risposta HTTP
    • Gli oggetti risposta con codifica MIME possono essere restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati. In genere questi verranno restituiti in un formato strutturato come JSON o XML, come indicato dall'intestazione della Content-type risposta. Ad esempio, quando si richiede un token di accesso da Azure AD, viene restituito nel corpo della risposta come access_token elemento, uno dei diversi oggetti associati nome/valore in una raccolta dati. In questo esempio verrà inclusa anche un'intestazione di risposta di Content-Type: application/json .

Registrare l'applicazione client con Azure AD

La maggior parte dei servizi di Azure, ad esempio i provider di Resource Manager di Azure e le API di gestione dei servizi classici, 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 di Azure AD, che fornisce al client un token di accesso come prova dell'autenticazione/autorizzazione. Il token viene quindi inviato al servizio di Azure nell'intestazione autorizzazione HTTP di tutte le richieste api REST successive. Le attestazioni del token forniscono anche informazioni al servizio, consentendogli di convalidare il client ed eseguire le autorizzazioni necessarie.

Se si usa un'API REST che non usa l'autenticazione integrata di Azure AD o si è già registrato il client, è possibile passare alla sezione Creare la richiesta .

Prerequisiti

L'applicazione client deve rendere nota la configurazione dell'identità ad Azure AD prima della fase di esecuzione, registrandola in un tenant di Azure AD. Di seguito è riportato un elenco di elementi da considerare prima di registrare il client con Azure AD:

  • Se non si ha ancora un tenant di Azure AD, vedere Come ottenere un tenant di Azure Active Directory.
  • Per OAuth2 Authorization Framework, Azure AD supporta 2 tipi di client. La comprensione di ognuno consentirà di decidere qual è la scelta più appropriata per lo scenario:
    • i client web/riservati (in esecuzione in un server Web) possono accedere alle risorse con la propria identità (ad esempio servizio/daemon) o ottenere l'autorizzazione delegata per accedere alle risorse con l'identità dell'utente connesso (ad esempio: app Web). Solo un client Web ha la possibilità di gestire e presentare in modo sicuro le proprie credenziali durante l'autenticazione di Azure AD per acquisire un token di accesso.
    • i client nativi/pubblici (installati/eseguiti in un dispositivo) possono accedere solo alle risorse con autorizzazione delegata, usando l'identità dell'utente connesso per acquisire un token di accesso per conto dell'utente.
  • Il processo di registrazione creerà 2 oggetti correlati nel tenant di Azure AD in cui è 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 Azure Active Directory.

A questo punto è possibile registrare l'applicazione client con Azure AD.

Registrazione client

Per registrare un client che accederà a un'API REST di Azure Resource Manager, vedere Usare il portale per creare un'applicazione Active Directory e un'entità servizio in grado di accedere alle risorse per istruzioni dettagliate sulla registrazione. Questo articolo (disponibile anche nelle versioni di PowerShell e dell'interfaccia della riga di comando per l'automazione della registrazione) illustra come:

  • registrare l'applicazione client con Azure AD
  • impostare le richieste di autorizzazione per consentire al client di accedere all'API di azure Resource Manager
  • configurare le impostazioni del Controllo di accesso basato sul ruolo di Azure Resource Manager per l'autorizzazione del client

Per tutti gli altri client, vedere Integrazione di applicazioni con Azure Active Directory. In questo articolo verranno illustrate le attività seguenti:

  • registrare l'applicazione client con Azure AD, nella sezione "Aggiunta di un'applicazione"
  • creare una chiave privata (se si registra un client Web), nella sezione "Aggiornamento di un'applicazione"
  • aggiungere richieste di autorizzazione come richiesto dall'API, nella sezione "Aggiornamento di un'applicazione"

Dopo aver completato la registrazione dell'applicazione client, è possibile passare al codice client, in cui si creerà la richiesta REST e si gestirà la risposta.

Creare la richiesta

Questa sezione illustra i primi 3 dei 5 componenti illustrati in precedenza. Prima di tutto è necessario acquisire il token di accesso da Azure AD, che verrà usato per assemblare l'intestazione del messaggio di richiesta.

Acquisire un token di accesso

Dopo aver ottenuto una registrazione client valida, esistono essenzialmente 2 modi per l'integrazione con Azure AD per acquisire un token di accesso:

  • Gli endpoint di servizio OAuth2 della piattaforma o del linguaggio indipendenti dal linguaggio di Azure AD, ovvero ciò che verrà usato. Analogamente agli endpoint dell'API REST di Azure in uso, le istruzioni fornite in questa sezione non presupposizione sulla piattaforma o sul linguaggio/script del client quando si usano gli endpoint di Azure AD; solo che può inviare/ricevere richieste HTTPS da Azure AD e analizzare il messaggio di risposta.
  • Microsoft Authentication Libraries (MSAL) specifico della piattaforma o della lingua. Le librerie forniscono wrapper asincroni per le richieste di endpoint OAuth2 e funzionalità di gestione dei token affidabili, ad esempio la memorizzazione nella cache e la gestione dei token di aggiornamento. Per altri dettagli, tra cui la documentazione di riferimento, i download delle librerie e il codice di esempio, vedere Librerie di autenticazione Microsoft.

I 2 endpoint di Azure AD che verranno usati per autenticare il client e acquisire un token di accesso vengono definiti endpoint OAuth2 /authorize e /token . Il modo in cui usarli dipenderà 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. Seguire le istruzioni per quella più adatta allo scenario, per acquisire il token di accesso che verrà usato nelle sezioni rimanenti.

Concessione del codice di autorizzazione (client interattivi)

Questa concessione può essere usata dai client Web e nativi e richiede le credenziali di 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 dovrà richiedere un codice di autorizzazione da Azure AD. Vedere Richiedere un codice di autorizzazione per informazioni dettagliate sul formato della richiesta HTTPS GET all'endpoint /authorize e messaggi di richiesta/risposta di esempio. L'URI conterrà i parametri della stringa di query, inclusi i seguenti specifici dell'applicazione client:

    • client_id - noto anche come ID applicazione, questo è il GUID assegnato all'applicazione client quando è stata registrata nella sezione precedente

    • redirect_uri : una versione con codifica URL di [uno di] gli URI di risposta/reindirizzamento specificati durante la registrazione dell'applicazione client. Si noti che il valore passato deve corrispondere esattamente alla registrazione.

    • resource : URI dell'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 gestione dei servizi classici) usanohttps://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 anche la identifierUris proprietà dell'oggetto applicazione Azure AD.

    La richiesta all'endpoint /authorize attiva prima di tutto una richiesta di accesso per autenticare l'utente finale. La risposta restituita verrà recapitata come reindirizzamento (302) all'URI specificato in redirect_uri. Il messaggio di intestazione della risposta conterrà un campo, che contiene l'URI di reindirizzamento seguito da un locationcode parametro di query, contenente il codice di autorizzazione necessario per il passaggio 2.

  2. Successivamente, il client dovrà riscattare il codice di autorizzazione per un token di accesso. Per informazioni dettagliate sul formato della richiesta HTTPS POST all'endpoint/token, vedere Usare il codice di autorizzazione per richiedere un token di accesso. Poiché si tratta di una richiesta POST, questa volta verranno inseriti i parametri specifici dell'applicazione nel corpo della richiesta. Oltre ad alcuni di quelli menzionati in precedenza (insieme ad altri nuovi), si passerà :

    • code - questo è il parametro di query che conterrà 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 può essere usata solo dai client Web, consentendo all'applicazione di accedere direttamente alle risorse (nessuna delega utente) usando le proprie credenziali del client, fornite al momento della registrazione. In genere viene usato dai client non interattivi (nessuna interfaccia utente) in esecuzione come daemon/servizio e richiede solo l'endpoint /token per acquisire un token di accesso.

Le interazioni client/risorse per questa concessione sono molto simili al passaggio 2 della concessione del codice di autorizzazione. Per informazioni dettagliate sul formato della richiesta HTTPS POST all'endpoint, vedere la sezione "Richiedere un token di accesso" in Service to service call using client credentials (Richiedere un token di accesso) all'endpoint /token e ad esempio i messaggi di richiesta/risposta.

Assemblare il messaggio di richiesta

Si noti che la maggior parte dei linguaggi di programmazione/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/formattazione della richiesta, semplificando la scrittura del codice client (ad esempio: la classe HttpWebRequest in .NET Framework). Per brevità, verranno trattati solo gli elementi importanti della richiesta, dato che la maggior parte di questa operazione verrà gestita per te.

URI richiesta

Tutte le richieste REST protette richiedono il protocollo HTTPS per lo schema URI, fornendo la richiesta e la risposta con un canale sicuro, a causa del fatto che le informazioni riservate vengono trasmesse/ricevute. Queste informazioni (ovvero il codice di autorizzazione di Azure AD, il token di accesso/connessione, 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 i parametri delle stringhe di query necessari) verranno determinati dalla specifica dell'API REST correlata. Ad esempio, le API del provider di Resource Manager di Azure usano , le API di gestione dei servizi di Azure classiche usano https://management.azure.com/https://management.core.windows.net/, richiedono entrambi un api-version parametro stringa di query e così via.

Intestazione della richiesta

L'URI della richiesta verrà in bundle nell'intestazione del messaggio di richiesta, insieme a eventuali campi aggiuntivi determinati dalla specifica dell'API REST del servizio e dalla specifica HTTP. Ecco alcuni campi di intestazione comuni necessari nella richiesta:

  • Authorization: contiene il token di connessione OAuth2 per proteggere la richiesta, come acquisito in precedenza da Azure AD
  • Content-Type: in genere impostato su "application/json" (coppie nome/valore in formato JSON) e specifica il tipo MIME del corpo della richiesta.
  • Host: si tratta del nome di dominio o dell'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, deve essere formattato per ogni Content-Type campo di 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/corpo del messaggio di richiesta correlato, è possibile inviare la richiesta all'endpoint del servizio REST.

Ad esempio, un metodo di richiesta HTTPS GET per un provider di Resource Manager di Azure potrebbe essere inviato usando campi di intestazione della richiesta simili ai seguenti, ma 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>

E un metodo di richiesta HTTPS PUT per un provider di Resource Manager di Azure potrebbe essere inviato usando campi di intestazione richiesta AND simili ai seguenti:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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, verrà restituita l'intestazione del messaggio di risposta e il corpo facoltativo.

Elaborare il messaggio di risposta

Ora finiamo con l'ultimo 2 dei 5 componenti.

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

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

e un corpo della risposta contenente l'elenco delle sottoscrizioni di Azure e le relative singole proprietà codificate in formato JSON, simile a:

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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;

e un corpo della risposta, confermando il contenuto del gruppo di risorse appena aggiunto codificato in formato JSON, simile a:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Come per la richiesta, la maggior parte dei linguaggi di programmazione/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 sarà interessati a confermare il codice di stato HTTP nell'intestazione della risposta e, se succsessful, analizzare il corpo della risposta in base alla specifica API (o i Content-Type campi di intestazione di risposta e Content-Length ).

L'operazione è terminata. Dopo aver registrato l'applicazione Azure AD e una tecnica componentizzata per acquisire un token di accesso ed elaborare richieste HTTP, è abbastanza facile replicare il codice per sfruttare le nuove API REST.

Contenuti correlati

  • Vedere Microsoft Identity Platform (Azure Active Directory per sviluppatori) per altre informazioni sulla registrazione dell'applicazione e sul modello di programmazione di Azure AD, incluso un indice completo degli articoli HowTo e QuickStart e codice di esempio.
  • Per il test di richieste/risposte HTTP, vedere
    • Fiddler. Fiddler è un proxy di debug Web gratuito che può intercettare le richieste REST, semplificando la diagnosi dei messaggi di richiesta e risposta HTTP.
    • Decodificatore JWT e JWT.io, che semplificano il dump delle attestazioni nel token di connessione in modo da poter convalidare il loro contenuto.

Usare la sezione Commenti LiveFyre che segue questo articolo per fornire commenti e suggerimenti e aiutarci a perfezionare e modellare il contenuto.