Azure REST API-referencia

Üdvözli az Azure REST API-referencia.

A Representational State Transfer (REST) API-k olyan szolgáltatásvégpontok, amelyek HTTP-műveletek (metódusok) készleteit támogatják, amelyek létrehozási/lekérési/frissítési/törlési hozzáférést biztosítanak a szolgáltatás erőforrásaihoz. Az alábbi szakaszok végigvezetik a következő lépéseken:

• A REST API-kérés-/válaszpárok alapvető összetevői
• Ügyfélalkalmazás regisztrálása az Azure Active Directoryban (Azure AD) 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

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

A REST API-kérés-válasz párok 5 összetevőre oszthatók:

1. A kérés URI azonosítója, amely a következőkből áll: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Vegye figyelembe, hogy ezt itt külön hívjuk meg, mivel a legtöbb nyelv/keretrendszer megköveteli, hogy ezt a kérésüzenettől elkülönítve adja át, de ez valójában szerepel a kérés üzenetfejlécében.
   • URI-séma: a kérés továbbításához használt protokollt jelöli. Például http vagy https.
   • URI-gazdagép: annak a kiszolgálónak a tartományneve vagy IP-címe, ahol a REST-szolgáltatásvégpont üzemel, például graph.microsoft.com
   • Erőforrás elérési útja: meghatározza az erőforrást vagy erőforrásgyűjteményt, amely a szolgáltatás által az erőforrások kiválasztásához használt több szegmenst is tartalmazhat. Például: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners használható egy adott alkalmazás tulajdonosainak listájának lekérdezésére az alkalmazásgyűjteményben.
   • Lekérdezési sztring (nem kötelező): további egyszerű paraméterek megadására szolgál, például az API-verzióra, az erőforrás-kiválasztási feltételekre stb.
2. HTTP-kérelem üzenetfejlécmező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.
   • A megadott URI és HTTP-metódus által megkövetelt további fejlécmezők megadása nem kötelező. 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. A POST-műveletek például összetett paraméterekként átadott MIME-kódolású objektumokat tartalmaznak. A POST/PUT műveletek esetében a kérelem fejlécében meg kell adni a Content-type törzs MIME kódolási típusát is. Vegye figyelembe, hogy egyes szolgáltatásokhoz egy adott MIME-típust kell használnia, például application/json: .
4. HTTP-válaszüzenet fejlécmezői
   • EGY HTTP-állapotkód, amely a 2xx sikerességi kódoktól a 4xx/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.
   • Opcionális további fejlécmezők, ha a kérés válaszának támogatásához szükséges, például válaszfejléc Content-type .
5. Nem kötelező HTTP-válaszüzenet törzsmezői
   • A MIME-kódolású válaszobjektumok a HTTP-válasz törzsében is visszaadhatók, például egy ADATOKAT visszaadó GET metódus válaszában. Ezek általában strukturált formátumban lesznek visszaadva JSON-ként vagy XML-ként, a Content-type válaszfejléc által jelzett módon. Ha például hozzáférési jogkivonatot kér Azure AD, 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 egy válaszfejléc Content-Type: application/json is megjelenik.

Ügyfélalkalmazás regisztrálása a Azure AD

A legtöbb Azure-szolgáltatáshoz (például az Azure Resource Manager szolgáltatókhoz és a klasszikus Service Management API-khoz) az ügyfélkódnak érvényes hitelesítő adatokkal kell hitelesítenie magát, mielőtt meghívhatja a szolgáltatás API-ját. A hitelesítést a Azure AD koordinálja a különböző szereplők között, amely hozzáférési jogkivonatot biztosít az ügyfélnek a hitelesítés/engedélyezés bizonyítékaként. A rendszer ezután elküldi a jogkivonatot az Azure-szolgáltatásnak az összes további REST API-kérés HTTP-engedélyezési fejlécében. A jogkivonat jogcímei információkat is szolgáltatnak a szolgáltatásnak, így ellenőrizheti az ügyfelet, és elvégezheti a szükséges engedélyeket.

Ha olyan REST API-t használ, amely nem használ integrált Azure AD-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 futtatás előtt ismertnek kell lennie az identitáskonfigurációval Azure AD, ha regisztrálja azt egy Azure AD-bérlőben. Az alábbiakban felsoroljuk azokat az elemeket, amelyeket figyelembe kell venni, mielőtt regisztrálja az ügyfelet Azure AD:

• Ha még nincs Azure AD-bérlője, tekintse meg az Azure Active Directory-bérlő beszerzését ismertető cikket.
• Az OAuth2 engedélyezési keretrendszer szerint a Azure AD 2 ügyféltípust támogat. Ezek megértése segít eldönteni, hogy melyik a legmegfelelőbb az Ön forgatókönyvéhez:
  • A web-/bizalmas ügyfelek (amelyek webkiszolgálón futnak) hozzáférhetnek a saját identitásuk (azaz szolgáltatás/démon) erőforrásaihoz, vagy delegált engedélyt kaphatnak a bejelentkezett felhasználó identitása alatt lévő erőforrások eléréséhez (azaz: webalkalmazás). Csak a webes ügyfél képes biztonságosan fenntartani és bemutatni a saját hitelesítő adatait Azure AD hitelesítés során a hozzáférési jogkivonat beszerzéséhez.
  • A natív/nyilvános ügyfelek (amelyek egy eszközön vannak telepítve/futnak) csak delegált engedélyezés alatt álló erőforrásokhoz férhetnek hozzá a bejelentkezett felhasználó identitásával, hogy hozzáférési jogkivonatot szerezzenek be a felhasználó nevében.
• A regisztrációs folyamat 2 kapcsolódó objektumot hoz létre abban a Azure AD bérlőben, ahol az alkalmazás regisztrálva van: egy alkalmazásobjektumot és egy szolgáltatásnév-objektumot. Az összetevőkkel és azok futásidőben való használatával kapcsolatos további háttérért tekintse át az Azure Active Directory alkalmazás- és szolgáltatásnév-objektumait ismertető cikket.

Most már készen áll arra, hogy regisztrálja az ügyfélalkalmazást a Azure AD.

Ügyfélregisztráció

Ha olyan ügyfelet szeretne regisztrálni, amely hozzáfér egy Azure Resource Manager REST API-hoz, olvassa el a Portál használata Active Directory-alkalmazás és szolgáltatásnév létrehozásához című témakört, amely képes hozzáférni az erőforrásokhoz a részletes regisztrációs utasításokért. Ez a cikk (amely a PowerShell és a cli-verziókban is elérhető a regisztráció automatizálásához) a következőket mutatja be:

• az ügyfélalkalmazás regisztrálása a Azure AD
• engedélykérések beállítása, hogy az ügyfél hozzáférhessen az Azure Resource Manager API-hoz
• az Azure Resource Manager szerepköralapú Access Control (RBAC) beállításainak konfigurálása az ügyfél engedélyezéséhez

Az összes többi ügyfél esetében lásd: Alkalmazások integrálása az Azure Active Directoryval. Ez a cikk bemutatja, hogyan:

• regisztrálja az ügyfélalkalmazást a Azure AD az "Alkalmazás hozzáadása" szakaszban
• hozzon létre egy titkos kulcsot (ha webes ügyfelet regisztrál), az "Alkalmazás frissítése" szakaszban
• engedélykérések hozzáadása az API által megkövetelt módon az "Alkalmazás frissítése" szakaszban

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

A kérés létrehozása

Ez a szakasz a korábban tárgyalt 5 összetevő közül az első 3-at ismerteti. Először be kell szereznünk a hozzáférési jogkivonatot Azure AD, amelyet a kérésüzenet fejlécének összeállításához fogunk használni.

Hozzáférési jogkivonat beszerzése

Ha már rendelkezik érvényes ügyfélregisztrációval, a hozzáférési jogkivonat beszerzéséhez alapvetően két módon integrálható a Azure AD:

• Azure AD platform-/nyelvsemleges OAuth2-szolgáltatásvégpontjai, amelyeket használni fogunk. Az Ön által használt Azure REST API-végpontokhoz hasonlóan az ebben a szakaszban található utasítások sem feltételezik az ügyfél platformját vagy nyelvét/szkriptjét a Azure AD végpontok használatakor; csak arra, hogy HTTPS-kéréseket küldjön/fogadjon Azure AD,és elemezhesse a válaszüzenetet.
• A platform-/nyelvspecifikus Microsoft Authentication-kódtárak (MSAL). 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 részletekért, beleértve a referenciadokumentációt, a kódtár letöltését és a mintakódot, tekintse meg a Microsoft Hitelesítési kódtárak című témakört.

Az ügyfél hitelesítéséhez és a hozzáférési jogkivonat beszerzéséhez használt 2 Azure AD 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 folyamat típusától függ, amely az alkalmazás futásidőben történő 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 fogja használni: engedélyezési kód vagy ügyfél hitelesítő adatai. A többi szakaszban használni kívánt hozzáférési jogkivonat beszerzéséhez kövesse a forgatókönyvnek leginkább megfelelő útmutatót.

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

Ezt a jogosultságot webes és natív ügyfelek is használhatják, és egy bejelentkezett felhasználó hitelesítő adataira van szükség 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. Az ügyfélnek először meg kell kérnie egy engedélyezési kódot Azure AD. A végpontra irányuló HTTPS GET-kérés /authorize formátumával, valamint a kérési/válaszüzenetekkel kapcsolatos részletekért lásd: Engedélyezési kód kérése. Az URI lekérdezési sztringparamétereket fog tartalmazni, beleértve az ügyfélalkalmazásra jellemző alábbiakat:

   • client_id - más néven alkalmazásazonosító, ez az ügyfélalkalmazáshoz rendelt GUID, amikor regisztrált a fenti szakaszban

   • redirect_uri - az ügyfélalkalmazás regisztrációja során megadott válasz-/átirányítási URI-k URL-kódolású verziója. Vegye figyelembe, hogy az átadott értéknek pontosan meg kell egyeznie a regisztrációval!

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

     • Az Azure Resource Manager szolgáltatói (és klasszikus szolgáltatáskezelési) API-k használatahttps://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 részletekért lásd a identifierUris Azure AD alkalmazásobjektum tulajdonságát is.

   A végpontra /authorize irányuló kérés először elindít egy bejelentkezési kérést a végfelhasználó hitelesítéséhez. A visszakapott válasz átirányításként (302) érkezik a megadott URI-ra.redirect_uri A válaszfejléc üzenete tartalmaz egy location mezőt, amely tartalmazza az átirányítási URI-t, majd egy code lekérdezési paramétert, amely 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. Lásd : Hozzáférési jogkivonat kérése az engedélyezési kód használatával a végpontra /token irányuló HTTPS POST-kérés formátumával, valamint példakérési/válaszüzenetekkel. Mivel ez egy POST-kérés, ezúttal az alkalmazásspecifikus paramétereket fogja csomagolni a kérelem törzsébe. A fent említettek mellett (a többi újkal együtt) a következőt fogja átadni:

   • code - ez az a lekérdezési paraméter, amely az 1. lépésben beszerzett engedélyezési kódot tartalmazza.
   • client_secret – erre a paraméterre csak akkor lesz 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álhatjá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 saját hitelesítő adataival, amelyek a regisztrációkor vannak megadva. Általában démonként/szolgáltatásként futó nem interaktív ügyfelek (felhasználói felület nélkül) használják, és 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 nagyon 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 /token formátumáról és a példakérési/válaszüzenetekről a Szolgáltatás szolgáltatásba irányuló hívások ügyfél-hitelesítő adatokkal című szakaszának "Hozzáférési jogkivonat kérése" szakaszában olvashat.

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

Vegye figyelembe, hogy a legtöbb programozási nyelv/keretrendszer és szkriptelési kö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/formázásához, megkönnyítve az ügyfélkód írását (például: a HttpWebRequest osztályt a .NET-keretrendszer). A rövidség kedvéért csak a kérés fontos elemeit fedjük le, tekintettel arra, hogy ennek nagy részét az Ön számára kezeljük.

Kérés URI-ja

Minden biztonságos REST-kéréshez szükség van az URI-sémához tartozó HTTPS protokollra, amely biztonságos csatornával biztosítja a kérést és a választ, mivel a bizalmas információk továbbítása/fogadása történik. Ezeket az információkat (azaz a Azure AD engedélyezési kódot, a hozzáférési/tulajdonosi jogkivonatot, 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 klasszikus Azure Service Management API-kat használjákhttps://management.azure.com/https://management.core.windows.net/, mindkettőhöz lekérdezési sztringparaméter api-version szükséges stb.

Kérelem fejléce

A kérés URI-ja a kérés üzenetfejlécében lesz csomagolva, valamint a szolgáltatás REST API-specifikációja és a HTTP-specifikáció által meghatározott további mezőkkel együtt. Az alábbiakban néhány gyakori fejlécmezőre lehet szüksége a kérésben:

• Authorization: tartalmazza az OAuth2 tulajdonosi jogkivonatot a kérés védelméhez, amint azt korábban Azure AD
• Content-Type: általában az "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: ez 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 is megadja a kódolást és a formátumot.

A kérelemtörzset egy üres sor választja el a fejléctől, a Content-Type fejlécmezőnként kell formázni. 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/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 egy Azure-Resource Manager-szolgáltató HTTPS GET kérési metódusa az alábbihoz hasonló kérelemfejlécmezők használatával küldhető el, de figyelje meg, 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>

Egy Azure-Resource Manager-szolgáltató HTTPS PUT kérési metódusa pedig a következőhöz hasonló kérelemfejléc és törzsmezők használatával küldhető el:

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

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

Most befejezzük az 5 összetevő közül az utolsó 2-t.

A válasz feldolgozásához elemeznie kell a válasz fejlécét és opcionálisan a válasz törzsét (a kéréstől függően). A fenti HTTPS GET-példában az /subscriptions végpontot használtuk a felhasználó előfizetéseinek listájának lekéréséhez. Feltételezve, hogy a válasz sikeres volt, a következőhöz hasonló válaszfejlécmezőket kell kapnunk:

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

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

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

Hasonlóképpen, a HTTPS PUT-példa esetében a következőhöz hasonló válaszfejlécet kell kapnunk, 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;

és egy választörzs, 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/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

A kéréshez hasonlóan a legtöbb programozási nyelv/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 ha succsessful, az API-specifikációnak (vagy a Content-TypeContent-Length válaszfejléc mezőinek) megfelelően elemzi a válasz törzsét.

Ennyi az egész! Miután regisztrálta a Azure AD alkalmazást, és a hozzáférési jogkivonatok beszerzésére és a HTTP-kérések létrehozására és feldolgozására szolgáló összetevővel rendelkezik, elég könnyű replikálni a kódot, hogy kihasználhassa az új REST API-k előnyeit.

Kapcsolódó tartalom

• Az alkalmazásregisztrációval és a Azure AD programozási modellel kapcsolatos további információkért lásd: Microsoft Identitásplatform (Azure Active Directory fejlesztőknek), beleértve a HowTo és a QuickStart cikkek átfogó indexét és a mintakódot.
• A HTTP-kérések/válaszok teszteléséhez tekintse meg a következőt:
  • Fiddler. A Fiddler egy ingyenes webes hibakeresési proxy, amely képes elfogni a REST-kéréseket, így könnyen diagnosztizálhatja a HTTP-kéréseket és a válaszüzeneteket.
  • JWT Dekóder és JWT.io, amelyek segítségével gyorsan és egyszerűen kiírhatja a jogcímeket a tulajdonosi jogkivonatba, így ellenőrizheti azok tartalmát.

Kérjük, használja az ebben a cikkben szereplő LiveFyre megjegyzések szakaszt, hogy visszajelzést nyújtson, és segítsen nekünk a tartalom finomításában és alakításában.