Share via

Azure REST API-referens

  • Artikel

Välkommen till Azure REST API-referensen.

REST-API:er (Representational State Transfer) är tjänstslutpunkter som stöder uppsättningar av HTTP-åtgärder (metoder), som ger åtkomst till tjänstens resurser för att skapa/hämta/uppdatera/ta bort. Avsnitten nedan vägleder dig genom:

  • De grundläggande komponenterna i ett REST API-begäran/svar-par
  • Så här registrerar du klientprogrammet med Azure Active Directory (Azure AD) för att skydda dina REST-begäranden
  • Översikt över att skapa och skicka en REST-begäran och hantera svaret

Anteckning

De flesta REST-API:er för Azure-tjänsten har ett motsvarande klient-SDK-bibliotek som hanterar mycket av klientkoden åt dig. Se:

SDK för Azure .NET
Azure Java SDK
Azure CLI 2.0 SDK

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

Ett REST API-begäran/svarspar kan delas upp i 5 komponenter:

  1. Aktuell begärande-URI, som består av: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Observera att vi anropar detta separat här, eftersom de flesta språk/ramverk kräver att du skickar detta separat från begärandemeddelandet, men det ingår faktiskt i meddelandehuvudet för begäran.
    • URI-schema: anger det protokoll som används för att överföra begäran. Exempel: http eller https.
    • URI-värd: domännamnet eller IP-adressen för den server där REST-tjänstslutpunkten finns, till exempel graph.microsoft.com
    • Resurssökväg: anger resursen eller resurssamlingen, 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 fråga listan över ägare av ett visst program i programsamlingen.
    • Frågesträng (valfritt): används för att tillhandahålla ytterligare enkla parametrar, till exempel API-version, kriterier för resursval osv.
  2. Rubrikfält för HTTP-begärandemeddelande
    • 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 rubrikfält som krävs av angiven URI och HTTP-metod. 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. POST-åtgärder innehåller till exempel MIME-kodade objekt som skickas som komplexa parametrar. MIME-kodningstypen för brödtexten bör också anges i Content-type begärandehuvudet för POST/PUT-åtgärder. Observera att vissa tjänster kräver att du använder en viss MIME-typ, till exempel application/json.
  4. Rubrikfält för HTTP-svarsmeddelande
    • En HTTP-statuskod som sträcker sig från 2xx lyckade koder till 4xx/5xx-felkoder. Som alternativ kan också en tjänstedefinierad statuskod returneras, i enlighet med beskrivningen i API-dokumentationen.
    • Valfria ytterligare rubrikfält som krävs för att stödja begärans svar, till exempel ett Content-type svarshuvud.
  5. Valfria brödtextfält för HTTP-svarsmeddelande
    • MIME-kodade svarsobjekt kan returneras i HTTP-svarstexten, till exempel ett svar från en GET-metod som returnerar data. Normalt returneras dessa i ett strukturerat format som JSON eller XML, vilket anges av svarshuvudet Content-type . När du till exempel begär en åtkomsttoken från Azure AD returneras den i svarstexten som elementet access_token , ett av flera länkade namn-/värdeobjekt i en datasamling. I det här exemplet inkluderas även en svarsrubrik Content-Type: application/json för .

Registrera klientprogrammet med Azure AD

De flesta Azure-tjänster (till exempel Azure Resource Manager-leverantörer och klassiska Service Management-API:er) kräver att klientkoden autentiseras med giltiga autentiseringsuppgifter innan du kan anropa tjänstens API. Autentiseringen samordnas mellan de olika aktörerna av Azure AD, vilket ger klienten en åtkomsttoken som bevis på autentiseringen/auktoriseringen. Token skickas sedan till Azure-tjänsten i HTTP-auktoriseringshuvudet för alla 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 Azure AD-autentisering, eller om du redan har registrerat klienten, kan du gå vidare till avsnittet Skapa begäran.

Förutsättningar

Klientprogrammet måste göra identitetskonfigurationen känd för att Azure AD före körning genom att registrera den i en Azure AD klientorganisation. Nedan visas en lista över objekt att överväga innan du registrerar klienten med Azure AD:

  • Om du inte har någon Azure AD klientorganisation än kan du läsa Hämta en Azure Active Directory-klientorganisation.
  • Enligt OAuth2 Authorization Framework stöder Azure AD 2 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) kan komma åt resurser under antingen sin egen identitet (dvs. tjänst/daemon) eller få delegerad auktorisering för att få åtkomst till resurser under identiteten för den inloggade användaren (dvs. webbapp). Endast en webbklient har möjlighet att på ett säkert sätt underhålla och presentera sina egna autentiseringsuppgifter under Azure AD autentisering för att hämta en åtkomsttoken.
    • interna/offentliga klienter (installerade/körs på en enhet) 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 2 relaterade objekt i den Azure AD klientorganisation där programmet är registrerat: ett programobjekt och ett objekt för tjänstens huvudnamn. Mer bakgrundsinformation om dessa komponenter och hur de används vid körning finns i Program- och tjänstobjekt i Azure Active Directory.

Nu är vi redo att registrera ditt klientprogram med Azure AD.

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 Active Directory-program och tjänstens huvudnamn som har åtkomst till resurser för stegvisa registreringsinstruktioner. Den här artikeln (även tillgänglig i PowerShell- och CLI-versioner för automatisk registrering) visar hur du:

  • registrera klientprogrammet med Azure AD
  • ange behörighetsbegäranden så att klienten får åtkomst till Azure Resource Manager-API:et
  • konfigurera inställningarna för rollbaserad Access Control (RBAC) i Azure Resource Manager för att auktorisera klienten

För alla andra klienter, se Integrera program med Azure Active Directory. Den här artikeln visar hur du:

  • registrera klientprogrammet med Azure AD i avsnittet "Lägga till ett program"
  • skapa en hemlig nyckel (om du registrerar en webbklient) i avsnittet "Uppdatera ett program"
  • lägg till behörighetsbegäranden som krävs av API:et i avsnittet "Uppdatera ett program"

Nu när du har slutfört registreringen av klientprogrammet kan vi gå över till din klientkod, där du skapar REST-begäran och hanterar svaret.

Skapa begäran

Det här avsnittet beskriver de första 3 av de 5 komponenter som vi diskuterade tidigare. Först måste vi hämta åtkomsttoken från Azure AD, som vi kommer att använda när vi monterar meddelandehuvudet för begäran.

Hämta en åtkomsttoken

När du har en giltig klientregistrering finns det i princip två sätt att integrera med Azure AD för att hämta en åtkomsttoken:

  • Azure AD plattforms-/språkneutrala OAuth2-tjänstslutpunkter, vilket är vad vi kommer att använda. Precis som de Azure REST API-slutpunkter du använder gör anvisningarna i det här avsnittet inga antaganden om klientens plattform eller språk/skript när du använder Azure AD slutpunkter. Endast att den kan skicka/ta emot HTTPS-begäranden till/från Azure AD och parsa svarsmeddelandet.
  • Plattforms-/språkspecifika Microsoft Authentication Libraries (MSAL). Biblioteken tillhandahåller asynkrona omslutningar för OAuth2-slutpunktsbegäranden och robusta funktioner för tokenhantering, till exempel hantering av cachelagring och uppdateringstoken. Mer information, inklusive referensdokumentation, nedladdningar av bibliotek och exempelkod finns i Microsoft Authentication Libraries.

De 2 Azure AD 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-auktoriseringsbeviljande flö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 flöden för beviljande av auktorisering: auktoriseringskod eller klientautentiseringsuppgifter. Följ anvisningarna för den som bäst matchar ditt scenario för att hämta den åtkomsttoken som du kommer att använda i de återstående avsnitten.

Beviljande av auktoriseringskod (interaktiva klienter)

Det här beviljandet kan användas av både webbklienter och interna klienter och 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 för en åtkomsttoken.

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

    • client_id – även kallat ett program-ID, det här är det GUID som tilldelats klientprogrammet när du registrerade dig i avsnittet ovan

    • redirect_uri – en URL-kodad version av [en av] svars-/omdirigerings-URI:er som angavs under registreringen av klientprogrammet. Observera att det värde som du skickar måste matcha exakt din registrering!

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

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

    Begäran till /authorize slutpunkten utlöser först en inloggningsprompt för att autentisera slutanvä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 som 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. Se Använd auktoriseringskoden för att begära en åtkomsttoken för mer information om formatet för HTTPS POST-begäran till /token slutpunkten och exempel på begärande-/svarsmeddelanden. Eftersom det här är en POST-begäran paketeras dina programspecifika parametrar i begärandetexten den här gången. Förutom några av de som nämns ovan (tillsammans med andra nya), kommer du att passera :

    • code – det här är frågeparametern som 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 hemliga/viktiga värde som du genererade tidigare i klientregistreringen.

Bevilja klientautentiseringsuppgifter (icke-interaktiva klienter)

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

Klient-/resursinteraktionerna för det här bidraget liknar steg 2 i beviljandet av auktoriseringskoden. Se avsnittet "Begär en åtkomsttoken" i Tjänst-till-tjänst-anrop med klientautentiseringsuppgifter för information om formatet för HTTPS POST-begäran till /token slutpunkten och exempel på begärande-/svarsmeddelanden.

Montera begärandemeddelandet

Observera att de flesta programmeringsspråk/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/formateringen av begäran, vilket gör det enklare att skriva klientkoden (t.ex. klassen HttpWebRequest i .NET Framework). I korthet kommer vi endast att ta upp de viktiga delarna i begäran, eftersom det mesta av detta kommer att hanteras åt dig.

URI för förfrågan

Alla skyddade REST-begäranden kräver HTTPS-protokollet för URI-schemat, vilket ger begäran och svar med en säker kanal, på grund av att känslig information överförs/tas emot. Den här informationen (dvs. Azure AD auktoriseringskod, åtkomst/ägartoken, 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 den relaterade REST API-specifikationen. Azure Resource Manager-provider-API:er använder https://management.azure.com/till exempel , klassiska Azure Service Management-API:er använder https://management.core.windows.net/, båda kräver en api-version frågesträngsparameter osv.

Begärandehuvud

Begärande-URI:n paketeras i meddelandehuvudet för begäran, tillsammans med eventuella ytterligare fält som bestäms av tjänstens REST API-specifikation och HTTP-specifikationen. Här är några vanliga rubrikfält som du kan behöva i din begäran:

  • Authorization: innehåller OAuth2-ägartoken för att skydda begäran, vilket hämtades tidigare från Azure AD
  • Content-Type: anges vanligtvis till "application/json" (namn/värde-par i JSON-format) och anger MIME-typen för begärandetexten.
  • Host: det här är domännamnet eller IP-adressen för servern 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 och ska formateras per Content-Type rubrikfält. 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/brödtexten för begäran är du redo att skicka begäran till REST-tjänstslutpunkten.

Till exempel kan en HTTPS GET-begärandemetod för en Azure-Resource Manager-provider skickas med hjälp av begärandehuvudfält som liknar följande, men 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 en HTTPS PUT-begärandemetod för en Azure Resource Manager-provider kan skickas med hjälp av fält för begärandehuvud och brödtext som liknar följande:

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

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

Bearbeta svarsmeddelandet

Nu ska vi avsluta med de sista 2 av de 5 komponenterna.

För att bearbeta svaret måste du parsa svarshuvudet och eventuellt svarstexten (beroende på begäran). I HTTPS GET-exemplet ovan använde vi slutpunkten /subscriptions för att hämta listan över prenumerationer för en användare. Förutsatt att svaret lyckades bör vi ta emot svarshuvudfält som liknar följande:

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

och en svarstext som innehåller listan över Azure-prenumerationer och deras enskilda egenskaper kodade i JSON-format, ungefär så här:

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

På samma sätt bör vi 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 en svarstext som bekräftar innehållet i vår nyligen tillagda resursgrupp kodad i JSON-format, ungefär så här:

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

Precis som med begäran gör de flesta programmeringsspråk/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 om den är lyckad parsar du svarstexten enligt API-specifikationen (eller fälten Content-Type och Content-Length svarshuvudet).

Klart! När du har registrerat ditt Azure AD program och en komponentiserad teknik för att hämta en åtkomsttoken och skapa och bearbeta HTTP-begäranden är det ganska enkelt att replikera koden för att dra nytta av nya REST-API:er.

Relaterat innehåll

  • Mer information om programregistrering och programmeringsmodellen Azure AD finns i Microsofts identitetsplattform (Azure Active Directory för utvecklare), inklusive ett omfattande index över howto- och snabbstartsartiklar och exempelkod.
  • Om du vill testa HTTP-begäranden/svar kan du ta en titt
    • Fiddler. Fiddler är en kostnadsfri webbfelsökningsproxy som kan fånga upp dina REST-begäranden, vilket gör det enkelt att diagnostisera HTTP-begäran och svarsmeddelanden.
    • JWT-avkodare och JWT.io, vilket gör det snabbt och enkelt att dumpa anspråken i ägartoken så att du kan verifiera innehållet.

Använd avsnittet LiveFyre-kommentarer som följer den här artikeln för att ge feedback och hjälpa oss att förfina och forma vårt innehåll.