Postman gebruiken om aanvragen te verzenden naar Azure Digital Twins API's

  • Artikel
  • 13 minuten om te lezen

Postman is een REST-testprogramma dat belangrijke HTTP-aanvraagfunctionaliteiten biedt in een bureaublad en gui op basis van invoegtoepassing. U kunt deze gebruiken om HTTP-aanvragen te maken en deze te verzenden naar Azure Digital Twins REST API's.

In dit artikel wordt beschreven hoe u de Postman REST-client configureert voor interactie met Azure Digital Twins API's door de volgende stappen uit te voeren:

  1. Gebruik de Azure CLI om een Bearer-token op te halen dat u gaat gebruiken om API-aanvragen te maken in Postman.
  2. Stel een Postman-verzameling in en configureer de Postman REST-client om uw Bearer-token te gebruiken voor verificatie. Bij het instellen van de verzameling kunt u een van de volgende opties kiezen:
    1. Importeer een vooraf gebouwde verzameling van Azure Digital Twins API-aanvragen.
    2. Maak uw eigen verzameling vanaf het begin.
  3. Voeg aanvragen toe aan de geconfigureerde verzameling en verzend deze naar de Azure Digital Twins API's.

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

Vereisten

Als u wilt doorgaan met het gebruik van Postman voor toegang tot de Azure Digital Twins API's, moet u een Azure Digital Twins 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, moet u eerst een Azure Digital Twins instellen. U hebt ook de vereiste machtigingen nodig om deze te kunnen gebruiken. Als u al een Azure Digital Twins hebt ingesteld, kunt u deze in plaats daarvan gebruiken.

Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om u te helpen controleren of u elke stap met succes hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de volgende waarden. U hebt deze waarden later nodig om verbinding te maken met het exemplaar:

  • De hostnaam van het exemplaar. U vindt de hostnaam in de Azure Portal.
  • Het Azure-abonnement dat u hebt gebruikt om het exemplaar te maken. De naam of id werkt. U vindt het abonnement op de pagina Overzicht van uw exemplaar in Azure Portal.

Postman downloaden

Download vervolgens de desktopversie van de Postman-client.

Bearer-token op halen

Nu u Postman en uw Azure Digital Twins-exemplaar hebt ingesteld, moet u een Bearer-token krijgen dat Postman-aanvragen kunnen gebruiken om te autoreren 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 op die manier 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 venster Azure Cloud Shell in uw browser openen en de opdrachten daar uitvoeren.

  1. Zorg er eerst voor dat u met de juiste referenties bent aangemeld bij Azure 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 toegangsken op te halen dat toegang heeft tot Azure Digital Twins resources.

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

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

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

    Notitie

    Als u toegang nodig hebt tot uw Azure Digital Twins-exemplaar met behulp van een service-principal of gebruikersaccount dat bij een andere Azure Active Directory-tenant van het exemplaar hoort, moet u een token aanvragen bij de tenant 'home' van het Azure Digital Twins-exemplaar. Zie App-verificatiecode schrijven voor meer informatie over dit proces.

  3. Kopieer de waarde van accessToken in het resultaat en sla deze op voor gebruik in de volgende sectie. Dit is de waarde van uw token die u aan Postman geeft om uw aanvragen te autor toestemming te geven.

    Schermopname van de console met het resultaat van de opdracht az account get-access-token. Het veld accessToken en de voorbeeldwaarde zijn gemarkeerd.

Tip

Dit token is ten minste vijf minuten en maximaal 60 minuten geldig. Als er geen tijd meer is 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 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 op veel aanvragen tegelijk toepassen. Dit kan de autorisatie sterk 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 één keer 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 importeren. U kunt dit doen 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. Open nu de Postman-toepassing op uw computer.

Verzameling van Azure Digital Twins API's importeren

Een snelle manier om aan de slag te Azure Digital Twins in Postman is door een vooraf gebouwde verzameling aanvragen te importeren voor de Azure Digital Twins API's.

Het verzamelingsbestand downloaden

De eerste stap bij het importeren van de API-set is het downloaden van een verzameling. Kies het tabblad hieronder voor uw keuze van gegevensvlak of besturingsvlak om de vooraf gebouwde verzamelingsopties te bekijken.

Er zijn momenteel twee Azure Digital Twins gegevensvlakverzamelingen waar u uit kunt kiezen:

  • Azure Digital Twins Postman Collection:deze verzameling biedt een eenvoudige aan de slag-ervaring voor Azure Digital Twins in Postman. De aanvragen bevatten voorbeeldgegevens, zodat u ze met minimale bewerkingen kunt uitvoeren. Kies deze verzameling als u een samenvattingsset met belangrijke API-aanvragen met voorbeeldgegevens wilt.
    • Als u de verzameling wilt zoeken, gaat u naar de koppeling naar de repo en opent u het bestand postman_collection.json.
  • Azure Digital Twins gegevensvlak Swagger:deze repo bevat het volledige Swagger-bestand voor de Azure Digital Twins API-set, dat als verzameling kan worden gedownload en geïmporteerd in Postman. Dit biedt een uitgebreide set van elke API-aanvraag, maar met lege gegevens in plaats van voorbeeldgegevens. Kies deze verzameling als u toegang wilt hebben tot elke API-aanroep en vul alle gegevens zelf in.
    • Als u de verzameling wilt zoeken, gaat u naar de koppeling naar de repo en kiest u de map voor de nieuwste specificatieversie. Open hier het bestand met de naam digitaltwins.json.

Hier ziet u hoe u de gekozen verzameling downloadt naar uw computer, zodat u deze kunt importeren in Postman.

  1. Gebruik de bovenstaande koppelingen om het verzamelingsbestand te openen in GitHub in uw browser.
  2. Selecteer de knop Onbewerkt om de onbewerkte tekst van het bestand te openen. Schermopname van het gegevensvlakbestand digitaltwins.json in GitHub. Er is een markering rond de knop Onbewerkt.
  3. Kopieer de tekst uit het venster en plak deze in een nieuw bestand op uw computer.
  4. Sla het bestand op met de extensie .json (de bestandsnaam mag zijn wat u wilt, zolang u het maar kunt onthouden om het bestand later te vinden).

De verzameling importeren

Importeer vervolgens de verzameling in Postman.

  1. Selecteer in het hoofdvenster van Postman de knop Importeren. Schermopname van een nieuw geopend Postman-venster. De knop Importeren is gemarkeerd.

  2. Selecteer in het volgende venster Importeren de optie Upload bestanden en navigeer naar het verzamelingsbestand op de computer die u eerder hebt gemaakt. Selecteer Openen.

  3. Selecteer de knop Importeren om te bevestigen.

    Schermopname van het venster 'Importeren' van Postman, met het bestand dat moet worden geïmporteerd als een verzameling en de knop Importeren.

De zojuist geïmporteerde verzameling is nu te zien in de hoofdweergave van Postman, op het tabblad Verzamelingen.

Schermopname van het hoofdvenster van Postman. De zojuist geïmporteerde verzameling is gemarkeerd op het tabblad Verzamelingen.

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 enkele toegangsgegevens te configureren. Markeer de verzameling die u hebt gemaakt en selecteer het pictogram Meer acties weergeven om een menu op te halen. Selecteer Bewerken.

Schermopname van Postman. Het pictogram Meer acties weergeven voor de geïmporteerde verzameling is gemarkeerd en 'Bewerken' is gemarkeerd in de opties.

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

  1. Zorg ervoor dat u zich in het bewerkingsdialoogvenster voor uw verzameling op het tabblad Autorisatie hebt.

    Schermopname van het dialoogvenster voor het bewerken van de geïmporteerde verzameling in Postman, met het tabblad Autorisatie.

  2. Stel Type in op OAuth 2.0, plak uw toegangsteken in het vak Toegangs token en selecteer Opslaan.

    Schermopname van het dialoogvenster Postman bewerken voor de geïmporteerde verzameling op het tabblad Autorisatie. Type is OAuth 2.0 en het vak Toegangs token is gemarkeerd.

Aanvullende configuratie

Als u een gegevensvlakverzameling maakt, helpt u de verzameling om eenvoudig verbinding te maken met uw Azure Digital Twins resources door enkele variabelen in te stellen die bij de verzamelingen worden geleverd. Wanneer voor veel aanvragen in een verzameling dezelfde waarde is vereist (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. Beide downloadbare verzamelingen voor Azure Digital Twins worden met vooraf gemaakte variabelen die u op verzamelingsniveau kunt instellen.

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

  2. Gebruik de hostnaam van uw exemplaar uit de sectie Vereisten om het veld CURRENT VALUE van de relevante variabele in te stellen. Selecteer Opslaan.

    Schermopname van het dialoogvenster voor het bewerken van de geïmporteerde verzameling in Postman, met het tabblad Variabelen. Het veld HUIDIGE WAARDE is gemarkeerd.

  3. Als uw verzameling aanvullende variabelen heeft, vult u deze waarden in en sla u deze op.

Wanneer u klaar bent met de bovenstaande stappen, bent u klaar met het configureren van de verzameling. U kunt het bewerkingstabblad voor de verzameling sluiten als u wilt.

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 bewerkingscategorie).

Voor verschillende aanvragen is andere informatie over uw exemplaar en de gegevens ervan vereist. Als u alle informatie wilt zien die nodig is om een bepaalde aanvraag te maken, bekijkt u de aanvraagdetails in Azure Digital Twins REST API referentiedocumentatie.

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

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

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

    Schermopname van Postman. De verzameling wordt uitgebreid om een aanvraag weer te geven. De sectie Padvariabelen is gemarkeerd in de aanvraagdetails.

  3. Geef alle benodigde headers of hoofdtekstdetails op op de desbetreffende tabbladen.

Zodra alle vereiste gegevens zijn opgegeven, kunt u de aanvraag uitvoeren met de knop Verzenden.

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 hieronder.

Uw eigen verzameling maken

In plaats van de bestaande verzameling van alle 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 Azure Digital Twins REST API referentiedocumentatie.

Een Postman-verzameling maken

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

    Schermopname van het hoofdvenster van Postman. De knop Nieuw is gemarkeerd.

    Kies een type verzameling.

    Schermopname van het dialoogvenster Nieuwe maken in Postman. De optie Verzameling is gemarkeerd.

  2. Hiermee opent u een tabblad voor het invullen van de details van de nieuwe verzameling. Selecteer het pictogram Bewerken naast de standaardnaam van de verzameling (Nieuwe verzameling) om deze te vervangen door uw eigen naam.

    Schermopname van het bewerkingsdialoogvenster van de nieuwe verzameling in Postman. Het pictogram Bewerken naast de naam Nieuwe verzameling is gemarkeerd.

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. Hier gebruikt u 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 nog steeds in het bewerkingsdialoogvenster voor uw nieuwe verzameling naar het tabblad Autorisatie.

    Schermopname van het dialoogvenster voor het bewerken van de nieuwe verzameling in Postman, met het tabblad Autorisatie.

  2. Stel Type in op OAuth 2.0, plak uw toegangsteken in het vak Toegangs token en selecteer Opslaan.

    Schermopname van het dialoogvenster Postman bewerken voor de nieuwe verzameling op het tabblad Autorisatie. Type is OAuth 2.0 en het vak Toegangs token is gemarkeerd.

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

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

Schermopname van het hoofdvenster van Postman. De zojuist gemaakte aangepaste verzameling is gemarkeerd op het tabblad Verzamelingen.

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 opnieuw de knop Nieuw.

    Schermopname van het hoofdvenster van Postman. De knop Nieuw is gemarkeerd.

    Kies een type aanvraag.

    Schermopname van het dialoogvenster Nieuwe maken in Postman. De optie 'Aanvraag' is gemarkeerd.

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

    Schermopname van het venster Aanvraag opslaan in Postman met de beschreven velden. De knop Opslaan Azure Digital Twins verzameling is gemarkeerd.

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

Schermopname van Postman. De Azure Digital Twins verzameling wordt uitgebreid om de details van de aanvraag weer te geven.

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 Azure Digital Twins REST API referentiedocumentatie.

Als u wilt doorgaan met een voorbeeldquery, gebruikt dit artikel de Query-API (en de referentiedocumentatie )om een query uit te voeren op alle digitale tweelingen in een exemplaar.

  1. Haal de aanvraag-URL op en typ in de referentiedocumentatie. Voor de Query-API is dit momenteel POST. https://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 en vul waar nodig tijdelijke aanduidingen in de URL in. Hier gebruikt u de hostnaam van uw exemplaar in de sectie Vereisten.

    Schermopname van de details van de nieuwe aanvraag in Postman. De query-URL uit de referentiedocumentatie is ingevuld in het vak aanvraag-URL.

  3. Controleer of de parameters voor de aanvraag op het tabblad Parameters overeenkomen met de parameters die worden beschreven in de referentiedocumentatie. Voor deze aanvraag in Postman is 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 bovenliggende. Dit geeft aan dat deze aanvraag de autorisatie gebruikt die u eerder hebt ingesteld voor de hele verzameling.

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

  6. Controleer of de hoofd body die wordt weergegeven voor de aanvraag op het tabblad Body overeenkomt met de behoeften die worden beschreven in de referentiedocumentatie. Voor de Query-API is een JSON-body vereist om de querytekst op te geven. Hier is een voorbeeld van een body voor deze aanvraag die een query op alle digitale tweelingen in het exemplaar opvraagt:

    Schermopname van de details van de nieuwe aanvraag in Postman, op het tabblad Hoofd hoofd. Deze bevat een onbewerkte JSON-body met de query SELECT * FROM DIGITALTWINS.

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

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

  8. Gebruik de knop Verzenden om uw voltooide aanvraag te verzenden. Schermopname van Postman met de details van de nieuwe aanvraag. De knop Verzenden is gemarkeerd.

Na het verzenden van de aanvraag worden de antwoorddetails weergegeven in het Postman-venster onder de aanvraag. U kunt de statuscode van het antwoord en alle tekst in de tekst bekijken.

Schermopname van de verzonden aanvraag in Postman. Onder de aanvraagdetails wordt het antwoord weergegeven. De status is 200 OK en de body geeft queryresultaten weer.

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 voor meer informatie Digital Twins API's Azure Digital Twins API's en SDK'sof bekijk de referentiedocumentatie voor de REST API's.