Referenční informace k rozhraní Azure REST API

Vítá vás referenční dokumentace k rozhraní Azure REST API.

Rozhraní REST (Representational State Transfer) API jsou koncové body služby, které podporují sady operací (metod) HTTP, které poskytují přístup k prostředkům služby za účelem jejich vytvoření, načtení, aktualizace nebo odstranění. Tento článek vás provede:

• Jak volat rozhraní Azure REST API pomocí curl
• Základní komponenty dvojice požadavků a odpovědí rozhraní REST API
• Postup registrace klientské aplikace v Microsoft Entra ID za účelem zabezpečení požadavků REST
• Přehled vytvoření a odeslání požadavku REST a zpracování odpovědi

Jak volat rozhraní Azure REST API pomocí curl

Proces popsaný v následujícím blogovém příspěvku ukazuje, jak volat rozhraní Azure REST API pomocí curl. Můžete zvážit použití curl v bezobslužných skriptech. Například ve scénářích automatizace DevOps.

Volání rozhraní Azure REST API přes curl

Součásti dvojice žádost-odpověď rozhraní REST API

Dvojici žádost-odpověď rozhraní REST API je možné rozdělit na pět součástí:

1. Identifikátor URI žádosti, který tvoří: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Přestože je identifikátor URI žádosti zahrnutý v hlavičce žádosti, voláme ho tady samostatně, protože většina jazyků nebo architektur vyžaduje, abyste ho předali odděleně od žádosti.

   • Schéma identifikátoru URI: Označuje protokol použitý k přenosu žádosti. Příkladem je http nebo https.
   • Hostitel identifikátoru URI: Určuje název domény nebo IP adresu serveru, který hostuje koncový bod služby REST, například graph.microsoft.com.
   • Cesta k prostředku: Určuje prostředek nebo kolekci prostředků, které mohou zahrnovat více segmentů používaných službou při určování výběru těchto prostředků. Příklad: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners Lze použít k dotazování seznamu vlastníků konkrétní aplikace v kolekci aplikací.
   • Řetězec dotazu (volitelný): Poskytuje další jednoduché parametry, například verzi rozhraní API nebo kritéria pro výběr prostředků.

2. Pole hlaviček zprávy požadavku HTTP:

   • Požadovaná metoda HTTP (označovaná také jako operace nebo sloveso), která službě řekne, jaký typ operace požadujete. Rozhraní Azure REST API podporují metody GET, HEAD, PUT, POST a PATCH.
   • Volitelná další pole hlavičky podle toho, jak je požaduje zadaný identifikátor URI a metoda HTTP. Například autorizační hlavička, která poskytuje nosný token obsahující informace o autorizaci klienta pro požadavek.

3. Volitelná pole hlavní části žádosti HTTP pro podporu identifikátoru URI a operace HTTP. Operace POST například obsahují objekty kódované pomocí MIME, které se předávají jako složité parametry. U operací POST a PUT je typ kódování MIME třeba zadat také v hlavičce žádosti Content-type. Některé služby vyžadují, abyste použili konkrétní typ MIME, například application/json.

4. Pole hlavičky odpovědi HTTP:

   • Kód stavu HTTP v rozsahu od kódů úspěchu 2xx po chybové kódy 4xx a 5xx. Může se také vrátit kód stavu definovaný službou, jak je uvedeno v dokumentaci k rozhraní API.
   • Volitelná další pole hlavičky, která jsou potřeba pro podporu odpovědi na žádosti, například hlavička odpovědi Content-type.

5. Volitelná pole hlavní části odpovědi HTTP:

   • Objekty odpovědi kódované pomocí MIME se vrátí v těle odpovědi HTTP, jako je odpověď z metody GET, která vrací data. Tyto objekty se obvykle vrací ve strukturovaném formátu, jako je JSON nebo XML, jak uvádí hlavička odpovědi Content-type. Když například požádáte o přístupový token z Microsoft Entra ID, vrátí se v textu odpovědi jako access_token element, jeden z několika párovaných objektů název/hodnota v kolekci dat. V tomto příkladu je zahrnuta také hlavička Content-Type: application/json odpovědi.

Registrace klientské aplikace pomocí Microsoft Entra ID

Většina služeb Azure (jako jsou poskytovatelé Azure Resource Manager a model nasazení Classic) před voláním rozhraní API služby vyžaduje ověření kódu klienta pomocí platných přihlašovacích údajů. Ověřování je mezi různými aktéry koordinováno pomocí Microsoft Entra ID a poskytuje klientovi přístupový token jako důkaz ověřování. Token se pak odešle do služby Azure v hlavičce autorizace HTTP následných požadavků rozhraní REST API. Deklarace identity tokenu také poskytují informace službě, což jí umožňuje ověřit klienta a provést veškerou požadovanou autorizaci.

Pokud používáte rozhraní REST API, které nepoužívá integrované ověřování Microsoft Entra, nebo jste už zaregistrovali klienta, přejděte k části Vytvoření požadavku.

Požadavky

Klientská aplikace musí před spuštěním oznamovat konfiguraci své identity Microsoft Entra ID tím, že ji zaregistruje v tenantovi Microsoft Entra. Než zaregistrujete klienta v Microsoft Entra ID, zvažte následující požadavky:

• Pokud ještě nemáte tenanta Microsoft Entra, přečtěte si téma Nastavení tenanta Microsoft Entra.

• V souladu s autorizační architekturou OAuth2 podporuje Microsoft Entra ID dva typy klientů. Porozumění každému z nich vám pomůže rozhodnout se, co je pro váš scénář nejvhodnější:

  • Weboví nebo důvěrní klienti běží na webovém serveru a můžou přistupovat k prostředkům pod vlastní identitou (například služba nebo démon) nebo získat delegovanou autorizaci pro přístup k prostředkům pod identitou přihlášeného uživatele (například webové aplikace). Pouze webový klient může bezpečně udržovat a prezentovat své vlastní přihlašovací údaje během ověřování Microsoft Entra za účelem získání přístupového tokenu.
  • nativní/veřejné klienty jsou nainstalované a spuštěné na zařízení. K prostředkům můžou přistupovat pouze v rámci delegované autorizace s použitím identity přihlášeného uživatele k získání přístupového tokenu jménem uživatele.

• Proces registrace vytvoří dva související objekty v tenantovi Microsoft Entra, kde je aplikace zaregistrovaná: objekt aplikace a instanční objekt. Další informace o těchto komponentách a jejich používání za běhu najdete v tématu Objekty aplikace a instanční objekty v Microsoft Entra ID.

Teď jste připraveni zaregistrovat klientskou aplikaci v Microsoft Entra ID.

Registrace klienta

Pokud chcete zaregistrovat klienta, který přistupuje k rozhraní REST API azure Resource Manager, přečtěte si téma Vytvoření aplikace Microsoft Entra a instančního objektu s přístupem k prostředkům pomocí portálu. Článek (dostupný také ve verzích PowerShellu a rozhraní příkazového řádku pro automatizaci registrace) ukazuje, jak:

• Zaregistrujte klientskou aplikaci v Microsoft Entra ID.
• Nastavte žádosti o oprávnění tak, aby klient měl přístup k rozhraní API azure Resource Manager.
• Nakonfigurujte nastavení Azure Resource Manager Role-Based Access Control (RBAC) pro autorizaci klienta.

Pokud váš klient přistupuje k jinému rozhraní API než k rozhraní API azure Resource Manager, projděte si následující informace:

• Registrace aplikace na platformě Microsoft Identity Platform
  • Zaregistrujte klientskou aplikaci pomocí Microsoft Entra ID v části Registrace aplikace.
  • V části Přidat přihlašovací údaje vytvořte tajný klíč (pokud registrujete webového klienta).
• Konfigurace aplikace pro zveřejnění webového rozhraní API
  • Přidání oprávnění k webovému rozhraní API a jejich zveřejnění jako rozsahů
• Konfigurace klientské aplikace pro přístup k webovému rozhraní API
  • Přidejte žádosti o oprávnění podle rozsahů definovaných pro rozhraní API v části Přidání oprávnění pro přístup k webovému rozhraní API.

Teď, když jste dokončili registraci klientské aplikace, přejděte ke kódu klienta, kde vytvoříte požadavek REST a zpracujete odpověď.

Vytvoření požadavku

Tato část se zabývá prvními třemi z pěti komponent, které jsme probrali dříve. Nejprve musíte získat přístupový token z Microsoft Entra ID, který použijete k sestavení hlavičky zprávy požadavku.

Získání přístupového tokenu

Po platné registraci klienta máte dva způsoby integrace s Microsoft Entra ID získání přístupového tokenu:

• Koncové body služby OAuth2 neutrální pro platformu a jazyk, které používáme v tomto článku. Pokyny uvedené v této části nepředpokládá nic o platformě nebo jazyku nebo skriptu vašeho klienta při použití koncových bodů Microsoft Entra OAuth. Jediným požadavkem je, abyste mohli odesílat a přijímat požadavky HTTPS do a z Microsoft Entra ID a parsovat zprávu odpovědi.
• Knihovny MSAL (Microsoft Authentication Library) specifické pro konkrétní platformu a jazyk, které jsou nad rámec tohoto článku. Knihovny poskytují asynchronní obálky pro požadavky koncových bodů OAuth2 a robustní funkce pro zpracování tokenů, jako je ukládání do mezipaměti a správa obnovovacích tokenů. Další informace najdete v tématu Přehled knihovny Microsoft Authentication Library (MSAL).

Dva koncové body Microsoft Entra, které používáte k ověření klienta a získání přístupového tokenu, se označují jako OAuth2 /authorize a /token koncové body. Způsob jejich použití závisí na registraci vaší aplikace a typu toku udělení autorizace OAuth2 , který potřebujete pro podporu aplikace za běhu. Pro účely tohoto článku předpokládáme, že váš klient používá jeden z následujících toků udělení autorizace: autorizační kód nebo přihlašovací údaje klienta. Pokud chcete získat přístupový token použitý ve zbývajících částech, postupujte podle pokynů pro tok, který nejlépe odpovídá vašemu scénáři.

Udělení autorizačního kódu (interaktivní klienti)

Toto udělení používají weboví i nativní klienti a vyžadují přihlašovací údaje od přihlášeného uživatele, aby bylo možné delegovat přístup k prostředkům klientské aplikaci. /authorize Používá koncový bod k získání autorizačního kódu (v reakci na přihlášení nebo souhlas uživatele) a /token následně koncový bod k výměně autorizačního kódu za přístupový token.

1. Nejprve si klient musí vyžádat autorizační kód z Microsoft Entra ID. Podrobnosti o formátu požadavku HTTPS GET na /authorize koncový bod a ukázkové zprávy žádosti a odpovědi najdete v tématu Žádost o autorizační kód. Identifikátor URI obsahuje následující parametry řetězce dotazu, které jsou specifické pro vaši klientskou aplikaci:

   • client_id: Identifikátor GUID, který byl přiřazen klientské aplikaci během registrace, označovaný také jako ID aplikace.

   • redirect_uri: Verze jednoho z identifikátorů URI pro odpověď/přesměrování zakódovaná v adrese URL zadaná při registraci klientské aplikace. Hodnota, kterou předáte, musí přesně odpovídat hodnotě vaší registrace.

   • resource: Identifikátor URI s kódováním URL, který je určený rozhraním REST API, které voláte. Webová nebo rozhraní REST API (označovaná také jako aplikace prostředků) můžou ve své konfiguraci vystavit jeden nebo více identifikátorů URI aplikace. Příklad:

     • Rozhraní API zprostředkovatele Azure Resource Manager (a modelu nasazení Classic) používají https://management.core.windows.net/.
     • Další prostředky najdete v dokumentaci k rozhraní API nebo konfiguraci aplikace prostředků v Azure Portal. Další informace najdete ve identifierUris vlastnosti objektu aplikace Microsoft Graph API.

   Požadavek na /authorize koncový bod nejprve aktivuje výzvu k přihlášení k ověření uživatele. Zpětná odpověď se doručí jako přesměrování (302) na identifikátor URI, který jste zadali v redirect_uri. Zpráva hlavičky odpovědi obsahuje location pole obsahující identifikátor URI přesměrování následovaný parametrem code dotazu. Parametr code obsahuje autorizační kód, který potřebujete pro krok 2.

2. Dále musí váš klient uplatnit autorizační kód pro přístupový token. Podrobnosti o formátu požadavku HTTPS POST na /token koncový bod a příklady požadavků a odpovědí najdete v tématu Žádost o přístupový token. Vzhledem k tomu, že se jedná o požadavek POST, zabalíte parametry specifické pro aplikaci do textu požadavku. Kromě některých z výše uvedených parametrů (spolu s dalšími novými parametry) předáte:

   • code: Tento parametr dotazu obsahuje autorizační kód, který jste získali v kroku 1.

   • client_secret: Tento parametr potřebujete jenom v případě, že je váš klient nakonfigurovaný jako webová aplikace. Jedná se o stejnou hodnotu tajného klíče nebo klíče, kterou jste vygenerovali dříve při registraci klienta.

Udělení přihlašovacích údajů klienta (neinteraktivní klienti)

Toto udělení je využíváno pouze webovými klienty, což aplikaci umožňuje přímý přístup k prostředkům (bez delegování uživatele) pomocí přihlašovacích údajů klienta, které jsou zadané při registraci. Udělení obvykle používají neinteraktivní klienti (bez uživatelského rozhraní), kteří se spouští jako služba nebo proces démon. K získání přístupového tokenu /token vyžaduje pouze koncový bod.

Interakce klienta a prostředku pro toto udělení se podobají kroku 2 udělení autorizačního kódu. Podrobnosti o formátu požadavku HTTPS POST na /token koncový bod a příklady požadavků a odpovědí najdete v části Získání tokenu v Microsoft identity platform a toku přihlašovacích údajů klienta OAuth 2.0.

Sestavení zprávy požadavku

Většina programovacích jazyků nebo architektur a skriptovacích prostředí usnadňuje sestavení a odeslání zprávy požadavku. Obvykle poskytují webovou třídu nebo třídu HTTP nebo rozhraní API, které abstrahují vytvoření nebo formátování požadavku a usnadňují psaní klientského kódu ( HttpWebRequest například třídy v rozhraní .NET Framework). Z důvodu stručnosti a protože většina úkolů je zpracována za vás, tato část se zabývá pouze důležitými prvky požadavku.

Identifikátor URI žádosti

Vzhledem k tomu, že se přenášejí a přijímají citlivé informace, všechny požadavky REST vyžadují pro schéma identifikátoru URI protokol HTTPS, což žádosti a odpovědi poskytuje zabezpečený kanál. Informace (tj. Microsoft Entra autorizační kód, přístupový/nosný token a citlivá data požadavků a odpovědí) jsou šifrovány nižší přenosovou vrstvou, která zajišťuje soukromí zpráv.

Zbytek identifikátoru URI požadavku vaší služby (hostitel, cesta k prostředku a všechny požadované parametry řetězce dotazu) jsou určené příslušnou specifikací rozhraní REST API. Například rozhraní API poskytovatele Azure Resource Manager používají https://management.azure.com/a model nasazení Azure Classic používá https://management.core.windows.net/. Oba vyžadují api-version parametr řetězce dotazu.

Hlavička požadavku

Identifikátor URI požadavku je součástí hlavičky zprávy požadavku spolu se všemi dalšími poli, která vyžadují specifikace rozhraní REST API vaší služby a specifikace HTTP. Váš požadavek může vyžadovat následující společná pole hlaviček:

• Authorization: Obsahuje nosný token OAuth2 pro zabezpečení požadavku, který jste získali dříve z Microsoft Entra ID.
• Content-Type: Obvykle se nastaví na application/json (páry název/hodnota ve formátu JSON) a určuje typ MIME textu požadavku.
• Host: Název domény nebo IP adresa serveru, na kterém je hostovaný koncový bod služby REST.

Text požadavku

Jak už bylo zmíněno dříve, text zprávy požadavku je volitelný v závislosti na konkrétní operaci, kterou požadujete, a jejích požadavcích na parametry. Pokud je to povinné, specifikace rozhraní API pro službu, kterou požadujete, určuje také kódování a formát.

Text požadavku je oddělený od hlavičky prázdným řádkem formátovaným podle pole hlavičky Content-Type . Příklad textu ve formátu "application/json" by vypadal takto:

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

Odeslání žádosti

Teď, když máte identifikátor URI požadavku služby a vytvořili jste hlavičku a text související zprávy požadavku, jste připraveni odeslat požadavek do koncového bodu služby REST.

Můžete například odeslat metodu požadavku HTTPS GET pro poskytovatele Azure Resource Manager pomocí polí hlaviček požadavku, která jsou podobná následujícímu (všimněte si, že text požadavku je prázdný):

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

<no body>

Můžete také odeslat metodu požadavku HTTPS PUT pro poskytovatele azure Resource Manager pomocí polí hlavičky a textu požadavku podobných následujícímu příkladu:

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

Po provedení požadavku se vrátí hlavička zprávy odpovědi a volitelné tělo.

Zpracování zprávy s odpovědí

Proces končí posledními dvěma z pěti komponent.

Pokud chcete odpověď zpracovat, parsujte hlavičku odpovědi a volitelně i text odpovědi (v závislosti na požadavku). V příkladu HTTPS GET v předchozí části jste použili koncový bod /subscriptions k načtení seznamu předplatných pro uživatele. Za předpokladu, že odpověď byla úspěšná, měli byste obdržet pole hlavičky odpovědi podobná následujícímu příkladu:

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

A měli byste obdržet text odpovědi, který obsahuje seznam předplatných Azure a jejich jednotlivých vlastností zakódovaných ve formátu JSON, podobně jako:

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

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

Podobně pro příklad HTTPS PUT byste měli obdržet hlavičku odpovědi podobnou následující, která potvrzuje, že vaše operace PUT pro přidání skupiny "ExampleResourceGroup" proběhla úspěšně:

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

A měli byste obdržet text odpovědi, který potvrdí, že obsah nově přidané skupiny prostředků je zakódovaný ve formátu JSON, podobně jako:

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

Stejně jako u požadavku většina programovacích jazyků a architektur usnadňuje zpracování zprávy odpovědi. Tyto informace obvykle vrátí vaší aplikaci po provedení požadavku a umožní vám je zpracovat v typovém nebo strukturovaném formátu. Hlavně vás zajímá potvrzení stavového kódu HTTP v hlavičce odpovědi a analýza textu odpovědi podle specifikace rozhraní API (nebo Content-Type polí hlavičky odpovědi a Content-Length ).

Asynchronní operace, omezování a stránkování

Vzor vytvoření,odeslání/zpracování-odpovědi popsaný v tomto článku je synchronní a vztahuje se na všechny zprávy REST. Některé služby však také podporují asynchronní vzor, který vyžaduje další zpracování hlaviček odpovědi k monitorování nebo dokončení asynchronního požadavku. Další informace najdete v tématu Sledování asynchronních operací Azure.

Resource Manager platí omezení počtu žádostí o čtení a zápis za hodinu, aby aplikace nemohla odesílat příliš mnoho požadavků. Pokud vaše aplikace tato omezení překročí, dojde k omezení požadavků. Hlavička odpovědi obsahuje počet zbývajících požadavků pro váš obor. Další informace najdete v tématu Omezování požadavků Resource Manageru.

Některé operace seznamu vrátí v textu odpovědi vlastnost s názvem nextLink . Tato vlastnost se zobrazí, pokud jsou výsledky příliš velké na to, aby se vrátily v jedné odpovědi. Obvykle odpověď obsahuje vlastnost nextLink, když operace seznamu vrátí více než 1 000 položek. Pokud další odkaz není ve výsledcích k dispozici, jsou vrácené výsledky dokončeny. Pokud nextLink obsahuje adresu URL, jsou vrácené výsledky pouze součástí celkové sady výsledků.

Odpověď je ve formátu:

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

Pokud chcete získat další stránku výsledků, odešlete požadavek GET na adresu URL ve vlastnosti nextLink. Adresa URL obsahuje pokračovací token, který označuje, kde se ve výsledcích nacházíte. Pokračujte v odesílání požadavků na adresu URL odkazu nextLink, dokud ve vrácených výsledcích nebude obsahovat adresu URL.

Odolnost rozhraní API Azure

Rozhraní Azure REST API jsou navržená s ohledem na odolnost a nepřetržitou dostupnost. Operace řídicí roviny (požadavky odeslané management.azure.com) v rozhraní REST API jsou:

• Distribuuje se napříč oblastmi. Některé služby jsou regionální.

• Distribuuje se napříč Zóny dostupnosti (i oblastmi) v umístěních, která mají více Zóny dostupnosti.

• Nezávisí na jednom logickém datovém centru.

• Nikdy se nespustí kvůli údržbě.

Související obsah

Hotovo. Jakmile zaregistrujete Microsoft Entra aplikaci a máte modulární techniku pro získání přístupového tokenu a zpracování požadavků HTTP, je poměrně snadné replikovat kód, abyste mohli využívat nová rozhraní REST API. Další informace o registraci aplikace a programovacím modelu Microsoft Entra najdete v dokumentaci k Microsoft identity platform.

Informace o testování požadavků a odpovědí HTTP najdete tady:

• Fiddler. Fiddler je bezplatný webový ladicí proxy server, který může zachytávat vaše žádosti REST, a zjednodušit tak diagnostiku zpráv žádost-odpověď HTTP.
• JWT.ms, které umožňují rychle a snadno vypisovat deklarace identity do nosné tokeny, abyste mohli ověřit jejich obsah.