Share via

Så här skickar du begäranden till Azure Digital Twins-API:er med Postman

  • Artikel

Postman är ett REST-testverktyg som tillhandahåller viktiga funktioner för HTTP-begäranden i ett skrivbords- och plugin-baserat GUI. Du kan använda den för att skapa HTTP-begäranden och skicka dem till Rest-API:erna för Azure Digital Twins. Den här artikeln beskriver hur du konfigurerar Postman REST-klienten så att den interagerar med Azure Digital Twins-API:erna. Den här informationen är specifik för Azure Digital Twins-tjänsten.

Den här artikeln innehåller information om följande steg:

  1. Använd Azure CLI för att hämta en ägartoken som du använder för att göra API-begäranden i Postman.
  2. Konfigurera en Postman-samling och konfigurera Postman REST-klienten så att den använder din ägartoken för att autentisera. När du konfigurerar samlingen kan du välja något av följande alternativ:
    1. Importera en fördefinierad samling Azure Digital Twins API-begäranden.
    2. Skapa en egen samling från grunden.
  3. Lägg till begäranden i din konfigurerade samling och skicka dem till Azure Digital Twins-API:erna.

Azure Digital Twins har två uppsättningar API:er som du kan arbeta med: dataplan och kontrollplan. Mer information om skillnaden mellan dessa API-uppsättningar finns i Azure Digital Twins-API:er och SDK:er. Den här artikeln innehåller information för båda API-uppsättningarna.

Förutsättningar

Om du vill fortsätta använda Postman för att få åtkomst till Azure Digital Twins-API:erna måste du konfigurera en Azure Digital Twins-instans och ladda ned Postman. Resten av det här avsnittet beskriver de här stegen.

Konfigurera Azure Digital Twins-instans

För att arbeta med Azure Digital Twins i den här artikeln behöver du en Azure Digital Twins-instans och de behörigheter som krävs för att använda den. Om du redan har konfigurerat en Azure Digital Twins-instans kan du använda den instansen och gå vidare till nästa avsnitt. Annars följer du anvisningarna i Konfigurera en instans och autentisering. Anvisningarna innehåller information som hjälper dig att kontrollera att du har slutfört varje steg.

När du har konfigurerat instansen antecknar du instansens värdnamn. Du hittar värdnamnet i Azure-portalen.

Ladda ned Postman

Ladda sedan ned skrivbordsversionen av Postman-klienten.

Hämta ägartoken

Nu när du har konfigurerat Postman och din Azure Digital Twins-instans måste du hämta en ägartoken som Postman-begäranden kan använda för att auktorisera mot Azure Digital Twins-API:erna.

Det finns flera möjliga sätt att hämta den här token. Den här artikeln använder Azure CLI för att logga in på ditt Azure-konto och hämta en token.

Om du har en Azure CLI installerad lokalt kan du starta en kommandotolk på datorn för att köra följande kommandon. Annars kan du öppna ett Azure Cloud Shell-fönster i webbläsaren och köra kommandona där.

  1. Kontrollera först att du är inloggad i Azure med lämpliga autentiseringsuppgifter genom att köra det här kommandot:

    az login

  2. Använd sedan kommandot az account get-access-token för att hämta en ägartoken med åtkomst till Azure Digital Twins-tjänsten. I det här kommandot skickar du resurs-ID:t för Azure Digital Twins-tjänstslutpunkten för att få en åtkomsttoken som kan komma åt Azure Digital Twins-resurser.

    Vilken kontext som krävs för token beror på vilken uppsättning API:er du använder, så använd följande flikar för att välja mellan API:er för dataplan och kontrollplan .

    Om du vill hämta en token som ska användas med API:erna för dataplanet använder du följande statiska värde för tokenkontexten: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Det här värdet är resurs-ID:t för Azure Digital Twins-tjänstslutpunkten.

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

    Kommentar

    Om du behöver komma åt din Azure Digital Twins-instans med hjälp av tjänstens huvudnamn eller användarkonto som tillhör en annan Microsoft Entra-klient från instansen måste du begära en token från Azure Digital Twins-instansens "hem"-klientorganisation. Mer information om den här processen finns i Skriva appautentiseringskod.

  3. Kopiera värdet accessToken för i resultatet och spara det som ska användas i nästa avsnitt. Det här värdet är ditt tokenvärde som du anger för Postman för att auktorisera dina begäranden.

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

Dricks

Den här token är giltig i minst fem minuter och högst 60 minuter. Om tiden för den aktuella token tar slut kan du upprepa stegen i det här avsnittet för att hämta en ny.

Därefter konfigurerar du Postman för att använda den här token för att göra API-begäranden till Azure Digital Twins.

Om Postman-samlingar

Begäranden i Postman sparas i samlingar (grupper med begäranden). När du skapar en samling för att gruppera dina begäranden kan du använda vanliga inställningar för många begäranden samtidigt. Vanliga inställningar kan förenkla auktoriseringen avsevärt om du planerar att skapa fler än en begäran mot Azure Digital Twins-API:erna, eftersom du bara behöver konfigurera den här informationen en gång för hela samlingen.

När du arbetar med Azure Digital Twins kan du komma igång genom att importera en fördefinierad samling av alla Azure Digital Twins-begäranden. Du kanske vill importera den här samlingen om du utforskar API:erna och vill konfigurera ett projekt snabbt med exempel på begäran.

Du kan också välja att börja från början genom att skapa en egen tom samling och fylla den med enskilda begäranden som endast anropar de API:er du behöver.

I följande avsnitt beskrivs båda dessa processer. Resten av artikeln äger rum i ditt lokala Postman-program, så gå vidare och öppna Postman-programmet på datorn nu.

Importera samling Azure Digital Twins-API:er

Ett snabbt sätt att komma igång med Azure Digital Twins i Postman är att importera en fördefinierad samling begäranden för API:erna. Följ stegen nedan för att importera en samling populära API-begäranden för Azure Digital Twins-dataplan som innehåller exempelbegärandedata.

  1. I postman-huvudfönstret väljer du knappen Importera . Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. I fönstret Importera som följer väljer du Länka och anger följande URL: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Välj sedan Importera för att bekräfta.

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

Den nyligen importerade samlingen kan nu ses från din huvudsakliga Postman-vy på fliken Samlingar.

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

Dricks

Om du vill importera den fullständiga uppsättningen API-anrop för en viss version av Azure Digital Twins-API:erna (inklusive kontrollplan eller dataplan) kan du även importera Swagger-filer som samlingar. Länkar till Swagger-filerna för API:erna för kontrollplanet och dataplanet finns i Azure Digital Twins API:er och SDK:er.

Fortsätt sedan till nästa avsnitt för att lägga till en ägartoken i samlingen för auktorisering och ansluta den till din Azure Digital Twins-instans.

Konfigurera auktorisering

Redigera sedan samlingen som du har skapat för att konfigurera viss åtkomstinformation. Markera samlingen som du har skapat och välj ikonen Visa fler åtgärder för att visa åtgärdsalternativ. Välj Redigera.

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

Följ de här stegen för att lägga till en ägartoken i samlingen för auktorisering. Använd det tokenvärde som du samlade in i avsnittet Hämta ägartoken för att använda det för alla API-begäranden i din samling.

  1. Kontrollera att du är på fliken Auktorisering i redigeringsdialogrutan för samlingen.

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

  2. Ange Typ till OAuth 2.0 och klistra in din åtkomsttoken i rutan Åtkomsttoken. Du måste använda rätt token för den typ av API som du använder, eftersom det finns olika token för API:er för dataplanet jämfört med API:er för kontrollplanet. Välj Spara.

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

    Dricks

    Du kan välja att aktivera tokendelning om du vill lagra token med begäran i Postman-molnet och eventuellt dela din token med andra.

Övrig konfiguration

Du kan hjälpa samlingen att enkelt ansluta till dina Azure Digital Twins-resurser genom att ange några variabler som ingår i samlingen. När många begäranden i en samling kräver samma värde (som värdnamnet för din Azure Digital Twins-instans) kan du lagra värdet i en variabel som gäller för varje begäran i samlingen. Azure Digital Twins-samlingen levereras med förskapade variabler som du kan ange på samlingsnivå.

  1. Gå till fliken Variabler i redigeringsdialogrutan för samlingen.

  2. Använd följande tabell för att ange värdena för variablerna i samlingen:

    Olika API-uppsättning Description
    digitaltwins-hostname Dataplanet Värdnamnet för din Azure Digital Twins-instans. Du hittar det här värdet på översiktssidan för din instans i portalen.
    subscriptionId Kontrollplan ditt prenumerations-ID för Azure
    digitalTwinInstance Kontrollplan Namnet på din Azure Digital Twins-instans.

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

  3. Om samlingen har extra variabler fyller du även i och sparar dessa värden.

  4. Välj Spara.

När du är klar med stegen ovan är du klar med att konfigurera samlingen. Du kan stänga redigeringsfliken för samlingen om du vill.

Utforska begäranden

Utforska sedan begäranden i Azure Digital Twins API-samlingen. Du kan expandera samlingen för att visa de förskapade begärandena (sorterade efter åtgärdskategori).

Olika begäranden kräver olika information om din instans och dess data. Om du vill se all information som krävs för att skapa en viss begäran letar du upp begärandeinformationen i referensdokumentationen för Azure Digital Twins REST API.

Du kan redigera information om en begäran i Postman-samlingen med hjälp av följande steg:

  1. Välj den i listan för att hämta dess redigerbara information.

  2. De flesta begäranden i exempelsamlingen är förkonfigurerade för körning utan att göra några ytterligare ändringar.

  3. Följande skärmbild visar DigitalTwinModels Lägg till API. På fliken Brödtext kan du se JSON-nyttolasten som definierar den nya modellen som ska läggas till:

  4. Fyll i värden för variablerna som visas på fliken Params under Sökvägsvariabler.

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

  5. Om du vill köra begäran använder du knappen Skicka .

Du kan också lägga till egna begäranden i samlingen med hjälp av den process som beskrivs i avsnittet Lägg till en enskild begäran .

Skapa en egen samling

I stället för att importera den befintliga samlingen med Azure Digital Twins-API:er kan du också skapa en egen samling från grunden. Du kan sedan fylla i den med enskilda begäranden med hjälp av referensdokumentationen för Azure Digital Twins REST API.

Skapa en Postman-samling

  1. Om du vill skapa en samling väljer du knappen Nytt i postman-huvudfönstret.

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

    Välj en typ av samling.

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

  2. En flik öppnas. Fyll i information om den nya samlingen. Välj ikonen Redigera bredvid samlingens standardnamn (Ny samling) för att ersätta den med ditt eget namnval.

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

Fortsätt sedan till nästa avsnitt för att lägga till en ägartoken i samlingen för auktorisering.

Konfigurera auktorisering

Följ de här stegen för att lägga till en ägartoken i samlingen för auktorisering. Använd det tokenvärde som du samlade in i avsnittet Hämta ägartoken för att använda det för alla API-begäranden i din samling.

  1. Gå fortfarande till fliken Auktorisering i redigeringsdialogrutan för den nya samlingen.

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

  2. Ange Typ till OAuth 2.0, klistra in din åtkomsttoken i rutan Åtkomsttoken och välj Spara.

    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.

När du är klar med stegen ovan är du klar med att konfigurera samlingen. Du kan stänga redigeringsfliken för den nya samlingen om du vill.

Den nya samlingen kan ses från din huvudsakliga Postman-vy på fliken Samlingar.

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

Lägga till en enskild begäran

Nu när samlingen har konfigurerats kan du lägga till dina egna begäranden till Azure Digital Twin-API:erna.

  1. Om du vill skapa en begäran använder du knappen Nytt igen.

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

    Välj en typ av begäran.

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

  2. Den här åtgärden öppnar fönstret SPARA BEGÄRAN, där du kan ange ett namn för din begäran, ge den en valfri beskrivning och välja den samling som den ingår i. Fyll i informationen och spara begäran i samlingen som du skapade tidigare.

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

Nu kan du visa din begäran under samlingen och välja den för att hämta dess redigerbara information.

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

Ange information om begäran

Om du vill göra en Postman-begäran till ett av Azure Digital Twins-API:erna behöver du URL:en för API:et och information om vilken information som krävs. Du hittar den här informationen i referensdokumentationen för Azure Digital Twins REST API.

För att fortsätta med en exempelfråga använder den här artikeln Azure Digital Twins Query API för att fråga efter alla digitala tvillingar i en instans.

  1. Hämta begärande-URL:en och skriv från referensdokumentationen. För fråge-API:et är detta för närvarande POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. I Postman anger du typen för begäran och anger begärande-URL:en och fyller i platshållarna i URL:en efter behov. Använd värdnamnet för din instans från avsnittet Krav.

    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. Kontrollera att parametrarna som visas för begäran på fliken Params matchar de som beskrivs i referensdokumentationen. För den här begäran i Postman fylldes parametern api-version automatiskt när begärande-URL:en angavs i föregående steg. För fråge-API:et är detta den enda obligatoriska parametern, så det här steget är klart.

  4. På fliken Auktorisering anger du Typen till Ärv autentisering från överordnad. Detta anger att den här begäran använder den auktorisering som du konfigurerade tidigare för hela samlingen.

  5. Kontrollera att rubrikerna som visas för begäran på fliken Rubriker matchar de som beskrivs i referensdokumentationen. För den här begäran har flera huvuden fyllts i automatiskt. För fråge-API:et krävs inget av rubrikalternativen, så det här steget är klart.

  6. Kontrollera att brödtexten som visas för begäran på fliken Brödtext matchar de behov som beskrivs i referensdokumentationen. För fråge-API:et krävs en JSON-brödtext för att ange frågetexten. Här är en exempeltext för den här begäran som frågar efter alla digitala tvillingar i instansen:

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

    Mer information om hur du skapar Azure Digital Twins-frågor finns i Fråga tvillingdiagrammet.

  7. Kontrollera referensdokumentationen för andra fält som kan krävas för din typ av begäran. För Fråge-API:et har alla krav nu uppfyllts i Postman-begäran, så det här steget är klart.

  8. Använd knappen Skicka för att skicka din slutförda begäran. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

När du har skickat begäran visas svarsinformationen i Postman-fönstret under begäran. Du kan visa svarets statuskod och valfri brödtext.

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

Du kan också jämföra svaret med de förväntade svarsdata som anges i referensdokumentationen för att verifiera resultatet eller lära dig mer om eventuella fel som uppstår.

Nästa steg

Om du vill veta mer om Digital Twins-API:er läser du Azure Digital Twins-API:er och SDK:er eller visar referensdokumentationen för REST-API:erna.