Azure REST API-referencia

Üdvözli az Azure REST API referenciadokumentációja.

A Representational State Transfer (REST) API-k HTTP-műveletek (metódusok) készleteit támogató szolgáltatásvégpontok, amelyek létrehozási, lekérési, frissítési és törlési jogosultságot biztosítanak a szolgáltatás erőforrásaihoz. Ez a cikk végigvezeti a következőn:

  • Azure REST API-k meghívása curl használatával
  • A REST API-kérés-válasz pár alapvető összetevői.
  • Hogyan regisztrálhatja az ügyfélalkalmazást Microsoft Entra ID a REST-kérések védelméhez.
  • A REST-kérések létrehozásának és küldésének, valamint a válasz kezelésének áttekintése.

Tipp

A legtöbb Azure-szolgáltatás REST API-jában vannak olyan ügyfélkódtárak, amelyek natív felületet biztosítanak az Azure-szolgáltatások használatához:

.NETTÓ | Java | | Node.jsPython | Megy | C++

Azure REST API-k meghívása curl használatával

Az alábbi blogbejegyzésben leírt folyamat bemutatja, hogyan hívhat meg egy Azure REST API-t curl használatával. Megfontolhatja a curl felügyelet nélküli szkriptekben való használatát. Például a DevOps automatizálási forgatókönyveiben.

Az Azure REST API meghívása curl használatával

A REST API-kérések/-válaszok összetevői

A REST API-k kérés-válasz párosai öt összetevőt tartalmaznak:

  1. A kérés URI azonosítója, amely a következőkből áll: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Bár a kérés URI azonosítója az üzenet fejlécének részét képezi, itt azért emeljük ki külön, mivel a legtöbb nyelvben és keretrendszerben a kérésüzenettől külön kell beadni.

    • URI-séma: A kérés továbbításához használt protokollt jelzi. Például http vagy https.
    • URI-gazdagép: A REST-szolgáltatásvégpontot futtató kiszolgáló tartománynevét vagy IP-címét adja meg, például graph.microsoft.com.
    • Erőforrás elérési útja: Az erőforrást vagy erőforráscsoportot adja meg, és akár a szolgáltatás által az adott erőforrások kiválasztásához használt több szegmens is tartalmazhat. Például a beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners használatával lekérdezhető egy adott alkalmazás tulajdonosainak listája az alkalmazásgyűjteményben.
    • Lekérdezési sztring (nem kötelező): További egyszerű paramétereket tartalmaz, például az API-verziót vagy az erőforrások kiválasztási kritériumait.
  2. HTTP-kérés üzenetfejlécének mezői:

    • Egy szükséges HTTP-metódus (más néven művelet vagy parancs), amely közli a szolgáltatással, hogy milyen típusú műveletet kér. Az Azure REST API-k támogatják a GET, HEAD, PUT, POST és PATCH metódusokat.
    • További nem kötelező fejlécmezők, a megadott URI azonosítótól és HTTP-metódustól függően. Például egy Engedélyezési fejléc, amely egy tulajdonosi jogkivonatot biztosít, amely a kérelem ügyfél-engedélyezési adatait tartalmazza.
  3. Az URI azonosítót és a HTTP-műveletet támogató, nem kötelező HTTP-kérésüzenettörzs-mezők. Például a POST műveletek MIME-kódolású objektumokat tartalmaznak, amelyek összetett paraméterként adhatók be. A POST és PUT műveletek esetében a törzs MIME-kódolásának típusát is meg kell adnia a Content-type kérésfejlécben. Egyes szolgáltatások megkövetelik egy adott MIME-típus, például az application/json használatát.

  4. HTTP-válasz üzenetfejlécének mezői:

    • HTTP-állapotkód, amely a 2xx sikerkódoktól a 4xx vagy 5xx hibakódokig terjed. Ezek helyett a rendszer visszaadhat a szolgáltatásban definiált állapotkódokat is, ahogy azt az API dokumentációja leírja.
    • A kérésre adott választ támogató további, nem kötelező fejlécmezők, például egy Content-type válaszfejléc.
  5. Nem kötelező HTTP-válasz üzenettörzsének mezői:

    • A MIME-kódolású válaszobjektumok a HTTP-válasz törzsében térnek vissza, mint például a GET metódusra adott, adatokkal visszatérő válaszok. Az ilyen objektumok általában strukturált formában, például JSON vagy XML formátumban térnek vissza a Content-type válaszfejlécben jelzett módon. Ha például hozzáférési jogkivonatot kér Microsoft Entra ID, a rendszer a válasz törzsében adja vissza az elemet, amely access_token egy adatgyűjtemény több név/érték párosított objektumának egyike. Ebben a példában a válaszfejléc Content-Type: application/json is szerepel.

Ügyfélalkalmazás regisztrálása a Microsoft Entra ID

A legtöbb Azure-szolgáltatás (például az Azure Resource Manager-szolgáltatók és a klasszikus üzemi modell) megköveteli, hogy az ügyfélkód érvényes hitelesítő adatokkal hitelesítse magát, mielőtt meghívhatja a szolgáltatás API-ját. A hitelesítést a Microsoft Entra ID koordinálja a különböző szereplők között, és egy hozzáférési jogkivonatot biztosít az ügyfélnek a hitelesítés igazolásaként. Ezt követően a rendszer elküldi a jogkivonatot az Azure-szolgáltatásnak a későbbi REST API-kérések HTTP-engedélyezési fejlécében. A jogkivonat jogcímei információkat is szolgáltatnak a szolgáltatásnak, lehetővé téve az ügyfél érvényesítését és a szükséges engedélyek elvégzését.

Ha olyan REST API-t használ, amely nem használ integrált Microsoft Entra hitelesítést, vagy már regisztrálta az ügyfelet, ugorjon a Kérés létrehozása szakaszra.

Előfeltételek

Az ügyfélalkalmazásnak a Microsoft Entra-bérlőben való regisztrálásával ismerté kell tennie az identitáskonfigurációját a Microsoft Entra ID előtt. Mielőtt regisztrálja az ügyfelet a Microsoft Entra ID, vegye figyelembe a következő előfeltételeket:

  • Ha még nincs Microsoft Entra bérlője, olvassa el a Microsoft Entra-bérlő beállítása című témakört.

  • Az OAuth2 engedélyezési keretrendszerrel összhangban a Microsoft Entra ID kétféle ügyfelet támogat. Mindegyik megértése segít eldönteni, hogy melyik a legmegfelelőbb az Ön forgatókönyvéhez:

    • a web-/bizalmas ügyfelek webkiszolgálón futnak, és hozzáférhetnek a saját identitásuk (például egy szolgáltatás vagy démon) erőforrásaihoz, vagy delegált engedélyt kérhetnek a bejelentkezett felhasználó identitása alatt lévő erőforrások eléréséhez (például egy webalkalmazáshoz). A hozzáférési jogkivonat beszerzéséhez csak egy webes ügyfél tudja biztonságosan fenntartani és bemutatni a saját hitelesítő adatait Microsoft Entra hitelesítés során.
    • natív/nyilvános ügyfelek vannak telepítve és futnak egy eszközön. Az erőforrásokhoz csak delegált engedélyezéssel férhetnek hozzá, és a bejelentkezett felhasználó identitásával szerezhetnek be hozzáférési jogkivonatot a felhasználó nevében.
  • A regisztrációs folyamat két kapcsolódó objektumot hoz létre abban a Microsoft Entra bérlőben, ahol az alkalmazás regisztrálva van: egy alkalmazásobjektumot és egy egyszerű szolgáltatásobjektumot. Az összetevők további hátteréről és azok futásidőben való használatáról az alkalmazás- és szolgáltatásnév-objektumok Microsoft Entra ID című témakörben olvashat.

Most már regisztrálhatja az ügyfélalkalmazást a Microsoft Entra ID.

Ügyfélregisztráció

Az Azure Resource Manager REST API-hoz hozzáférő ügyfél regisztrálásához lásd: Az erőforrásokhoz hozzáférő Microsoft Entra alkalmazás és szolgáltatásnév létrehozása a portál használatával. A cikk (amely a Regisztráció automatizálására szolgáló PowerShell- és CLI-verziókban is elérhető) bemutatja, hogyan:

  • Regisztrálja az ügyfélalkalmazást a Microsoft Entra ID.
  • Állítson be engedélykérelmeket, hogy az ügyfél hozzáférhessen az Azure Resource Manager API-hoz.
  • Konfigurálja az Azure Resource Manager Role-Based Access Control (RBAC) beállításait az ügyfél engedélyezéséhez.

Ha az ügyfél nem egy Azure Resource Manager API-hoz fér hozzá, tekintse meg az alábbiakat:

Most, hogy befejezte az ügyfélalkalmazás regisztrációját, lépjen tovább az ügyfélkódra, ahol létrehozza a REST-kérést, és kezeli a választ.

A kérelem létrehozása

Ez a szakasz a korábban tárgyalt öt összetevő közül az első háromat ismerteti. Először be kell szereznie a hozzáférési jogkivonatot Microsoft Entra ID, amelyet a kérésüzenet fejlécének összeállításához használ.

Hozzáférési jogkivonat beszerzése

Az érvényes ügyfélregisztrációt követően két módon integrálhatja a Microsoft Entra ID a hozzáférési jogkivonat beszerzéséhez:

  • Platform- és nyelvsemleges OAuth2-szolgáltatásvégpontok, amelyeket ebben a cikkben használunk. Az ebben a szakaszban megadott utasítások semmit sem feltételeznek az ügyfél platformjáról vagy nyelvéről/szkriptjéről az OAuth-végpontok Microsoft Entra használatakor. Az egyetlen követelmény, hogy HTTPS-kéréseket küldhet vagy fogadhat Microsoft Entra ID, és elemezheti a válaszüzenetet.
  • A platform- és nyelvspecifikus Microsoft Authentication-kódtárak (MSAL), amely túlmutat a jelen cikk hatókörén. A kódtárak aszinkron burkolókat biztosítanak az OAuth2-végpontkérelmekhez, valamint robusztus jogkivonat-kezelési funkciókat, például gyorsítótárazást és frissítési jogkivonat-kezelést. További információ: A Microsoft Authentication Library (MSAL) áttekintése.

Az ügyfél hitelesítéséhez és a hozzáférési jogkivonat beszerzéséhez használt két Microsoft Entra végpontot OAuth2-nek /authorize és /token végpontoknak nevezzük. A használatuk az alkalmazás regisztrációjától és az OAuth2 engedélyezési engedélyezési folyamat típusától függ, amelyet az alkalmazás futásidejű támogatásához szükséges. A cikk alkalmazásában feltételezzük, hogy az ügyfél a következő engedélyezési engedélyezési folyamatok egyikét használja: engedélyezési kódot vagy ügyfél-hitelesítő adatokat. A többi szakaszban használt hozzáférési jogkivonat beszerzéséhez kövesse a forgatókönyvnek leginkább megfelelő folyamat utasításait.

Engedélyezési kód megadása (interaktív ügyfelek)

Ezt az engedélyt a webes és a natív ügyfelek is használják, és hitelesítő adatokat igényelnek egy bejelentkezett felhasználótól az erőforrás-hozzáférés ügyfélalkalmazáshoz való delegálásához. A végpont használatával /authorize szerez be egy engedélyezési kódot (válaszul a felhasználói bejelentkezésre/hozzájárulásra), majd a végpontot a /token hozzáférési jogkivonat engedélyezési kódjának cseréjére.

  1. Először is az ügyfélnek meg kell kérnie egy engedélyezési kódot Microsoft Entra ID. A végpontra /authorize irányuló HTTPS GET-kérés formátumával, valamint a példakérési/válaszüzenetekkel kapcsolatos részletekért lásd: Engedélyezési kód kérése. Az URI a következő lekérdezési sztringparamétereket tartalmazza, amelyek az ügyfélalkalmazásra vonatkoznak:

    • client_id: Az ügyfélalkalmazáshoz a regisztráció során hozzárendelt GUID, más néven alkalmazásazonosító.

    • redirect_uri: Az ügyfélalkalmazás regisztrációja során megadott válasz-átirányítási URI-k egyikének URL-kódolású verziója. A megadott értéknek pontosan meg kell egyeznie a regisztrációs értékével.

    • resource: A meghívni kívánt REST API által megadott URL-kódolású azonosító URI-ja. A webes/REST API-k (más néven erőforrás-alkalmazások) egy vagy több alkalmazásazonosító URI-t tehetnek elérhetővé a konfigurációjukban. Például:

      • Az Azure Resource Manager szolgáltatói (és klasszikus üzemi modell) API-k a következőt használjákhttps://management.core.windows.net/: .
      • Egyéb erőforrásokért tekintse meg az API dokumentációját vagy az erőforrás-alkalmazás konfigurációját a Azure Portal. További információt a identifierUris Microsoft Graph API alkalmazásobjektum tulajdonságában talál.

    A végpontra /authorize irányuló kérés először elindít egy bejelentkezési kérést a felhasználó hitelesítéséhez. A visszakapott válasz átirányításként (302) érkezik a megadott redirect_uriURI-ra. A válaszfejléc üzenete egy location mezőt tartalmaz, amely tartalmazza az átirányítási URI-t, majd egy lekérdezési paramétert code . A code paraméter tartalmazza a 2. lépéshez szükséges engedélyezési kódot.

  2. Ezután az ügyfélnek be kell váltania az engedélyezési kódot egy hozzáférési jogkivonathoz. A végpontra irányuló HTTPS POST-kérés formátumával, valamint a /token kérelmek/válaszok példáival kapcsolatban lásd: Hozzáférési jogkivonat kérése. Mivel ez egy POST-kérés, az alkalmazásspecifikus paramétereket a kérelem törzsébe kell csomagolni. A korábban említett paraméterek mellett (a többi új paraméterrel együtt) a következőt fogja átadni:

    • code: Ez a lekérdezési paraméter az 1. lépésben beszerzett engedélyezési kódot tartalmazza.

    • client_secret: Erre a paraméterre csak akkor van szüksége, ha az ügyfél webalkalmazásként van konfigurálva. Ez ugyanaz a titkos kulcs/kulcs érték, amelyet korábban létrehozott az ügyfélregisztrációban.

Ügyfél hitelesítő adatainak megadása (nem interaktív ügyfelek)

Ezt az engedélyt csak webes ügyfelek használják, így az alkalmazás közvetlenül (felhasználói delegálás nélkül) férhet hozzá az erőforrásokhoz az ügyfél regisztrációkor megadott hitelesítő adataival. Az engedélyt általában szolgáltatásként vagy démonként futó nem interaktív ügyfelek (felhasználói felület nélkül) használják. Csak a /token végpontnak kell hozzáférési jogkivonatot beszereznie.

Az ehhez a támogatáshoz tartozó ügyfél-/erőforrás-interakciók hasonlóak az engedélyezési kód megadásának 2. lépéséhez. A végpontra irányuló HTTPS POST-kérés formátumáról, valamint a /token kérés/válasz példákról a "Jogkivonat lekérése" című szakaszban talál további információt a Microsoft Identitásplatform és az OAuth 2.0 ügyfél hitelesítő adatainak folyamatában.

A kérelemüzenet összeállítása

A legtöbb programozási nyelv, keretrendszer és szkriptkörnyezet megkönnyíti a kérésüzenet összeállítását és elküldését. Ezek általában egy webes/HTTP-osztályt vagy API-t biztosítanak, amely absztrakciót végez a kérés létrehozásához vagy formázásához, megkönnyítve az ügyfélkód írását (például a HttpWebRequest .NET-keretrendszer osztályát). A rövidség kedvéért, és mivel a feladat nagy része az Ön számára van kezelve, ez a szakasz csak a kérés fontos elemeit ismerteti.

Kérés URI-ja

Mivel a bizalmas adatok továbbítása és fogadása folyamatban van, minden REST-kéréshez az URI-séma HTTPS-protokollja szükséges, amely biztonságos csatornát ad a kérésnek és a válasznak. Az információkat (azaz a Microsoft Entra engedélyezési kódot, a hozzáférési/tulajdonosi jogkivonatot és a bizalmas kérési/válaszadatokat) egy alacsonyabb átviteli réteg titkosítja, biztosítva az üzenetek védelmét.

A szolgáltatás kérési URI-jának fennmaradó részét (a gazdagépet, az erőforrás-útvonalat és a szükséges lekérdezési sztringparamétereket) a kapcsolódó REST API-specifikáció határozza meg. Az Azure Resource Manager szolgáltatói API-k például a , a klasszikus Azure-beli üzembehelyezési modell pedig a -t használjákhttps://management.azure.com/https://management.core.windows.net/. Mindkettőhöz lekérdezési sztring paraméter szükséges api-version .

Kérelem fejléce

A kérelem URI-ja a kérelemüzenet fejlécében található, valamint a szolgáltatás REST API-specifikációja és a HTTP-specifikáció által megkövetelt további mezők. Előfordulhat, hogy a kéréshez a következő gyakori fejlécmezők szükségesek:

  • Authorization: Az OAuth2 tulajdonosi jogkivonatát tartalmazza a kérés védelméhez, ahogy azt korábban Microsoft Entra ID.
  • Content-Type: Általában "application/json" (név/érték párok JSON formátumban) értékre van állítva, és megadja a kérelemtörzs MIME-típusát.
  • Host: Annak a kiszolgálónak a tartományneve vagy IP-címe, ahol a REST szolgáltatásvégpont üzemel.

A kérés törzse

Ahogy korábban említettük, a kérés üzenettörzse nem kötelező, a kért művelettől és a paraméterkövetelményektől függően. Ha szükséges, a kért szolgáltatás API-specifikációja a kódolást és a formátumot is meghatározza.

A kérelemtörzset a fejlécmezőnek megfelelően formázott üres sor választja el a Content-Type fejléctől. Egy példa egy "application/json" formátumú törzsre a következőképpen jelenik meg:

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

A kérés elküldése

Most, hogy már rendelkezik a szolgáltatás kérési URI-jával, és létrehozta a kapcsolódó kérésüzenet fejlécét és törzsét, készen áll arra, hogy elküldje a kérést a REST szolgáltatásvégpontnak.

Előfordulhat például, hogy https GET kérésmetódust küld egy Azure Resource Manager-szolgáltatónak a következőhöz hasonló kérelemfejlécmezők használatával (vegye figyelembe, hogy a kérelem törzse üres):

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

<no body>

Az Azure Resource Manager-szolgáltatóhoz pedig elküldhet EGY HTTPS PUT kérésmetódust a következő példához hasonló kérelemfejléc és törzsmezők használatával:

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

A kérés elküldése után a rendszer visszaadja a válaszüzenet fejlécét és az opcionális törzset.

A válaszüzenet feldolgozása

A folyamat az öt összetevő közül az utolsó kettővel fejeződik be.

A válasz feldolgozásához elemezni kell a válasz fejlécét és szükség esetén a válasz törzsét (a kéréstől függően). Az előző szakaszban található HTTPS GET példában az /subscriptions végpontot használta a felhasználó előfizetéseinek listájának lekéréséhez. Feltételezve, hogy a válasz sikeres volt, a következő példához hasonló válaszfejlécmezőket kell kapnia:

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

Egy választörzset kell kapnia, amely tartalmazza az Azure-előfizetések listáját és azok egyéni tulajdonságait JSON formátumban, a következőhöz hasonló módon:

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

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

Hasonlóképpen, a HTTPS PUT példa esetében a következőhöz hasonló válaszfejlécet kell kapnia, amely megerősíti, hogy a "ExampleResourceGroup" hozzáadására szolgáló PUT művelet sikeres volt:

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

Egy választörzset kell kapnia, amely megerősíti az újonnan hozzáadott erőforráscsoport JSON formátumban kódolt tartalmát a következőhöz hasonló módon:

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

A kéréshez hasonlóan a legtöbb programozási nyelv és keretrendszer megkönnyíti a válaszüzenet feldolgozását. Ezeket az adatokat általában a kérést követően küldik vissza az alkalmazásnak, így azokat gépelt/strukturált formátumban lehet feldolgozni. Elsősorban a válaszfejléc HTTP-állapotkódját szeretné megerősíteni, és elemezni a válasz törzsét az API-specifikációnak (vagy a Content-Type válaszfejléc Content-Length mezőinek) megfelelően.

Aszinkron műveletek, szabályozás és lapozás

A cikkben tárgyalt létrehozási/küldési/folyamatválasz-minta szinkron, és az összes REST-üzenetre érvényes. Egyes szolgáltatások azonban támogatják az aszinkron mintát is, amely a válaszfejlécek további feldolgozását igényli az aszinkron kérés monitorozásához vagy befejezéséhez. További információ: Aszinkron Azure-műveletek nyomon követése.

Resource Manager korlátozza az olvasási és írási kérelmek számát óránként, hogy megakadályozza, hogy egy alkalmazás túl sok kérést küldjön. Ha az alkalmazás túllépi ezeket a korlátokat, a kérelmek szabályozva lesznek. A válaszfejléc tartalmazza a hatókör hátralévő kéréseinek számát. További információ: A Resource Manager-kérések szabályozása.

Egyes listaműveletek egy nevű nextLink tulajdonságot ad vissza a válasz törzsében. Ez a tulajdonság akkor jelenik meg, ha az eredmények túl nagyok ahhoz, hogy egyetlen válaszban térjenek vissza. A válasz általában tartalmazza a nextLink tulajdonságot, ha a listaművelet több mint 1000 elemet ad vissza. Ha a nextLink nem jelenik meg az eredmények között, a visszaadott eredmények befejeződnek. Ha a nextLink url-címet tartalmaz, a visszaadott eredmények csak a teljes eredményhalmaz részei.

A válasz formátuma:

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

Az eredmények következő oldalának lekéréséhez küldjön EGY GET kérést a nextLink tulajdonság URL-címére. Az URL-cím tartalmaz egy folytatási jogkivonatot, amely jelzi, hogy hol van az eredmények között. Folytassa a kérések küldését a nextLink URL-címre, amíg az már nem tartalmaz URL-címet a visszaadott eredményekben.

Az Azure API-k rugalmassága

Az Azure REST API-kat rugalmasságra és folyamatos rendelkezésre állásra tervezték. A vezérlősík műveletei (management.azure.com küldött kérések) a REST API-ban a következők:

  • Régiók között elosztva. Egyes szolgáltatások regionálisak.

  • Több Availability Zones rendelkező helyeken Availability Zones (és régiók között) elosztva.

  • Nem függ egyetlen logikai adatközponttól.

  • Soha nem vették le karbantartási tevékenységekre.

Ennyi az egész. Miután regisztrálta a Microsoft Entra alkalmazást, és moduláris technikával rendelkezik a hozzáférési jogkivonatok beszerzéséhez és a HTTP-kérések kezeléséhez, elég könnyű replikálni a kódot, hogy kihasználhassa az új REST API-kat. Az alkalmazásregisztrációval és a Microsoft Entra programozási modellel kapcsolatos további információkért tekintse meg a Microsoft Identitásplatform dokumentációját.

A HTTP-kérések/válaszok teszteléséről a következő témakörben olvashat bővebben:

  • Fiddler. A Fiddler egy ingyenes webes hibaelhárító proxy, amely el tudja fogni a REST-kéréseket, így könnyen diagnosztizálhatóak a használatával a HTTP kérés- és válaszüzenetek.
  • JWT.ms, amely gyors és egyszerűvé teszi a jogcímek memóriaképét a tulajdonosi jogkivonatban, így ellenőrizheti azok tartalmát.