Share via

Azure REST API-naslaginformatie

  • Artikel

Welkom bij de Azure REST API-naslaginformatie.

REST-API's (Representational State Transfer) zijn service-eindpunten die ondersteuning bieden voor sets HTTP-bewerkingen (methoden), die toegang bieden tot de resources van de service. In de onderstaande secties vindt u stapsgewijze instructies:

  • De basisonderdelen van een REST API-aanvraag/antwoordpaar
  • Uw clienttoepassing registreren bij Azure Active Directory (Azure AD) om uw REST-aanvragen te beveiligen
  • Overzichten van het maken en verzenden van een REST-aanvraag en het verwerken van het antwoord

Notitie

De meeste REST API's van de Azure-service hebben een bijbehorende client-SDK-bibliotheek, die een groot deel van de clientcode voor u verwerkt. Zie:

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

Onderdelen van een REST API-aanvraag/antwoord

Een REST API-aanvraag/antwoordpaar kan worden onderverdeeld in 5 onderdelen:

  1. De Aanvraag-URI die bestaat uit: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Houd er rekening mee dat we dit hier afzonderlijk aanroepen, omdat de meeste talen/frameworks vereisen dat u dit afzonderlijk van het aanvraagbericht doorgeeft, maar het is in feite opgenomen in de berichtkop van de aanvraag.
    • URI-schema: geeft het protocol aan dat wordt gebruikt om de aanvraag te verzenden. Bijvoorbeeld http of https.
    • URI-host: de domeinnaam of het IP-adres van de server waarop het REST-service-eindpunt wordt gehost, zoals graph.microsoft.com
    • Resourcepad: hiermee geeft u de resource of resourceverzameling op, die meerdere segmenten kan bevatten die door de service worden gebruikt bij het bepalen van de selectie van deze resources. Bijvoorbeeld: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners kan worden gebruikt om een query uit te voeren op de lijst met eigenaren van een specifieke toepassing in de verzameling toepassingen.
    • Queryreeks (optioneel): wordt gebruikt om aanvullende eenvoudige parameters op te geven, zoals de API-versie, selectiecriteria voor resources, enzovoort.
  2. Headervelden voor HTTP-aanvraagberichten
    • Een vereiste HTTP-methode (ook wel een bewerking of werkwoord genoemd), die de service vertelt welk type bewerking u aanvraagt. Azure REST API's ondersteunen de methoden GET, HEAD, PUT, POST en PATCH.
    • Optionele extra headervelden zoals vereist voor de opgegeven URI en HTTP-methode. Bijvoorbeeld een autorisatieheader die een Bearer-token bevat met clientautorisatiegegevens voor de aanvraag.
  3. Optionele berichttekstvelden voor de HTTP-aanvraag ter ondersteuning van de URI en HTTP-bewerking. POST-bewerkingen bevatten bijvoorbeeld MIME-gecodeerde objecten die als complexe parameters worden doorgegeven. Het MIME-coderingstype voor de hoofdtekst moet ook worden opgegeven in de Content-type aanvraagheader voor POST/PUT-bewerkingen. Houd er rekening mee dat u voor sommige services een specifiek MIME-type moet gebruiken, zoals application/json.
  4. Headervelden voor HTTP-antwoordberichten
    • Een HTTP-statuscode, variërend van 2xx-succescodes tot 4xx/5xx-foutcodes. Er kan ook een servicegedefinieerde statuscode worden geretourneerd, zoals aangegeven in de API-documentatie.
    • Optionele extra headervelden, indien vereist ter ondersteuning van het antwoord van de aanvraag, zoals een Content-type antwoordheader.
  5. Optionele hoofdtekstvelden voor HTTP-antwoordberichten
    • Mime-gecodeerde antwoordobjecten kunnen worden geretourneerd in de HTTP-antwoordtekst, zoals een antwoord van een GET-methode die gegevens retourneert. Normaal gesproken worden deze geretourneerd in een gestructureerde indeling als JSON of XML, zoals aangegeven door de Content-type antwoordheader. Wanneer u bijvoorbeeld een toegangstoken van Azure AD aanvraagt, wordt dit in de hoofdtekst van het antwoord geretourneerd als het element, een van de access_token verschillende gekoppelde naam-/waardeobjecten in een gegevensverzameling. In dit voorbeeld wordt ook een antwoordheader van Content-Type: application/json opgenomen.

Uw clienttoepassing registreren bij Azure AD

Voor de meeste Azure-services (zoals Azure Resource Manager-providers en de klassieke Service Management API's) moet uw clientcode worden geverifieerd met geldige referenties voordat u de API van de service kunt aanroepen. Verificatie wordt gecoördineerd tussen de verschillende actoren door Azure AD, waarmee uw client een toegangstoken krijgt als bewijs van de verificatie/autorisatie. Het token wordt vervolgens verzonden naar de Azure-service in de HTTP-autorisatieheader van alle volgende REST API-aanvragen. De claims van het token bieden ook informatie aan de service, zodat deze de client kan valideren en eventuele vereiste autorisatie kan uitvoeren.

Als u een REST API gebruikt die geen geïntegreerde Azure AD-verificatie gebruikt, of als u uw client al hebt geregistreerd, kunt u doorgaan naar de sectie De aanvraag maken.

Vereisten

Uw clienttoepassing moet de identiteitsconfiguratie vóór runtime bekend maken bij Azure AD door deze te registreren in een Azure AD-tenant. Hieronder vindt u een lijst met items die u moet overwegen voordat u uw client registreert bij Azure AD:

  • Als u nog geen Azure AD-tenant hebt, raadpleegt u Een Azure Active Directory-tenant verkrijgen.
  • Volgens het OAuth2-autorisatieframework ondersteunt Azure AD twee typen clients. Als u elk begrijpt, kunt u bepalen wat het meest geschikt is voor uw scenario:
    • web-/vertrouwelijke clients (uitgevoerd op een webserver) hebben toegang tot resources onder hun eigen identiteit (dat wil zeggen: service/daemon) of verkrijgen gedelegeerde autorisatie voor toegang tot resources onder de identiteit van de aangemelde gebruiker (dat wil zeggen: web-app). Alleen een webclient heeft de mogelijkheid om zijn eigen referenties veilig te onderhouden en te presenteren tijdens Azure AD verificatie om een toegangstoken te verkrijgen.
    • systeemeigen/openbare clients (geïnstalleerd/uitgevoerd op een apparaat) hebben alleen toegang tot resources onder gedelegeerde autorisatie, waarbij de identiteit van de aangemelde gebruiker wordt gebruikt om namens de gebruiker een toegangstoken te verkrijgen.
  • Tijdens het registratieproces worden twee gerelateerde objecten gemaakt in de Azure AD tenant waar de toepassing is geregistreerd: een toepassingsobject en een service-principalobject. Raadpleeg Application and service principal objects in Azure Active Directory (Toepassings- en service-principalobjecten in Azure Active Directory) voor meer achtergrondinformatie over deze onderdelen en hoe ze tijdens runtime worden gebruikt.

Nu zijn we klaar om uw clienttoepassing te registreren bij Azure AD.

Clientregistratie

Als u een client wilt registreren die toegang krijgt tot een Azure Resource Manager REST API, raadpleegt u Portal gebruiken om een Active Directory-toepassing en service-principal te maken die toegang hebben tot resources voor stapsgewijze registratie-instructies. In dit artikel (ook beschikbaar in PowerShell- en CLI-versies voor het automatiseren van registratie) leest u het volgende:

  • de clienttoepassing registreren met Azure AD
  • machtigingsaanvragen instellen om de client toegang te geven tot de Azure Resource Manager-API
  • RBAC-instellingen (Op rollen gebaseerd Access Control) van Azure Resource Manager configureren voor het autoriseren van de client

Raadpleeg Toepassingen integreren met Azure Active Directory voor alle andere clients. In dit artikel wordt uitgelegd hoe u het volgende kunt doen:

  • de clienttoepassing registreren met Azure AD, in de sectie Een toepassing toevoegen
  • maak een geheime sleutel (als u een webclient registreert) in de sectie Een toepassing bijwerken
  • voeg machtigingsaanvragen toe zoals vereist door de API, in de sectie Een toepassing bijwerken

Nu u de registratie van uw clienttoepassing hebt voltooid, kunnen we naar uw clientcode gaan, waar u de REST-aanvraag maakt en het antwoord verwerkt.

De aanvraag maken

In deze sectie worden de eerste 3 van de vijf onderdelen behandeld die we eerder hebben besproken. Eerst moeten we het toegangstoken ophalen van Azure AD, dat we gaan gebruiken bij het samenstellen van de berichtkop van de aanvraag.

Een toegangstoken verkrijgen

Zodra u een geldige clientregistratie hebt, zijn er in feite twee manieren om te integreren met Azure AD om een toegangstoken te verkrijgen:

  • Azure AD platform-/taalneutrale OAuth2-service-eindpunten, die we gaan gebruiken. Net als bij de Azure REST API-eindpunten die u gebruikt, wordt in de instructies in deze sectie geen veronderstellingen gedaan over het platform of de taal/het script van uw client bij het gebruik van de Azure AD-eindpunten; alleen dat deze HTTPS-aanvragen naar/van Azure AD kan verzenden/ontvangen en het antwoordbericht kan parseren.
  • Het platform/taalspecifieke Microsoft Authentication Libraries (MSAL). De bibliotheken bieden asynchrone wrappers voor de OAuth2-eindpuntaanvragen en robuuste tokenverwerkingsfuncties zoals caching en vernieuwingstokenbeheer. Zie Microsoft Authentication Libraries (Microsoft Authentication Libraries) voor meer informatie, inclusief referentiedocumentatie, bibliotheekdownloads en voorbeeldcode.

De twee Azure AD eindpunten die u gebruikt om uw client te verifiëren en een toegangstoken te verkrijgen, worden de OAuth2 /authorize en /token eindpunten genoemd. Hoe u deze gebruikt, is afhankelijk van de registratie van uw toepassing en het type OAuth2-autorisatietoestemmingsstroom dat u nodig hebt om uw toepassing tijdens runtime te ondersteunen. Voor de doeleinden van dit artikel gaan we ervan uit dat uw client een van de volgende autorisatietoekenningenstromen gebruikt: autorisatiecode of clientreferenties. Volg de instructies voor het token dat het beste overeenkomt met uw scenario om het toegangstoken te verkrijgen dat u in de resterende secties gaat gebruiken.

Autorisatiecode verlenen (interactieve clients)

Deze toekenning kan worden gebruikt door zowel web- als systeemeigen clients en vereist referenties van een aangemelde gebruiker om resourcetoegang tot de clienttoepassing te delegeren. Het eindpunt wordt gebruikt /authorize om een autorisatiecode te verkrijgen (als reactie op aanmelding/toestemming van de gebruiker), gevolgd door het /token eindpunt om de autorisatiecode uit te wisselen voor een toegangstoken.

  1. Eerst moet uw client een autorisatiecode aanvragen bij Azure AD. Zie Een autorisatiecode aanvragen voor meer informatie over de indeling van de HTTPS GET-aanvraag voor het /authorize eindpunt en voorbeelden van aanvraag-/antwoordberichten. De URI bevat queryreeksparameters, waaronder de volgende parameters die specifiek zijn voor uw clienttoepassing:

    • client_id - ook wel een toepassings-id genoemd. Dit is de GUID die is toegewezen aan uw clienttoepassing toen u zich registreerde in de bovenstaande sectie

    • redirect_uri - een URL-gecodeerde versie van [een van] de antwoord-/omleidings-URI's die zijn opgegeven tijdens de registratie van uw clienttoepassing. Houd er rekening mee dat de waarde die u doorgeeft exact moet overeenkomen met uw registratie!

    • resource - een URL-gecodeerde id-URI die is opgegeven door de REST API die u aanroept. Web-/REST-API's (ook wel resourcetoepassingen genoemd) kunnen een of meer toepassings-id-URI's beschikbaar maken in hun configuratie. Bijvoorbeeld:

      • Azure Resource Manager provider(en klassieke Service Management) API's gebruikenhttps://management.core.windows.net/
      • Zie de API-documentatie of de configuratie van de resourcetoepassing in de Azure Portal voor andere resources. Zie ook de identifierUris eigenschap van het toepassingsobject Azure AD voor meer informatie.

    De aanvraag voor het /authorize eindpunt activeert eerst een aanmeldingsprompt om de eindgebruiker te verifiëren. Het antwoord dat u terugkrijgt, wordt geleverd als een omleiding (302) naar de URI die u hebt opgegeven in redirect_uri. Het antwoordheaderbericht bevat een location veld dat de omleidings-URI bevat, gevolgd door een code queryparameter, met daarin de autorisatiecode die u nodig hebt voor stap 2.

  2. Vervolgens moet uw client de autorisatiecode inwisselen voor een toegangstoken. Zie De autorisatiecode gebruiken om een toegangstoken aan te vragen voor meer informatie over de indeling van de HTTPS POST-aanvraag voor het /token eindpunt en voorbeeld van aanvraag-/antwoordberichten. Omdat dit een POST-aanvraag is, verpakt u deze keer uw toepassingsspecifieke parameters in de aanvraagbody. Naast een aantal van de hierboven genoemde (samen met andere nieuwe), passeert u :

    • code - dit is de queryparameter die de autorisatiecode bevat die u in stap 1 hebt verkregen.
    • client_secret - u hebt deze parameter alleen nodig als uw client is geconfigureerd als een webtoepassing. Dit is dezelfde waarde voor het geheim/de sleutel die u eerder hebt gegenereerd in de clientregistratie.

Clientreferenties verlenen (niet-interactieve clients)

Deze toekenning kan alleen worden gebruikt door webclients, waardoor de toepassing rechtstreeks toegang heeft tot resources (geen gebruikersdelegering) met behulp van de eigen referenties van de client, die tijdens de registratie worden verstrekt. Het wordt meestal gebruikt door niet-interactieve clients (geen gebruikersinterface) die worden uitgevoerd als een daemon/service en vereist alleen het /token eindpunt om een toegangstoken te verkrijgen.

De client-/resource-interacties voor deze toekenning zijn vergelijkbaar met stap 2 van de autorisatiecodetoekenning. Zie de sectie 'Een toegangstoken aanvragen' in Service-naar-serviceaanroepen met behulp van clientreferenties voor meer informatie over de indeling van de HTTPS POST-aanvraag naar het /token eindpunt en voorbeelden van aanvraag-/antwoordberichten.

Het aanvraagbericht samenstellen

Houd er rekening mee dat de meeste programmeertalen/frameworks en scriptomgevingen het eenvoudig maken om het aanvraagbericht samen te stellen en te verzenden. Ze bieden doorgaans een web-/HTTP-klasse of API die het maken/formatteren van de aanvraag abstraheert, waardoor het eenvoudiger wordt om de clientcode te schrijven (bijvoorbeeld de klasse HttpWebRequest in de .NET Framework). Kortheidshalve behandelen we alleen de belangrijke elementen van de aanvraag, aangezien het grootste deel hiervan voor u wordt afgehandeld.

Aanvraag-URI

Alle beveiligde REST-aanvragen vereisen het HTTPS-protocol voor het URI-schema, waarbij de aanvraag en het antwoord worden geleverd met een beveiligd kanaal, vanwege het feit dat gevoelige informatie wordt verzonden/ontvangen. Deze informatie (bijvoorbeeld: de Azure AD autorisatiecode, toegangs-/bearer-token, gevoelige aanvraag-/antwoordgegevens) wordt versleuteld door een lagere transportlaag, waardoor de privacy van de berichten wordt gewaarborgd.

De rest van de aanvraag-URI van uw service (de host, het resourcepad en eventuele vereiste queryreeksparameters) wordt bepaald door de gerelateerde REST API-specificatie. Azure Resource Manager provider-API's gebruiken https://management.azure.com/bijvoorbeeld , klassieke Azure Service Management-API's gebruiken https://management.core.windows.net/, beide vereisen een api-version queryreeksparameter, enzovoort.

Aanvraagheader

De aanvraag-URI wordt gebundeld in de berichtkop van de aanvraag, samen met eventuele aanvullende velden zoals bepaald door de REST API-specificatie van uw service en de HTTP-specificatie. Hier volgen enkele algemene headervelden die u mogelijk nodig hebt in uw aanvraag:

  • Authorization: bevat het OAuth2 Bearer-token om de aanvraag te beveiligen, zoals eerder verkregen van Azure AD
  • Content-Type: meestal ingesteld op 'application/json' (naam-/waardeparen in JSON-indeling) en geeft het MIME-type van de aanvraagbody op.
  • Host: dit is de domeinnaam of het IP-adres van de server waarop het REST-service-eindpunt wordt gehost

Aanvraagbody

Zoals eerder vermeld, is de hoofdtekst van het aanvraagbericht optioneel, afhankelijk van de specifieke bewerking die u aanvraagt en de parametervereisten. Als dit vereist is, worden in de API-specificatie voor de service die u aanvraagt ook de codering en indeling opgegeven.

De aanvraagbody is gescheiden van de header door een lege regel, moet worden opgemaakt volgens het Content-Type veld header. Een voorbeeld van een hoofdtekst met de indeling 'application/json' ziet er als volgt uit:

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

De aanvraag verzenden

Nu u de aanvraag-URI van de service hebt en de bijbehorende berichtkop/hoofdtekst van de aanvraag hebt gemaakt, bent u klaar om de aanvraag naar het REST-service-eindpunt te verzenden.

Een HTTPS GET-aanvraagmethode voor een Azure Resource Manager-provider kan bijvoorbeeld worden verzonden met behulp van aanvraagheadervelden die vergelijkbaar zijn met de volgende, maar u ziet dat de aanvraagtekst leeg is:

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

<no body>

En een HTTPS PUT-aanvraagmethode voor een Azure Resource Manager-provider kan worden verzonden met behulp van aanvraagheader EN hoofdtekstvelden die er ongeveer als volgt uitzien:

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

Nadat u de aanvraag hebt ingediend, worden de koptekst van het antwoordbericht en de optionele hoofdtekst geretourneerd.

Het antwoordbericht verwerken

Nu sluiten we af met de laatste 2 van de vijf onderdelen.

Als u het antwoord wilt verwerken, moet u de antwoordheader en optioneel de hoofdtekst van het antwoord parseren (afhankelijk van de aanvraag). In het bovenstaande HTTPS GET-voorbeeld hebben we het eindpunt /subscriptions gebruikt om de lijst met abonnementen voor een gebruiker op te halen. Ervan uitgaande dat het antwoord is geslaagd, moeten we antwoordheadervelden ontvangen die er ongeveer als volgt uitzien:

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

en een antwoordtekst, met de lijst met Azure-abonnementen en hun afzonderlijke eigenschappen gecodeerd in JSON-indeling, vergelijkbaar met:

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

Op dezelfde manier moeten we voor het HTTPS PUT-voorbeeld een antwoordheader ontvangen die vergelijkbaar is met het volgende, om te bevestigen dat de PUT-bewerking voor het toevoegen van de 'ExampleResourceGroup' is geslaagd:

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

en een antwoordtekst, die de inhoud bevestigt van de zojuist toegevoegde resourcegroep gecodeerd in JSON-indeling, vergelijkbaar met:

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

Net als bij de aanvraag is het in de meeste programmeertalen/frameworks eenvoudig om het antwoordbericht te verwerken. Ze retourneren deze informatie meestal naar uw toepassing na de aanvraag, zodat u deze in een getypte/gestructureerde indeling kunt verwerken. U zult voornamelijk geïnteresseerd zijn in het bevestigen van de HTTP-statuscode in de antwoordheader en, indien succsessful, het parseren van de antwoordtekst volgens de API-specificatie (of de Content-Type antwoordheadervelden en Content-Length ).

Dat is alles. Zodra u uw Azure AD-toepassing hebt geregistreerd en een gecomponentiseerde techniek voor het verkrijgen van een toegangstoken en het maken en verwerken van HTTP-aanvragen, is het vrij eenvoudig om uw code te repliceren om te profiteren van nieuwe REST API's.

Gerelateerde inhoud

  • Zie Microsoft identity platform (Azure Active Directory voor ontwikkelaars) voor meer informatie over toepassingsregistratie en het Azure AD programmeermodel, waaronder een uitgebreide index van artikelen over procedures en quickstart-artikelen en voorbeeldcode.
  • Als u HTTP-aanvragen/-antwoorden wilt testen, bekijkt u
    • Fiddler. Fiddler is een gratis webfoutopsporingsproxy die uw REST-aanvragen kan onderscheppen, zodat u eenvoudig de HTTP-aanvraag- en antwoordberichten kunt diagnosticeren.
    • JWT Decoder en JWT.io, waarmee u snel en eenvoudig de claims in uw Bearer-token kunt dumpen, zodat u de inhoud ervan kunt valideren.

Gebruik de livefyre-opmerkingensectie die volgt op dit artikel om feedback te geven en ons te helpen onze inhoud te verfijnen en vorm te geven.