Naslaginformatie over Azure REST API

Welkom bij de referentiedocumentatie voor Azure REST API.

REST API's (Representational State Transfer) zijn service-eindpunten die ondersteuning bieden voor sets met HTTP-bewerkingen (methoden) waarmee u toegang tot de resources van de service kunt maken, ophalen, bijwerken of verwijderen. In dit artikel worden de volgende stappen beschreven:

• Azure REST API's aanroepen met curl
• De basisonderdelen van een REST API-aanvraag/antwoordpaar.
• Uw clienttoepassing registreren bij Microsoft Entra ID om uw REST-aanvragen te beveiligen.
• Overzichten van het maken en verzenden van een REST-aanvraag en het verwerken van het antwoord.

Tip

De meeste REST API's voor Azure-services hebben clientbibliotheken die een systeemeigen interface bieden voor het gebruik van Azure-services:

.NET | Java | | Node.jsPython | Gaan | C++

Azure REST API's aanroepen met curl

Het proces dat in het volgende blogbericht wordt beschreven, laat zien hoe u een Azure REST API aanroept met behulp van curl. U kunt overwegen curl te gebruiken in scripts zonder toezicht. Bijvoorbeeld in DevOps-automatiseringsscenario's.

Azure REST API aanroepen via curl

Onderdelen van een REST API-aanvraag/antwoord

Een combinatie van REST API-aanvraag/antwoord kan worden opgesplitst in vijf onderdelen:

1. De Aanvraag-URI die bestaat uit: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Hoewel de aanvraag-URI is opgenomen in de berichtkop van de aanvraag, wordt deze hier afzonderlijk aangeroepen omdat u deze voor de meeste talen of frameworks afzonderlijk moet doorgeven vanuit het aanvraagbericht.

   • URI-schema: geeft het protocol aan dat wordt gebruikt voor het verzenden van de aanvraag. Bijvoorbeeld http of https.
   • URI-host: geeft de domeinnaam of het IP-adres op van de server op waarop het REST-service-eindpunt wordt gehost, zoals graph.microsoft.com.
   • Resourcepad: geeft de resource of resourceverzameling op, die verschillende segmenten kan bevatten die in de service worden gebruikt om de selectie van deze resources te bepalen. Kan bijvoorbeeld beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners worden gebruikt om een query uit te voeren op de lijst met de eigenaren van een specifieke toepassing in de verzameling toepassingen.
   • Querytekenreeks (optioneel): biedt extra eenvoudige parameters, zoals de API-versie of criteria voor resourceselectie.

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 kopvelden, zoals vereist voor de opgegeven URI en HTTP-methode. Bijvoorbeeld een autorisatieheader die een Bearer-token biedt met clientautorisatiegegevens voor de aanvraag.

3. Optionele berichttekstvelden voor de HTTP-aanvraag ter ondersteuning van de URI en HTTP-bewerking. POST-bewerkingen bevatten bijvoorbeeld met MIME gecodeerde objecten die worden doorgevoerd als complexe parameters. Voor POST- of PUT-bewerkingen moet ook het MIME-coderingstype voor de berichttekst worden opgegeven in de Content-type-aanvraagkop. Voor sommige services moet u een specifiek MIME-type gebruiken, zoals application/json.

4. Berichtkopvelden voor het HTTP-antwoord:

   • Een HTTP-statuscode, die ligt tussen 2xx-succescodes tot 4xx- of 5xx-foutcodes. Er kan ook een servicegedefinieerde statuscode worden geretourneerd, zoals aangegeven in de API-documentatie.
   • Optionele extra kopvelden, zoals vereist ter ondersteuning van het antwoord op de aanvraag, zoals een Content-type-antwoordkop.

5. Optionele berichttekstvelden voor het HTTP-antwoord:

   • Met MIME gecodeerde antwoordobjecten worden geretourneerd in de berichttekst van het HTTP-antwoord, zoals een reactie via een GET-methode waarmee gegevens worden geretourneerd. Normaal gesproken worden deze objecten geretourneerd in een gestructureerde indeling (bijvoorbeeld JSON of XML), zoals aangegeven in de Content-type-antwoordkop. Wanneer u bijvoorbeeld een toegangstoken aanvraagt bij Microsoft Entra ID, wordt dit in de antwoordtekst geretourneerd als het access_token element, een van de verschillende gekoppelde objecten met namen/waarden in een gegevensverzameling. In dit voorbeeld is ook een antwoordheader van Content-Type: application/json opgenomen.

Uw clienttoepassing registreren bij Microsoft Entra ID

Voor de meeste Azure-services (zoals Azure Resource Manager-providers en het klassieke implementatiemodel) 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 Microsoft Entra ID en biedt uw client een toegangstoken als bewijs van de verificatie. Het token wordt vervolgens verzonden naar de Azure-service in de HTTP-autorisatieheader van 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 Microsoft Entra-verificatie gebruikt of als u uw client al hebt geregistreerd, gaat u naar de sectie De aanvraag maken.

Vereisten

Uw clienttoepassing moet de identiteitsconfiguratie bekend maken bij Microsoft Entra ID vóór runtime door deze te registreren in een Microsoft Entra-tenant. Voordat u uw client registreert bij Microsoft Entra ID, moet u rekening houden met de volgende vereisten:

• Zie Een Microsoft Entra-tenant instellen als u nog geen Microsoft Entra tenant hebt.

• In overeenstemming met het OAuth2 Authorization Framework ondersteunt Microsoft Entra ID twee typen clients. Als u elk begrijpt, kunt u bepalen wat het meest geschikt is voor uw scenario:

  • web-/vertrouwelijke clients worden uitgevoerd op een webserver en hebben toegang tot resources onder hun eigen identiteit (bijvoorbeeld een service of daemon) of verkrijgen gedelegeerde autorisatie voor toegang tot resources onder de identiteit van een aangemelde gebruiker (bijvoorbeeld een web-app). Alleen een webclient kan zijn eigen referenties veilig onderhouden en presenteren tijdens Microsoft Entra verificatie om een toegangstoken te verkrijgen.
  • systeemeigen/openbare clients worden geïnstalleerd en uitgevoerd op een apparaat. Ze hebben alleen toegang tot resources onder gedelegeerde autorisatie, waarbij ze de identiteit van de aangemelde gebruiker gebruiken om namens de gebruiker een toegangstoken te verkrijgen.

• Tijdens het registratieproces worden twee gerelateerde objecten gemaakt in de Microsoft Entra tenant waarin de toepassing is geregistreerd: een toepassingsobject en een service-principalobject. Zie Toepassings- en service-principalobjecten in Microsoft Entra ID voor meer informatie over deze onderdelen en hoe ze tijdens runtime worden gebruikt.

U bent nu klaar om uw clienttoepassing te registreren bij Microsoft Entra ID.

Clientregistratie

Als u een client wilt registreren die toegang heeft tot een Azure Resource Manager REST API, raadpleegt u Portal gebruiken om Microsoft Entra toepassing en service-principal te maken die toegang hebben tot resources. In het artikel (ook beschikbaar in PowerShell- en CLI-versies voor het automatiseren van registratie) wordt uitgelegd hoe u het volgende kunt doen:

• Registreer de clienttoepassing bij Microsoft Entra ID.
• Stel machtigingsaanvragen in om de client toegang te geven tot de Azure Resource Manager-API.
• Configureer RBAC-instellingen (Azure Resource Manager Role-Based Access Control) voor het autoriseren van de client.

Als uw client toegang heeft tot een andere API dan een Azure Resource Manager-API, raadpleegt u:

• Een toepassing registreren bij het Microsoft Identity Platform
  • Registreer de clienttoepassing met Microsoft Entra ID in de sectie Een toepassing registreren.
  • Maak een geheime sleutel (als u een webclient registreert) in de sectie Referenties toevoegen.
• Een toepassing configureren om een web-API beschikbaar te maken
  • Machtigingen toevoegen aan uw web-API en deze weergeven als bereiken
• Een clienttoepassing configureren voor toegang tot een web-API
  • Voeg machtigingsaanvragen toe zoals vereist voor de bereiken die voor de API zijn gedefinieerd, in de sectie 'Machtigingen toevoegen voor toegang tot uw web-API'.

Nu u de registratie van uw clienttoepassing hebt voltooid, gaat u verder met uw clientcode, waar u de REST-aanvraag maakt en het antwoord verwerkt.

De aanvraag maken

In deze sectie worden de eerste drie van de vijf onderdelen behandeld die we eerder hebben besproken. U moet eerst het toegangstoken verkrijgen van Microsoft Entra ID, dat u gebruikt om de berichtkop van de aanvraag samen te stellen.

Een toegangstoken verkrijgen

Nadat u een geldige clientregistratie hebt, kunt u op twee manieren integreren met Microsoft Entra ID om een toegangstoken te verkrijgen:

• Platform- en taalneutrale OAuth2-service-eindpunten, die we in dit artikel gebruiken. De instructies in deze sectie gaan niet uit van het platform of de taal/het script van uw client wanneer u de Microsoft Entra OAuth-eindpunten gebruikt. De enige vereiste is dat u HTTPS-aanvragen naar/van Microsoft Entra ID kunt verzenden/ontvangen en het antwoordbericht kunt parseren.
• De platform- en taalspecifieke Microsoft Authentication Libraries (MSAL), die buiten het bereik van dit artikel vallen. De bibliotheken bieden asynchrone wrappers voor de OAuth2-eindpuntaanvragen en robuuste functies voor het verwerken van tokens, zoals caching en vernieuwingstokenbeheer. Zie overzicht van Microsoft Authentication Library (MSAL) voor meer informatie.

De twee Microsoft Entra 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 ze 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 autorisatietoekenningen gebruikt: autorisatiecode of clientreferenties. Als u een toegangstoken wilt verkrijgen dat in de resterende secties wordt gebruikt, volgt u de instructies voor de stroom die het beste overeenkomt met uw scenario.

Autorisatiecode verlenen (interactieve clients)

Deze toekenning wordt gebruikt door zowel web- als systeemeigen clients, waarvoor referenties van een aangemelde gebruiker zijn vereist om resourcetoegang tot de clienttoepassing te delegeren. Het eindpunt wordt gebruikt voor het /authorize verkrijgen van een autorisatiecode (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 Microsoft Entra ID. Zie Een autorisatiecode aanvragen voor meer informatie over de indeling van de HTTPS GET-aanvraag voor het /authorize eindpunt en voorbeeld van aanvraag-/antwoordberichten. De URI bevat de volgende queryreeksparameters, die specifiek zijn voor uw clienttoepassing:

   • client_id: Een GUID die tijdens de registratie is toegewezen aan uw clienttoepassing, ook wel een toepassings-id genoemd.

   • redirect_uri: Een URL-gecodeerde versie van een van de antwoord-/omleidings-URI's die is opgegeven tijdens de registratie van uw clienttoepassing. De waarde die u doorgeeft, moet exact overeenkomen met uw registratiewaarde.

   • 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 in hun configuratie beschikbaar maken. Bijvoorbeeld:

     • Api's van Azure Resource Manager provider (en klassiek implementatiemodel) gebruiken https://management.core.windows.net/.
     • Zie de API-documentatie of de configuratie van de resourcetoepassing in de Azure Portal voor andere resources. Zie de eigenschap van het identifierUristoepassingsobject Microsoft Graph API voor meer informatie.

   De aanvraag voor het /authorize eindpunt activeert eerst een aanmeldingsprompt om de gebruiker 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 met de omleidings-URI, gevolgd door een code queryparameter. De code parameter bevat de autorisatiecode die u nodig hebt voor stap 2.

2. Vervolgens moet uw client de autorisatiecode inwisselen voor een toegangstoken. Zie Een toegangstoken aanvragen voor meer informatie over de indeling van de HTTPS POST-aanvraag voor het /token eindpunt en de voorbeelden van aanvragen/antwoorden. Omdat dit een POST-aanvraag is, verpakt u uw toepassingsspecifieke parameters in de aanvraagbody. Naast enkele van de eerder genoemde parameters (samen met andere nieuwe), geeft u het volgende door:

   • code: deze queryparameter bevat de autorisatiecode 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 wordt alleen gebruikt door webclients, waardoor de toepassing rechtstreeks toegang heeft tot resources (geen gebruikersdelegering) met behulp van de referenties van de client, die tijdens de registratie worden verstrekt. De toekenning wordt doorgaans gebruikt door niet-interactieve clients (geen gebruikersinterface) die als een service of daemon worden uitgevoerd. Alleen het eindpunt is vereist voor het /token verkrijgen van een toegangstoken.

De client-/resource-interacties voor deze toekenning zijn vergelijkbaar met stap 2 van de toekenning van de autorisatiecode. Zie de sectie 'Een token ophalen' in Microsoft identity platform en de OAuth 2.0-clientreferentiestroom voor meer informatie over de indeling van de HTTPS POST-aanvraag voor /token het eindpunt en de voorbeelden van aanvragen/antwoorden.

Het aanvraagbericht samenstellen

De meeste programmeertalen of frameworks en scriptomgevingen maken het eenvoudig om het aanvraagbericht samen te stellen en te verzenden. Ze bieden doorgaans een web-/HTTP-klasse of API die het maken of opmaken van de aanvraag abstraheert, waardoor het eenvoudiger wordt om de clientcode te schrijven (bijvoorbeeld de HttpWebRequest klasse in de .NET Framework). Kortheidshalve en omdat het grootste deel van de taak voor u wordt afgehandeld, worden in deze sectie alleen de belangrijke elementen van de aanvraag behandeld.

Aanvraag-URI

Omdat gevoelige informatie wordt verzonden en ontvangen, vereisen alle REST-aanvragen het HTTPS-protocol voor het URI-schema, waardoor de aanvraag en het antwoord een beveiligd kanaal krijgen. De informatie (de Microsoft Entra autorisatiecode, toegangs-/bearer-token en 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 alle vereiste queryreeksparameters) wordt bepaald door de bijbehorende REST API-specificatie. Azure Resource Manager provider-API's maken bijvoorbeeld gebruik https://management.azure.com/van en het klassieke Azure-implementatiemodel maakt gebruik https://management.core.windows.net/van . Voor beide is een api-version queryreeksparameter vereist.

Aanvraagheader

De aanvraag-URI wordt gebundeld in de berichtkop van de aanvraag, samen met eventuele aanvullende velden die zijn vereist voor de REST API-specificatie van uw service en de HTTP-specificatie. Voor uw aanvraag zijn mogelijk de volgende algemene headervelden vereist:

• Authorization: Bevat het OAuth2 Bearer-token om de aanvraag te beveiligen, zoals eerder verkregen van Microsoft Entra ID.
• Content-Type: Meestal ingesteld op 'application/json' (naam/waardeparen in JSON-indeling) en geeft u het MIME-type van de aanvraagbody op.
• Host: 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, bevat de API-specificatie voor de service die u aanvraagt ook de codering en indeling.

De aanvraagbody wordt gescheiden van de header door een lege regel, opgemaakt in overeenstemming met 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 en hoofdtekst van de aanvraag hebt gemaakt, bent u klaar om de aanvraag naar het REST-service-eindpunt te verzenden.

U kunt bijvoorbeeld een HTTPS GET-aanvraagmethode verzenden voor een Azure Resource Manager-provider met behulp van aanvraagheadervelden die vergelijkbaar zijn met de volgende (houd er rekening mee 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 u kunt een HTTPS PUT-aanvraagmethode verzenden voor een Azure Resource Manager-provider, met behulp van aanvraagheader- en hoofdtekstvelden die vergelijkbaar zijn met het volgende voorbeeld:

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

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

Het antwoordbericht verwerken

Het proces eindigt met de laatste twee van de vijf onderdelen.

Als u het antwoord wilt verwerken, parseert u de antwoordheader en optioneel de hoofdtekst van het antwoord (afhankelijk van de aanvraag). In het HTTPS GET-voorbeeld in de vorige sectie hebt u het eindpunt /subscriptions gebruikt om de lijst met abonnementen voor een gebruiker op te halen. Ervan uitgaande dat het antwoord is geslaagd, ontvangt u antwoordheadervelden die vergelijkbaar zijn met het volgende voorbeeld:

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

En u ontvangt een antwoordtekst met een lijst met Azure-abonnementen en hun afzonderlijke eigenschappen die zijn gecodeerd in JSON-indeling, vergelijkbaar met:

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

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

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

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

En u ontvangt een antwoordtekst die de inhoud bevestigt van uw zojuist toegevoegde resourcegroep gecodeerd in JSON-indeling, vergelijkbaar met:

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

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

Asynchrone bewerkingen, beperking en paging

Het patroon Create/Send/Process-Response dat in dit artikel wordt besproken, is synchroon en is van toepassing op alle REST-berichten. Sommige services ondersteunen echter ook een asynchroon patroon, waarvoor aanvullende verwerking van antwoordheaders nodig is om de asynchrone aanvraag te controleren of te voltooien. Zie Asynchrone Azure-bewerkingen bijhouden voor meer informatie.

Resource Manager past een limiet toe voor het aantal lees- en schrijfaanvragen per uur om te voorkomen dat een toepassing te veel aanvragen verzendt. Als uw toepassing deze limieten overschrijdt, worden aanvragen beperkt. De antwoordheader bevat het aantal resterende aanvragen voor uw bereik. Zie Resource Manager-aanvragen beperken voor meer informatie.

Sommige lijstbewerkingen retourneren een eigenschap met de naam nextLink in de hoofdtekst van het antwoord. U ziet deze eigenschap wanneer de resultaten te groot zijn om in één antwoord te worden geretourneerd. Normaal gesproken bevat het antwoord de eigenschap nextLink wanneer de lijstbewerking meer dan 1000 items retourneert. Wanneer nextLink niet aanwezig is in de resultaten, zijn de geretourneerde resultaten voltooid. Wanneer nextLink een URL bevat, maken de geretourneerde resultaten slechts deel uit van de totale resultatenset.

Het antwoord heeft de volgende indeling:

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

Als u de volgende pagina van de resultaten wilt ophalen, verzendt u een GET-aanvraag naar de URL in de eigenschap nextLink. De URL bevat een vervolgtoken om aan te geven waar u zich bevindt in de resultaten. Ga door met het verzenden van aanvragen naar de nextLink-URL totdat deze geen URL meer bevat in de geretourneerde resultaten.

Tolerantie van Azure-API's

De Azure REST API's zijn ontworpen voor tolerantie en continue beschikbaarheid. Besturingsvlakbewerkingen (aanvragen die naar management.azure.com worden verzonden) in de REST API zijn:

• Gedistribueerd over verschillende regio's. Sommige services zijn niet regionaal.

• Gedistribueerd over verschillende Beschikbaarheidszones (en over regio's) op locaties met meerdere Beschikbaarheidszones.

• Niet afhankelijk van één logisch datacentrum.

• Nooit offline gezet voor onderhoudsactiviteiten.

Gerelateerde inhoud

Dat is alles. Nadat u uw Microsoft Entra-toepassing hebt geregistreerd en een modulaire techniek hebt voor het verkrijgen van een toegangstoken en het verwerken van HTTP-aanvragen, is het vrij eenvoudig om uw code te repliceren om te profiteren van nieuwe REST API's. Zie de Microsoft identity platform documentatie voor meer informatie over toepassingsregistratie en het Microsoft Entra programmeermodel.

Zie voor informatie over het testen van HTTP-aanvragen/-antwoorden:

• Fiddler. Fiddler is een gratis proxy voor webfoutopsporing waarmee uw REST-aanvragen kunnen worden onderschept, zodat u eenvoudig een diagnose kunt uitvoeren voor de HTTP-aanvraag-/antwoordberichten.
• JWT.ms, waarmee u snel en eenvoudig de claims in uw Bearer-token kunt dumpen, zodat u de inhoud ervan kunt valideren.