Share via

Aanvragen verzenden naar de Azure Digital Twins-API's met postman

  • Artikel

Postman is een REST-testprogramma dat belangrijke HTTP-aanvraagfunctionaliteiten biedt in een desktop- en invoegtoepassings-GUI. U kunt deze gebruiken om HTTP-aanvragen te maken en deze in te dienen bij de Azure Digital Twins REST API's. In dit artikel wordt beschreven hoe u de Postman REST-client configureert voor interactie met de Azure Digital Twins-API's. Deze informatie is specifiek voor de Azure Digital Twins-service.

Dit artikel bevat informatie over de volgende stappen:

  1. Gebruik de Azure CLI om een Bearer-token op te halen dat u gaat gebruiken om API-aanvragen in Postman te maken.
  2. Stel een Postman-verzameling in en configureer de Postman REST-client om uw Bearer-token te gebruiken om te verifiëren. Wanneer u de verzameling instelt, kunt u een van de volgende opties kiezen:
    1. Importeer een vooraf gebouwde verzameling azure Digital Twins-API-aanvragen.
    2. Maak uw eigen verzameling helemaal zelf.
  3. Voeg aanvragen toe aan uw geconfigureerde verzameling en verzend deze naar de Azure Digital Twins-API's.

Azure Digital Twins heeft twee sets API's waarmee u kunt werken: gegevensvlak en besturingsvlak. Zie Azure Digital Twins-API's en SDK's voor meer informatie over het verschil tussen deze API-sets. Dit artikel bevat informatie voor beide API-sets.

Vereisten

Als u Postman wilt gebruiken voor toegang tot de Azure Digital Twins-API's, moet u een Azure Digital Twins-exemplaar instellen en Postman downloaden. In de rest van deze sectie krijgt u stapsgewijze instructies.

Een Azure Digital Twins-exemplaar instellen

Als u met Azure Digital Twins in dit artikel wilt werken, hebt u een Azure Digital Twins-exemplaar en de vereiste machtigingen nodig om deze te gebruiken. Als u al een Azure Digital Twins-exemplaar hebt ingesteld, kunt u dat exemplaar gebruiken en doorgaan naar de volgende sectie. Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om te controleren of u elke stap hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de hostnaam van het exemplaar. U vindt de hostnaam in Azure Portal.

Postman downloaden

Download vervolgens de bureaubladversie van de Postman-client.

Bearer-token ophalen

Nu u Postman en uw Azure Digital Twins-exemplaar hebt ingesteld, moet u een bearer-token ophalen dat Postman-aanvragen kunnen gebruiken om te autoriseren voor de Azure Digital Twins-API's.

Er zijn verschillende manieren om dit token te verkrijgen. In dit artikel wordt de Azure CLI gebruikt om u aan te melden bij uw Azure-account en een token te verkrijgen.

Als u een Azure CLI lokaal hebt geïnstalleerd, kunt u een opdrachtprompt op uw computer starten om de volgende opdrachten uit te voeren. Anders kunt u een Azure Cloud Shell-venster openen in uw browser en de opdrachten daar uitvoeren.

  1. Controleer eerst of u bent aangemeld bij Azure met de juiste referenties door deze opdracht uit te voeren:

    az login

  2. Gebruik vervolgens de opdracht az account get-access-token om een bearer-token op te halen met toegang tot de Azure Digital Twins-service. In deze opdracht geeft u de resource-id voor het Azure Digital Twins-service-eindpunt door om een toegangstoken op te halen dat toegang heeft tot Azure Digital Twins-resources.

    De vereiste context voor het token is afhankelijk van de set API's die u gebruikt. Gebruik daarom de volgende tabbladen om te selecteren tussen api's van het gegevensvlak en het besturingsvlak .

    Gebruik de volgende statische waarde voor de tokencontext om een token op te halen dat moet worden gebruikt met de API's van het gegevensvlak: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 Deze waarde is de resource-id voor het Azure Digital Twins-service-eindpunt.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Notitie

    Als u toegang wilt krijgen tot uw Azure Digital Twins-exemplaar met behulp van een service-principal of gebruikersaccount dat deel uitmaakt van een andere Microsoft Entra-tenant van het exemplaar, moet u een token aanvragen bij de 'home'-tenant van het Azure Digital Twins-exemplaar. Zie App-verificatiecode schrijven voor meer informatie over dit proces.

  3. Kopieer de waarde van accessToken het resultaat en sla deze op voor gebruik in de volgende sectie. Deze waarde is uw tokenwaarde die u aan Postman opgeeft om uw aanvragen te autoriseren.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Fooi

Dit token is minimaal vijf minuten geldig en maximaal 60 minuten. Als u onvoldoende tijd hebt toegewezen voor het huidige token, kunt u de stappen in deze sectie herhalen om een nieuw token op te halen.

Vervolgens stelt u Postman in om dit token te gebruiken om API-aanvragen te doen bij Azure Digital Twins.

Over Postman-verzamelingen

Aanvragen in Postman worden opgeslagen in verzamelingen (groepen aanvragen). Wanneer u een verzameling maakt om uw aanvragen te groeperen, kunt u algemene instellingen toepassen op veel aanvragen tegelijk. Algemene instellingen kunnen autorisatie aanzienlijk vereenvoudigen als u van plan bent om meer dan één aanvraag te maken voor de Azure Digital Twins-API's, omdat u deze gegevens slechts eenmaal hoeft te configureren voor de hele verzameling.

Wanneer u met Azure Digital Twins werkt, kunt u aan de slag gaan door een vooraf gebouwde verzameling van alle Azure Digital Twins-aanvragen te importeren. U kunt deze verzameling importeren als u de API's verkent en snel een project wilt instellen met aanvraagvoorbeelden.

U kunt er ook voor kiezen om helemaal opnieuw te beginnen door uw eigen lege verzameling te maken en deze te vullen met afzonderlijke aanvragen die alleen de API's aanroepen die u nodig hebt.

In de volgende secties worden beide processen beschreven. De rest van het artikel vindt plaats in uw lokale Postman-toepassing, dus open nu de Postman-toepassing op uw computer.

Verzameling Azure Digital Twins-API's importeren

Een snelle manier om aan de slag te gaan met Azure Digital Twins in Postman is het importeren van een vooraf gebouwde verzameling aanvragen voor de API's. Volg de onderstaande stappen om een verzameling populaire Azure Digital Twins-api-aanvragen met voorbeeldaanvraaggegevens te importeren.

  1. Selecteer in het hoofdvenster van Postman de knop Importeren . Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Selecteer in het volgende venster Importeren de optie Koppeling en voer de volgende URL in: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Selecteer Vervolgens Importeren om te bevestigen.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

De zojuist geïmporteerde verzameling kan nu worden weergegeven vanuit de hoofdweergave van Postman, op het tabblad Verzamelingen.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Fooi

Als u de volledige set API-aanroepen wilt importeren voor een bepaalde versie van de Azure Digital Twins-API's (inclusief besturingsvlak of gegevensvlak), kunt u ook Swagger-bestanden als verzamelingen importeren. Zie Azure Digital Twins-API's en SDK's voor koppelingen naar de Swagger-bestanden voor de besturingsvlak- en gegevensvlak-API's.

Ga vervolgens verder met de volgende sectie om een Bearer-token toe te voegen aan de verzameling voor autorisatie en deze te verbinden met uw Azure Digital Twins-exemplaar.

Autorisatie configureren

Bewerk vervolgens de verzameling die u hebt gemaakt om bepaalde toegangsgegevens te configureren. Markeer de verzameling die u hebt gemaakt en selecteer het pictogram Meer acties weergeven om actieopties weer te geven. Selecteer Bewerken.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Volg deze stappen om een Bearer-token toe te voegen aan de verzameling voor autorisatie. Gebruik de tokenwaarde die u hebt verzameld in de sectie Bearer-token ophalen om deze te gebruiken voor alle API-aanvragen in uw verzameling.

  1. Controleer in het dialoogvenster Bewerken voor uw verzameling of u zich op het tabblad Autorisatie bevindt.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Stel het type in op OAuth 2.0 en plak het toegangstoken in het vak Toegangstoken. U moet het juiste token gebruiken voor het type API dat u gebruikt, omdat er verschillende tokens zijn voor API's van het gegevensvlak versus API's van het besturingsvlak. Selecteer Opslaan.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Fooi

    U kunt ervoor kiezen om token delen in te schakelen als u het token wilt opslaan met de aanvraag in de Postman-cloud en uw token mogelijk met anderen wilt delen.

Andere configuratie

U kunt de verzameling helpen eenvoudig verbinding te maken met uw Azure Digital Twins-resources door enkele variabelen in te stellen die bij de verzameling worden geleverd. Wanneer veel aanvragen in een verzameling dezelfde waarde vereisen (zoals de hostnaam van uw Azure Digital Twins-exemplaar), kunt u de waarde opslaan in een variabele die van toepassing is op elke aanvraag in de verzameling. De Azure Digital Twins-verzameling wordt geleverd met vooraf gemaakte variabelen die u op verzamelingsniveau kunt instellen.

  1. Ga in het bewerkingsdialoogvenster voor uw verzameling naar het tabblad Variabelen .

  2. Gebruik de volgende tabel om de waarden van de variabelen in de verzameling in te stellen:

    Variabel API-set Omschrijving
    digitaltwins-hostname Gegevenslaag De hostnaam van uw Azure Digital Twins-exemplaar. U vindt deze waarde op de overzichtspagina voor uw exemplaar in de portal.
    subscriptionId Besturingsvlak Uw Azure-abonnements-id.
    digitalTwinInstance Besturingsvlak De naam van uw Azure Digital Twins-exemplaar.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Als uw verzameling extra variabelen heeft, kunt u deze waarden ook doorvoeren en opslaan.

  4. Selecteer Opslaan.

Wanneer u klaar bent met de bovenstaande stappen, bent u klaar met het configureren van de verzameling. U kunt desgewenst het tabblad Bewerken voor de verzameling sluiten.

Aanvragen verkennen

Verken vervolgens de aanvragen in de Azure Digital Twins API-verzameling. U kunt de verzameling uitbreiden om de vooraf gemaakte aanvragen weer te geven (gesorteerd op categorie van bewerking).

Voor verschillende aanvragen is verschillende informatie over uw exemplaar en de bijbehorende gegevens vereist. Als u alle informatie wilt zien die nodig is om een bepaalde aanvraag te maken, zoekt u de aanvraagdetails op in de naslagdocumentatie voor de Azure Digital Twins REST API.

U kunt de details van een aanvraag in de Postman-verzameling bewerken met behulp van deze stappen:

  1. Selecteer deze in de lijst om de bewerkbare details op te halen.

  2. De meeste aanvragen in de voorbeeldverzameling zijn vooraf geconfigureerd om te worden uitgevoerd zonder verdere wijzigingen aan te brengen.

  3. In de volgende schermopname ziet u de Api DigitalTwinModels Add . Op het tabblad Hoofdtekst ziet u de JSON-nettolading waarmee het nieuwe model wordt gedefinieerd dat moet worden toegevoegd:

  4. Vul waarden in voor de variabelen die worden vermeld op het tabblad Params onder Padvariabelen.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Gebruik de knop Verzenden om de aanvraag uit te voeren.

U kunt ook uw eigen aanvragen toevoegen aan de verzameling met behulp van het proces dat wordt beschreven in de sectie Een afzonderlijke aanvraag toevoegen.

Uw eigen verzameling maken

In plaats van de bestaande verzameling azure Digital Twins-API's te importeren, kunt u ook uw eigen verzameling helemaal zelf maken. U kunt deze vervolgens vullen met afzonderlijke aanvragen met behulp van de naslagdocumentatie voor de Azure Digital Twins REST API.

Een Postman-verzameling maken

  1. Als u een verzameling wilt maken, selecteert u de knop Nieuw in het hoofdvenster van Postman.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Kies een type verzameling.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Er wordt een tabblad geopend. Vul de details van de nieuwe verzameling in. Selecteer het pictogram Bewerken naast de standaardnaam van de verzameling (Nieuwe verzameling) om deze te vervangen door uw eigen naam.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Ga vervolgens verder met de volgende sectie om een bearer-token toe te voegen aan de verzameling voor autorisatie.

Autorisatie configureren

Volg deze stappen om een Bearer-token toe te voegen aan de verzameling voor autorisatie. Gebruik de tokenwaarde die u hebt verzameld in de sectie Bearer-token ophalen om deze te gebruiken voor alle API-aanvragen in uw verzameling.

  1. Ga in het bewerkingsdialoogvenster voor uw nieuwe verzameling naar het tabblad Autorisatie .

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Stel het type in op OAuth 2.0, plak uw toegangstoken in het vak Toegangstoken en selecteer Opslaan.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Wanneer u klaar bent met de bovenstaande stappen, bent u klaar met het configureren van de verzameling. U kunt desgewenst het tabblad Bewerken voor de nieuwe verzameling sluiten.

De nieuwe verzameling is te zien vanuit de hoofdweergave van Postman, op het tabblad Verzamelingen.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Een afzonderlijke aanvraag toevoegen

Nu uw verzameling is ingesteld, kunt u uw eigen aanvragen toevoegen aan de Azure Digital Twin-API's.

  1. Als u een aanvraag wilt maken, gebruikt u de knop Nieuw opnieuw.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Kies een type aanvraag.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Met deze actie opent u het venster SAVE REQUEST, waarin u een naam voor uw aanvraag kunt invoeren, een optionele beschrijving kunt geven en de verzameling kunt kiezen waarvan deze deel uitmaakt. Vul de details in en sla de aanvraag op in de verzameling die u eerder hebt gemaakt.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

U kunt uw aanvraag nu bekijken onder de verzameling en deze selecteren om de bewerkbare details op te halen.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Aanvraagdetails instellen

Als u een Postman-aanvraag wilt indienen bij een van de Azure Digital Twins-API's, hebt u de URL van de API en informatie nodig over de details die nodig zijn. U vindt deze informatie in de naslagdocumentatie voor azure Digital Twins REST API.

Als u wilt doorgaan met een voorbeeldquery, gebruikt dit artikel de Azure Digital Twins Query-API om een query uit te voeren op alle digitale dubbels in een exemplaar.

  1. Haal de aanvraag-URL en het type op uit de referentiedocumentatie. Voor de Query-API is dit momenteel POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. Stel in Postman het type voor de aanvraag in en voer de aanvraag-URL in, waarbij u indien nodig tijdelijke aanduidingen in de URL invult. Gebruik de hostnaam van uw exemplaar in de sectie Vereisten.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Controleer of de parameters voor de aanvraag op het tabblad Params overeenkomen met de parameters die worden beschreven in de referentiedocumentatie. Voor deze aanvraag in Postman werd de api-version parameter automatisch ingevuld toen de aanvraag-URL in de vorige stap werd ingevoerd. Voor de Query-API is dit de enige vereiste parameter, dus deze stap wordt uitgevoerd.

  4. Stel op het tabblad Autorisatie het type in op Verificatie overnemen van bovenliggend item. Dit geeft aan dat deze aanvraag gebruikmaakt van de autorisatie die u eerder hebt ingesteld voor de hele verzameling.

  5. Controleer of de headers die worden weergegeven voor de aanvraag op het tabblad Headers overeenkomen met de headers die in de referentiedocumentatie worden beschreven. Voor deze aanvraag zijn verschillende headers automatisch ingevuld. Voor de Query-API zijn geen van de headeropties vereist, dus deze stap wordt uitgevoerd.

  6. Controleer of de hoofdtekst voor de aanvraag op het tabblad Hoofdtekst overeenkomt met de behoeften die in de referentiedocumentatie worden beschreven. Voor de Query-API is een JSON-hoofdtekst vereist om de querytekst op te geven. Hier volgt een voorbeeldtekst voor deze aanvraag die query's voor alle digitale dubbels in het exemplaar opvraagt:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Zie Query's uitvoeren op de tweelinggrafiek voor meer informatie over het maken van Azure Digital Twins-query's.

  7. Raadpleeg de referentiedocumentatie voor andere velden die mogelijk vereist zijn voor uw type aanvraag. Voor de Query-API is nu voldaan aan alle vereisten in de Postman-aanvraag, dus deze stap wordt uitgevoerd.

  8. Gebruik de knop Verzenden om uw voltooide aanvraag te verzenden. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Nadat de aanvraag is verzonden, worden de antwoordgegevens weergegeven in het Postman-venster onder de aanvraag. U kunt de statuscode van het antwoord en elke hoofdtekst bekijken.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

U kunt het antwoord ook vergelijken met de verwachte antwoordgegevens in de referentiedocumentatie om het resultaat te controleren of meer te weten te komen over eventuele fouten die zich voordoen.

Volgende stappen

Lees Azure Digital Twins-API's en SDK's voor meer informatie over de Digital Twins-API's of bekijk de referentiedocumentatie voor de REST API's.