Azure REST API-referens

Välkommen till referensdokumentationen för Azure REST API.

REST-API:er (Representational State Transfer) är tjänstslutpunkter som stödjer uppsättningar av HTTP-åtgärder (metoder), som ger åtkomst av typerna skapa, hämta, uppdatera eller ta bort till tjänstens resurser. Den här artikeln vägleder dig genom:

• Så här anropar du Azure REST API:er med curl
• De grundläggande komponenterna i ett REST API-begäran/svarspar.
• Så här registrerar du klientprogrammet med Microsoft Entra ID för att skydda dina REST-begäranden.
• Översikter över hur du skapar och skickar en REST-begäran och hanterar svaret.

Tips

De flesta REST-API:er för Azure-tjänsten har klientbibliotek som tillhandahåller ett internt gränssnitt för användning av Azure-tjänster:

.NET | Java | | Node.jsPython | Gå | C++

Så här anropar du Azure REST API:er med curl

Processen som beskrivs i följande blogginlägg visar hur du anropar ett Azure REST API med curl. Du kan överväga att använda curl i obevakade skript. Till exempel i DevOps-automatiseringsscenarier.

Anropa Azure REST API via curl

Komponenter i REST-API-begäran/-svar

Ett REST API-begäran/-svarspar kan delas in i fem komponenter:

1. Aktuell begärande-URI, som består av: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Även om URI-begäran ingår i begärandets meddelandehuvud, redovisar vi den separat här eftersom de flesta språk eller ramverk kräver att du skickar den separat från begärandemeddelandet.

   • URI-schema: Anger det protokoll som används för att överföra begäran. Exempel: http eller https.
   • URI-värd: Anger domännamnet eller IP-adressen för servern där REST-tjänstslutpunkten finns, som graph.microsoft.com.
   • Resursens sökväg: Anger den resurs- eller resurssamling som kan innehålla flera segment som används av tjänsten för att fastställa valet av dessa resurser. Till exempel: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners kan användas för att köra frågor mot listan över ett visst programs ägare i programsamlingen.
   • Frågesträng (valfritt): Ger ytterligare enkla parametrar, till exempel API-versionen eller resursurvalskriterier.

2. Fält för meddelandehuvud för HTTP-begäran :

   • En nödvändig HTTP-metod (kallas även en åtgärd eller ett verb), som talar om för tjänsten vilken typ av åtgärd du begär. Azure REST API:er stöder GET-, HEAD-, PUT-, POST- och PATCH-metoder.
   • Valfria ytterligare huvudfält efter vad som krävs av den angivna URI- och HTTP-metoden. Till exempel ett auktoriseringshuvud som tillhandahåller en ägartoken som innehåller information om klientauktorisering för begäran.

3. Valfria brödtextsfält för HTTP-begärandemeddelande till stöd för URI- och HTTP-åtgärder. Som exempel innehåller POST-åtgärder MIME-kodade objekt som skickas som komplexa parametrar. För POST- eller PUT-åtgärder måste MIME-kodningstypen för brödtexten anges även i Content-type begärandehuvudet. Vissa tjänster kräver att du använder en specifik MIME-typ, som application/json.

4. Huvudfält för HTTP-svarsmeddelande:

   • En HTTP-statuskod som sträcker sig från 2xx lyckade koder till 4xx eller 5xx felkoder. Som alternativ kan också en tjänstedefinierad statuskod returneras, i enlighet med beskrivningen i API-dokumentationen.
   • Valfria ytterligare huvudfält efter vad som krävs för att stödja svaret på begäran, som ett svarshuvud av formen Content-type.

5. Valfria fält för HTTP-svarsmeddelandets brödtext:

   • MIME-kodade svarsobjekt returneras i HTTP-svarsbrödtexten som till exempel ett svar från en GET-metod som returnerar data. Normalt sett returneras dessa objekt i ett strukturerat format, till exempel JSON eller XML, enligt vad som anges av svarshuvudet av formen Content-type . När du till exempel begär en åtkomsttoken från Microsoft Entra ID returneras den i svarstexten som elementetaccess_token, ett av flera namn/värde-kopplade objekt i en datasamling. I det här exemplet ingår även ett svarshuvud Content-Type: application/json för.

Registrera klientprogrammet med Microsoft Entra ID

De flesta Azure-tjänster (till exempel Azure Resource Manager-leverantörer och den klassiska distributionsmodellen) kräver att klientkoden autentiseras med giltiga autentiseringsuppgifter innan du kan anropa tjänstens API. Autentisering samordnas mellan de olika aktörerna av Microsoft Entra ID och ger klienten en åtkomsttoken som bevis på autentiseringen. Token skickas sedan till Azure-tjänsten i HTTP-auktoriseringshuvudet för efterföljande REST API-begäranden. Tokens anspråk ger också information till tjänsten, så att den kan verifiera klienten och utföra nödvändig auktorisering.

Om du använder ett REST-API som inte använder integrerad Microsoft Entra-autentisering, eller om du redan har registrerat klienten, går du vidare till avsnittet Skapa begäran.

Förutsättningar

Klientprogrammet måste göra sin identitetskonfiguration känd för att Microsoft Entra ID innan körning genom att registrera den i en Microsoft Entra klientorganisation. Innan du registrerar din klient med Microsoft Entra ID bör du tänka på följande krav:

• Om du inte har någon Microsoft Entra klientorganisation än kan du läsa Konfigurera en Microsoft Entra klientorganisation.

• I enlighet med OAuth2 Authorization Framework stöder Microsoft Entra ID två typer av klienter. Att förstå var och en hjälper dig att avgöra vilket som passar bäst för ditt scenario:

  • webb-/konfidentiella klienter körs på en webbserver och kan komma åt resurser under sin egen identitet (till exempel en tjänst eller daemon) eller få delegerad auktorisering för att få åtkomst till resurser under identiteten för en inloggad användare (till exempel en webbapp). Endast en webbklient kan på ett säkert sätt underhålla och presentera sina egna autentiseringsuppgifter under Microsoft Entra autentisering för att hämta en åtkomsttoken.
  • interna/offentliga klienter installeras och körs på en enhet. De kan bara komma åt resurser under delegerad auktorisering, med hjälp av identiteten för den inloggade användaren för att hämta en åtkomsttoken för användarens räkning.

• Registreringsprocessen skapar två relaterade objekt i den Microsoft Entra klientorganisation där programmet är registrerat: ett programobjekt och ett objekt för tjänstens huvudnamn. Mer bakgrund om dessa komponenter och hur de används vid körning finns i Program- och tjänsthuvudnamnsobjekt i Microsoft Entra ID.

Nu är du redo att registrera klientprogrammet med Microsoft Entra ID.

Klientregistrering

Information om hur du registrerar en klient som har åtkomst till en Azure Resource Manager REST API finns i Använda portalen för att skapa Microsoft Entra program och tjänstens huvudnamn som har åtkomst till resurser. Artikeln (finns även i PowerShell- och CLI-versioner för automatisk registrering) som visar hur du:

• Registrera klientprogrammet med Microsoft Entra ID.
• Ange behörighetsbegäranden så att klienten får åtkomst till Azure Resource Manager-API:et.
• Konfigurera Inställningar för Azure Resource Manager Role-Based Access Control (RBAC) för att auktorisera klienten.

Om klienten har åtkomst till ett annat API än ett Azure Resource Manager-API läser du följande:

• Registrera en app på Microsoft Identity Platform
  • Registrera klientprogrammet med Microsoft Entra ID i avsnittet "Registrera ett program".
  • Skapa en hemlig nyckel (om du registrerar en webbklient) i avsnittet Lägg till autentiseringsuppgifter.
• Konfigurera ett program för att exponera ett webb-API
  • Lägga till behörigheter i webb-API:et och exponera dem som omfång
• Konfigurera ett klientprogram för åtkomst till ett webb-API
  • Lägg till behörighetsbegäranden som krävs av de omfång som definierats för API:et i avsnittet "Lägg till behörigheter för att komma åt ditt webb-API".

Nu när du har slutfört registreringen av klientprogrammet går du vidare till klientkoden där du skapar REST-begäran och hanterar svaret.

Skapa begäran

Det här avsnittet beskriver de tre första av de fem komponenter som vi diskuterade tidigare. Du måste först hämta åtkomsttoken från Microsoft Entra ID, som du använder för att sätta ihop meddelandehuvudet för begäran.

Hämta en åtkomsttoken

När du har en giltig klientregistrering har du två sätt att integrera med Microsoft Entra ID för att hämta en åtkomsttoken:

• Plattforms- och språkneutrala OAuth2-tjänstslutpunkter, som vi använder i den här artikeln. Anvisningarna i det här avsnittet förutsätter ingenting om klientens plattform eller språk/skript när du använder Microsoft Entra OAuth-slutpunkter. Det enda kravet är att du kan skicka/ta emot HTTPS-begäranden till/från Microsoft Entra ID och parsa svarsmeddelandet.
• Plattforms- och språkspecifika Microsoft Authentication Libraries (MSAL), som ligger utanför omfånget för den här artikeln. Biblioteken tillhandahåller asynkrona omslutningar för OAuth2-slutpunktsbegäranden och robusta funktioner för tokenhantering, till exempel cachelagring och uppdateringstokenhantering. Mer information finns i Översikt över Microsoft Authentication Library (MSAL).

De två Microsoft Entra slutpunkter som du använder för att autentisera klienten och hämta en åtkomsttoken kallas OAuth2 /authorize och /token slutpunkter. Hur du använder dem beror på programmets registrering och vilken typ av OAuth2-auktoriseringsbidragsflöde du behöver för att stödja ditt program vid körning. I den här artikeln förutsätter vi att klienten använder något av följande auktoriseringsflöde: auktoriseringskod eller klientautentiseringsuppgifter. Om du vill hämta en åtkomsttoken som används i de återstående avsnitten följer du anvisningarna för flödet som bäst matchar ditt scenario.

Beviljande av auktoriseringskod (interaktiva klienter)

Det här beviljandet används av både webbklienter och interna klienter, vilket kräver autentiseringsuppgifter från en inloggad användare för att delegera resursåtkomst till klientprogrammet. Den använder /authorize slutpunkten för att hämta en auktoriseringskod (som svar på användarinloggning/medgivande), följt av /token slutpunkten för att utbyta auktoriseringskoden mot en åtkomsttoken.

1. Först måste klienten begära en auktoriseringskod från Microsoft Entra ID. Mer information om formatet för HTTPS GET-begäran till /authorize slutpunkten och exempel på begärande-/svarsmeddelanden finns i Begära en auktoriseringskod. URI:n innehåller följande frågesträngsparametrar, som är specifika för klientprogrammet:

   • client_id: Ett GUID som tilldelades klientprogrammet under registreringen, även kallat ett program-ID.

   • redirect_uri: En URL-kodad version av en av svars-/omdirigerings-URI:erna som angavs under registreringen av klientprogrammet. Det värde som du skickar måste matcha ditt registreringsvärde exakt.

   • resource: En URL-kodad identifierar-URI som anges av rest-API:et som du anropar. Webb-/REST-API:er (även kallade resursprogram) kan exponera en eller flera program-ID-URI:er i konfigurationen. Exempel:

     • Api:er för Azure Resource Manager-provider (och klassisk distributionsmodell) använder https://management.core.windows.net/.
     • Andra resurser finns i API-dokumentationen eller resursprogrammets konfiguration i Azure Portal. Mer information finns i identifierUris egenskapen för Microsoft Graph API-programobjektet.

   Begäran till /authorize slutpunkten utlöser först en inloggningsprompt för att autentisera användaren. Svaret du får tillbaka levereras som en omdirigering (302) till den URI som du angav i redirect_uri. Svarshuvudmeddelandet innehåller ett location fält som innehåller omdirigerings-URI följt av en code frågeparameter. Parametern code innehåller den auktoriseringskod som du behöver för steg 2.

2. Därefter måste klienten lösa in auktoriseringskoden för en åtkomsttoken. Mer information om formatet för HTTPS POST-begäran till /token slutpunkten och exempel på begäran/svar finns i Begära en åtkomsttoken. Eftersom det här är en POST-begäran paketeras dina programspecifika parametrar i begärandetexten. Förutom några av de tidigare nämnda parametrarna (tillsammans med andra nya) skickar du följande:

   • code: Den här frågeparametern innehåller den auktoriseringskod som du fick i steg 1.

   • client_secret: Du behöver bara den här parametern om klienten har konfigurerats som ett webbprogram. Det här är samma hemlighets-/nyckelvärde som du genererade tidigare i klientregistreringen.

Bevilja klientautentiseringsuppgifter (icke-interaktiva klienter)

Det här beviljandet används endast av webbklienter, vilket gör att programmet kan komma åt resurser direkt (ingen användardelegering) med hjälp av klientens autentiseringsuppgifter, som tillhandahålls vid registreringen. Beviljandet används vanligtvis av icke-interaktiva klienter (inget användargränssnitt) som körs som en tjänst eller daemon. Den kräver bara /token slutpunkten för att hämta en åtkomsttoken.

Interaktionen mellan klient och resurs för det här bidraget liknar steg 2 i beviljandet av auktoriseringskoden. Mer information om formatet för HTTPS POST-begäran till /token slutpunkten och exempel på begäran/svar finns i avsnittet "Hämta en token" i Microsofts identitetsplattform och OAuth 2.0-klientens autentiseringsuppgifter.

Montera begärandemeddelandet

De flesta programmeringsspråk eller ramverk och skriptmiljöer gör det enkelt att sätta ihop och skicka begärandemeddelandet. De tillhandahåller vanligtvis en webb-/HTTP-klass eller ETT API som abstraherar skapandet eller formateringen av begäran, vilket gör det enklare att skriva klientkoden (HttpWebRequestklassen i .NET Framework, till exempel). För korthet, och eftersom merparten av uppgiften hanteras åt dig, täcker det här avsnittet bara de viktiga elementen i begäran.

URI för förfrågan

Eftersom känslig information överförs och tas emot kräver alla REST-begäranden HTTPS-protokollet för URI-schemat, vilket ger begäran och svaret en säker kanal. Informationen (dvs. Microsoft Entra auktoriseringskod, åtkomst/ägartoken och känsliga begärande-/svarsdata) krypteras med ett lägre transportlager, vilket säkerställer meddelandenas integritet.

Resten av tjänstens URI för begäran (värden, resurssökvägen och eventuella obligatoriska frågesträngsparametrar) bestäms av dess relaterade REST API-specifikation. Azure Resource Manager-provider-API:er använder https://management.azure.com/till exempel och den klassiska Azure-distributionsmodellen använder https://management.core.windows.net/. Båda kräver en api-version frågesträngsparameter.

Begärandehuvud

Begärande-URI:n paketeras i meddelandehuvudet för begäran, tillsammans med eventuella ytterligare fält som krävs av tjänstens REST API-specifikation och HTTP-specifikationen. Din begäran kan kräva följande vanliga rubrikfält:

• Authorization: Innehåller OAuth2-ägartoken för att skydda begäran, som hämtades tidigare från Microsoft Entra ID.
• Content-Type: Anges vanligtvis till "application/json" (namn/värdepar i JSON-format) och anger MIME-typen för begärandetexten.
• Host: Domännamnet eller IP-adressen för den server där REST-tjänstslutpunkten finns.

Begärandetext

Som tidigare nämnts är begärandemeddelandetexten valfri, beroende på vilken åtgärd du begär och dess parameterkrav. Om det behövs anger API-specifikationen för den tjänst som du begär också kodningen och formatet.

Begärandetexten avgränsas från rubriken med en tom rad, formaterad i enlighet med Content-Type rubrikfältet. Ett exempel på en "application/json"-formaterad brödtext visas på följande sätt:

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

Skicka begäran

Nu när du har tjänstens begärande-URI och har skapat det relaterade meddelandehuvudet och brödtexten för begäran är du redo att skicka begäran till REST-tjänstslutpunkten.

Du kan till exempel skicka en HTTPS GET-begärandemetod för en Azure Resource Manager-provider med hjälp av fält för begärandehuvud som liknar följande (observera att begärandetexten är tom):

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

<no body>

Och du kan skicka en HTTPS PUT-begärandemetod för en Azure Resource Manager-provider med hjälp av fält för begärandehuvud och brödtext som liknar följande exempel:

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"
}

När du har skickat begäran returneras svarsmeddelanderubriken och den valfria brödtexten.

Bearbeta svarsmeddelandet

Processen avslutas med de sista två av de fem komponenterna.

Bearbeta svaret genom att parsa svarshuvudet och eventuellt svarstexten (beroende på begäran). I HTTPS GET-exemplet i föregående avsnitt använde du slutpunkten /subscriptions för att hämta listan över prenumerationer för en användare. Förutsatt att svaret lyckades bör du få fält för svarshuvud som liknar följande exempel:

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

Och du bör få en svarstext som innehåller en lista över Azure-prenumerationer och deras enskilda egenskaper kodade i JSON-format, ungefär som:

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

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

På samma sätt bör du för HTTPS PUT-exemplet få ett svarshuvud som liknar följande, vilket bekräftar att PUT-åtgärden för att lägga till "ExampleResourceGroup" lyckades:

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

Och du bör få en svarstext som bekräftar innehållet i den nyligen tillagda resursgruppen som kodas i JSON-format, ungefär så här:

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

Precis som med begäran gör de flesta programmeringsspråk och ramverk det enkelt att bearbeta svarsmeddelandet. De returnerar vanligtvis den här informationen till ditt program efter begäran, så att du kan bearbeta den i ett skrivet/strukturerat format. Främst är du intresserad av att bekräfta HTTP-statuskoden i svarshuvudet och parsa svarstexten enligt API-specifikationen (eller fälten Content-Type och Content-Length svarshuvudet).

Asynkrona åtgärder, begränsning och växling

Mönstret Skapa/skicka/bearbeta svar som beskrivs i den här artikeln är synkront och gäller för alla REST-meddelanden. Men vissa tjänster stöder också ett asynkront mönster, vilket kräver ytterligare bearbetning av svarshuvuden för att övervaka eller slutföra den asynkrona begäran. Mer information finns i Spåra asynkrona Azure-åtgärder.

Resource Manager tillämpar en gräns för antalet läs- och skrivbegäranden per timme för att förhindra att ett program skickar för många begäranden. Om programmet överskrider dessa gränser begränsas begäranden. Svarshuvudet innehåller antalet återstående begäranden för ditt omfång. Mer information finns i Begränsa Resource Manager-begäranden.

Vissa liståtgärder returnerar en egenskap som heter nextLink i svarstexten. Du ser den här egenskapen när resultatet är för stort för att returneras i ett svar. Vanligtvis innehåller svaret egenskapen nextLink när liståtgärden returnerar fler än 1 000 objekt. När nextLink inte finns i resultatet är de returnerade resultaten slutförda. När nextLink innehåller en URL är de returnerade resultaten bara en del av den totala resultatuppsättningen.

Svaret är i formatet:

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

Om du vill hämta nästa sida i resultatet skickar du en GET-begäran till URL:en i egenskapen nextLink. URL:en innehåller en fortsättningstoken som anger var du befinner dig i resultatet. Fortsätt att skicka begäranden till nextLink-URL:en tills den inte längre innehåller en URL i de returnerade resultaten.

Återhämtning för Azure-API:er

Azure REST-API:erna är utformade för återhämtning och kontinuerlig tillgänglighet. Kontrollplansåtgärder (begäranden som skickas till management.azure.com) i REST-API:et är:

• Distribuerad mellan regioner. Vissa tjänster är regionala.

• Distribueras över Tillgänglighetszoner (samt regioner) på platser som har flera Tillgänglighetszoner.

• Inte beroende av ett enda logiskt datacenter.

• Tas aldrig ned för underhållsaktiviteter.

Relaterat innehåll

Klart! När du har registrerat ditt Microsoft Entra-program och har en modulär teknik för att hämta en åtkomsttoken och hantera HTTP-begäranden är det ganska enkelt att replikera koden för att dra nytta av nya REST-API:er. Mer information om programregistrering och programmeringsmodellen Microsoft Entra finns i Microsofts identitetsplattform dokumentation.

Information om hur du testar HTTP-begäranden/svar finns i:

• Fiddler. Fiddler är en gratis proxy för felsökning av webbplatser som kan komma åt dina REST-begäranden, vilket gör det enkelt att diagnostisera HTTP-begärans-/svarsmeddelanden.
• JWT.ms, vilket gör det snabbt och enkelt att dumpa anspråken i ägartoken så att du kan verifiera innehållet.