Sdílet prostřednictvím

Reference k rozhraní Azure REST API

  • Článek

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

Rozhraní REST (Representational State Transfer) API jsou koncové body služby, které podporují sady operací HTTP (metod), které poskytují přístup k prostředkům služby. Následující části vás provedou:

  • Základní komponenty dvojice požadavků a odpovědí rozhraní REST API
  • Postup registrace klientské aplikace v Azure Active Directory (Azure AD) za účelem zabezpečení požadavků REST
  • Přehled vytvoření a odeslání požadavku REST a zpracování odpovědi

Poznámka

Většina rozhraní REST API služby Azure má odpovídající knihovnu klientské sady SDK, která zpracovává většinu klientského kódu za vás. Přečtěte si:

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

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

Dvojice požadavků a odpovědí rozhraní REST API je možné rozdělit do 5 komponent:

  1. Identifikátor URI žádosti, který tvoří: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Všimněte si, že to tady voláme samostatně, protože většina jazyků nebo architektur vyžaduje, abyste ho předali odděleně od zprávy požadavku, ale ve skutečnosti je součástí hlavičky zprávy požadavku.
    • Schéma URI: Označuje protokol použitý k přenosu požadavku. Příkladem je http nebo https.
    • Hostitel URI: název domény nebo IP adresa serveru, na kterém je hostovaný koncový bod služby REST, například graph.microsoft.com
    • Cesta k prostředku: Určuje prostředek nebo kolekci prostředků, která může zahrnovat více segmentů používaných službou při určování výběru těchto prostředků. Například: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners můžete použít k dotazování seznamu vlastníků konkrétní aplikace v kolekci aplikací.
    • Řetězec dotazu (volitelné): Slouží k zadání dalších jednoduchých parametrů, jako je verze rozhraní API, kritéria výběru prostředků atd.
  2. Pole záhlaví zprávy požadavku HTTP
    • Požadovaná metoda HTTP (označovaná také jako operace nebo sloveso), která službě sdělí, jaký typ operace požadujete. Rozhraní Azure REST API podporují metody GET, HEAD, PUT, POST a PATCH.
    • Volitelná další pole hlaviček vyžadovaná zadaným identifikátorem URI a metodou 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. Například operace POST obsahují objekty s kódováním MIME, které se předávají jako komplexní parametry. Typ kódování MIME pro text by měl být zadán také v Content-type hlavičce požadavku pro operace POST/PUT. Upozorňujeme, že některé služby vyžadují, abyste použili určitý typ MIME, například application/json.
  4. Pole záhlaví zprávy odpovědi HTTP
    • Stavový kód HTTP od kódů úspěchu 2xx až po kódy chyb 4xx/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ček podle potřeby pro podporu odpovědi na požadavek, jako je hlavička Content-type odpovědi.
  5. Volitelná pole textu zprávy odpovědi HTTP
    • Objekty odpovědi s kódováním MIME mohou být vráceny v textu odpovědi HTTP, jako je například odpověď z metody GET, která vrací data. Obvykle se vrátí ve strukturovaném formátu jako JSON nebo XML, jak je uvedeno v Content-type hlavičce odpovědi. Například při vyžádání přístupového tokenu z Azure AD se vrátí v textu odpovědi jako access_token prvek, jeden z několika objektů spárovaných název/hodnota v kolekci dat. V tomto příkladu bude zahrnuta také hlavička Content-Type: application/json odpovědi.

Registrace klientské aplikace pomocí Azure AD

Většina služeb Azure (jako jsou poskytovatelé Azure Resource Manager a klasická rozhraní API pro správu služeb) 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í Azure AD, která klientovi poskytne přístupový token jako důkaz o ověření nebo autorizaci. Token se pak odešle do služby Azure v hlavičce autorizace HTTP všech 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í Azure AD, nebo jste už zaregistrovali klienta, můžete přeskočit k části Vytvoření požadavku.

Požadavky

Vaše klientská aplikace musí před spuštěním Azure AD oznamovat konfiguraci identity tím, že ji zaregistruje v tenantovi Azure AD. Níže je seznam položek, které je potřeba zvážit před registrací klienta u Azure AD:

  • Pokud ještě nemáte tenanta Azure AD, přečtěte si téma Jak získat tenanta Azure Active Directory.
  • Podle autorizační architektury OAuth2 Azure AD podporuje 2 typy klientů. Když jim porozujdete, pomůže vám to rozhodnout se, která z nich je pro váš scénář nejvhodnější:
    • Weboví nebo důvěrní klienti (běží na webovém serveru) mají přístup k prostředkům buď pod vlastní identitou (tj. služba/démon), nebo získat delegovanou autorizaci pro přístup k prostředkům pod identitou přihlášeného uživatele (tj. webové aplikace). Pouze webový klient má možnost bezpečně udržovat a prezentovat své vlastní přihlašovací údaje během ověřování Azure AD získání přístupového tokenu.
    • nativní/veřejný klient (nainstalovaný nebo spuštěný na zařízení) může přistupovat k prostředkům 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ří v tenantovi Azure AD, ve kterém je aplikace zaregistrovaná, 2 související objekty: 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 aplikací a instančních objektů v Azure Active Directory.

Teď jsme připraveni zaregistrovat vaši klientskou aplikaci ve službě Azure AD.

Registrace klienta

Pokud chcete zaregistrovat klienta, který bude přistupovat k rozhraní REST API azure Resource Manager, najdete podrobné pokyny k registraci v tématu Použití portálu k vytvoření aplikace a instančního objektu Active Directory, který má přístup k prostředkům. Tento článek (dostupný také ve verzích PowerShellu a rozhraní příkazového řádku pro automatizaci registrace) vám ukáže, jak:

  • zaregistrovat klientskou aplikaci pomocí Azure AD
  • nastavení žádostí o oprávnění, které klientovi umožní přístup k rozhraní API azure Resource Manager
  • Konfigurace nastavení Access Control na základě rolí (RBAC) azure Resource Manager pro autorizaci klienta

Pro všechny ostatní klienty si přečtěte téma Integrace aplikací s Azure Active Directory. V tomto článku se dozvíte, jak:

  • zaregistrujte klientskou aplikaci pomocí Azure AD v části "Přidání aplikace".
  • vytvořte tajný klíč (pokud registrujete webového klienta) v části "Aktualizace aplikace".
  • přidání žádostí o oprávnění podle požadavků rozhraní API v části "Aktualizace aplikace"

Teď, když jste dokončili registraci klientské aplikace, můžeme přejít na kód vašeho klienta, kde vytvoříte požadavek REST a zpracujete odpověď.

Vytvoření požadavku

Tato část se zabývá prvními 3 z 5 komponent, které jsme probrali dříve. Nejprve musíme získat přístupový token z Azure AD, který použijeme při sestavení hlavičky zprávy požadavku.

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

Jakmile máte platnou registraci klienta, existují v podstatě 2 způsoby integrace s Azure AD získání přístupového tokenu:

  • Azure AD koncových bodů služby OAuth2 neutrálních pro platformu nebo jazyk, které budeme používat. Stejně jako koncové body rozhraní Azure REST API, které používáte, i pokyny uvedené v této části nečiní při používání koncových bodů Azure AD žádné předpoklady o platformě, jazyku nebo skriptu vašeho klienta. Pouze to, že může odesílat a přijímat požadavky HTTPS do a z Azure AD a analyzovat zprávu odpovědi.
  • Knihovny MSAL (Microsoft Authentication Library) specifické pro platformu nebo jazyk. 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ší podrobnosti, včetně referenční dokumentace, stažení knihovny a ukázkového kódu, najdete v tématu Knihovny ověřování Microsoftu.

2 Azure AD koncové body, které budete používat 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 na 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 bude používat jeden z následujících toků udělení autorizace: autorizační kód nebo přihlašovací údaje klienta. Postupujte podle pokynů pro ten, který nejlépe odpovídá vašemu scénáři, a získejte přístupový token, který použijete ve zbývajících částech.

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

Toto udělení můžou používat weboví i nativní klienti a vyžaduje přihlašovací údaje od přihlášeného uživatele, aby bylo možné delegovat přístup k prostředkům klientské aplikace. /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 bude muset vyžádat autorizační kód z Azure AD. 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 bude obsahovat parametry řetězce dotazu, včetně následujících parametrů, které jsou specifické pro vaši klientskou aplikaci:

    • client_id – označuje se také jako ID aplikace. Toto je identifikátor GUID přiřazený vaší klientské aplikaci, když jste se zaregistrovali v části výše.

    • redirect_uri – verze [jednoho z] identifikátorů URI odpovědi/přesměrování zadaná během registrace klientské aplikace s kódováním URL. Všimněte si, že hodnota, kterou předáte, se musí přesně shodovat s vaší registrací!

    • resource – identifikátor URI kódovaný adresou URL určený rozhraním REST API, které voláte. Webová nebo rozhraní REST API (označovaná také jako aplikace prostředků) můžou v konfiguraci zveřejnit jednu nebo více identifikátorů URI aplikace. Příklad:

      • Rozhraní API poskytovatele azure Resource Manager (a klasické správy služeb) se 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ší podrobnosti najdete také ve identifierUris vlastnosti objektu aplikace Azure AD.

    Požadavek na /authorize koncový bod nejprve aktivuje výzvu k přihlášení k ověření koncového uživatele. Odpověď, kterou získáte zpět, se doručí jako přesměrování (302) na identifikátor URI, který jste zadali v redirect_uri. Zpráva hlavičky odpovědi bude obsahovat location pole, které obsahuje identifikátor URI přesměrování následovaný parametrem code dotazu, obsahující autorizační kód, který budete potřebovat pro krok 2.

  2. Dále bude muset váš klient uplatnit autorizační kód pro přístupový token. Podrobnosti o formátu požadavku HTTPS POST na koncový bod a ukázkové zprávy žádosti a odpovědi najdete v tématu Použití autorizačního kódu k vyžádání přístupového tokenu/token. Vzhledem k tomu, že se jedná o požadavek POST, tentokrát zabalíte parametry specifické pro aplikaci v textu požadavku. Kromě některých výše uvedených (spolu s dalšími novými) předáte :

    • code – Toto je parametr dotazu, který bude obsahovat autorizační kód, který jste získali v kroku 1.
    • client_secret – Tento parametr budete potřebovat pouze 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í můžou použít jenom weboví klienti, což aplikaci umožňuje přímý přístup k prostředkům (bez delegování uživatele) pomocí vlastních přihlašovacích údajů klienta, které jsou zadané při registraci. Obvykle ho používají neinteraktivní klienti (bez uživatelského rozhraní), kteří běží jako proces démon nebo služba, a k získání přístupového tokenu /token vyžaduje pouze koncový bod.

Interakce klienta a prostředku pro toto udělení jsou velmi podobné kroku č. 2 udělení autorizačního kódu. Podrobnosti o formátu požadavku HTTPS POST na /token koncový bod a ukázkové zprávy žádosti a odpovědi najdete v části Žádost o přístupový token v tématu Volání služby do služby pomocí přihlašovacích údajů klienta.

Sestavení zprávy požadavku

Všimněte si, že většina programovacích jazyků/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í a formátování požadavku, což usnadňuje psaní klientského kódu (například třída HttpWebRequest v rozhraní .NET Framework). Kvůli stručnosti se budeme zabývat pouze důležitými prvky požadavku, protože většina z nich bude zpracována za vás.

Identifikátor URI žádosti

Všechny zabezpečené požadavky REST vyžadují pro schéma identifikátoru URI protokol HTTPS, který poskytuje požadavek a odpověď se zabezpečeným kanálem, protože se přenášejí nebo přijímají citlivé informace. Tyto informace (tj. Azure AD autorizační kód, přístupový/nosný token, citlivá data požadavků a odpovědí) se šifrují nižší přenosovou vrstvou, která zajišťuje soukromí zpráv.

Zbývající část identifikátoru URI požadavku vaší služby (hostitel, cesta k prostředku a všechny požadované parametry řetězce dotazu) bude určena související specifikací rozhraní REST API. Například rozhraní API poskytovatele Azure Resource Manager používají https://management.azure.com/, klasická rozhraní API pro správu služeb Azure , https://management.core.windows.net/obě vyžadují api-version parametr řetězce dotazu atd.

Hlavička požadavku

Identifikátor URI požadavku bude součástí hlavičky zprávy požadavku spolu se všemi dalšími poli určenými specifikací rozhraní REST API vaší služby a specifikací HTTP. Tady jsou některá běžná pole hlaviček, která můžete v požadavku potřebovat:

  • Authorization: obsahuje nosný token OAuth2 pro zabezpečení požadavku, který jste získali dříve z Azure AD
  • 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: Toto je 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 nutné, specifikace rozhraní API pro službu, kterou požadujete, určí také kódování a formát.

Text požadavku je oddělený od hlavičky prázdným řádkem, který by měl být formátován 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 nebo text zprávy související s požadavkem, jste připraveni odeslat požadavek do koncového bodu služby REST.

Například metoda požadavku HTTPS GET pro poskytovatele Azure Resource Manager se může posílat pomocí polí hlaviček požadavku podobných následujícímu, ale 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>

Metoda požadavku HTTPS PUT pro poskytovatele Azure Resource Manager může být odeslána pomocí polí hlavičky a textu požadavku, která jsou podobná následujícímu:

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

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

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

Teď dokončíme poslední 2 z 5 komponent.

Ke zpracování odpovědi budete muset parsovat hlavičku odpovědi a volitelně i text odpovědi (v závislosti na požadavku). V příkladu HTTPS GET uvedeném výše jsme k načtení seznamu předplatných pro uživatele použili koncový bod /subscriptions. Za předpokladu, že odpověď byla úspěšná, měli bychom obdržet pole hlavičky odpovědi podobná následujícímu:

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

a text odpovědi, který obsahuje seznam předplatných Azure a jejich jednotlivé vlastnosti zakódované ve formátu JSON, podobně jako:

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

Podobně u příkladu HTTPS PUT bychom měli obdržet hlavičku odpovědi podobnou následující, která potvrzuje, že naš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 text odpovědi, který potvrzuje obsah nově přidané skupiny prostředků zakódovaný ve formátu JSON, podobně jako:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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 s odpovědí. 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 bude zajímat potvrzení stavového kódu HTTP v hlavičce odpovědi, a pokud se to povede, parsování textu odpovědi podle specifikace rozhraní API (nebo Content-Type polí hlaviček odpovědi a Content-Length ).

A to je vše! Jakmile budete mít zaregistrovanou aplikaci Azure AD a získáte komponentizovanou techniku pro získání přístupového tokenu a vytváření a zpracování požadavků HTTP, je poměrně snadné replikovat kód, abyste mohli využít výhod nových rozhraní REST API.

Související obsah

  • Další informace o registraci aplikací a programovacím modelu Azure AD najdete v tématu Microsoft identity platform (Azure Active Directory pro vývojáře), včetně komplexního indexu článků HowTo a QuickStart a ukázkového kódu.
  • Pokud chcete testovat požadavky a odpovědi HTTP, podívejte se na
    • Fiddler. Fiddler je bezplatný webový ladicí proxy server, který může zachycovat vaše požadavky REST, což usnadňuje diagnostiku požadavků HTTP a zpráv odpovědí.
    • Dekodér JWT a JWT.io, které umožňují rychle a snadno vypisovat deklarace identity do nosné tokeny, abyste mohli ověřit jejich obsah.

V části komentáře LiveFyre, která následuje po tomto článku, nám můžete poskytnout zpětnou vazbu a pomoct nám upřesnit a utvářet obsah.