Så här använder du Postman för att skicka begäranden till Azure Digital Twins API:er

Postman är ett REST-testverktyg som tillhandahåller viktiga FUNKTIONER för HTTP-begäranden i ett skrivbords- och plugin-baserat grafiskt användargränssnitt. Du kan använda den för att skapa HTTP-begäranden och skicka dem till Azure Digital Twins REST-API:er.

I den här artikeln beskrivs hur du konfigurerar Postman REST-klienten så att den interagerar med Azure Digital Twins API:er med hjälp av följande steg:

1. Använd Azure CLI för att hämta en bearer-token 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 bearer-token för autentisering. När du ställer in samlingen kan du välja något av följande alternativ:
   1. Importera en förbyggd samling av API Azure Digital Twins begäranden.
   2. Skapa din egen samling från grunden.
3. Lägg till begäranden i din konfigurerade samling och skicka dem till Azure Digital Twins API:er.

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

Förutsättningar

Om du vill fortsätta med att använda Postman för att komma åt Azure Digital Twins-API:er måste du konfigurera en Azure Digital Twins-instans och ladda ned Postman. Resten av det här avsnittet går igenom de här stegen.

Konfigurera en Azure Digital Twins instans

Om du vill Azure Digital Twins den här artikeln måste du först konfigurera en Azure Digital Twins instans. Du behöver också de behörigheter som krävs för att använda den. Om du redan har Azure Digital Twins en instans kan du använda den i stället.

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 ställt in din instans anteckning du följande värden. Du behöver dessa värden för att ansluta till instansen senare:

• Instansens värdnamn. Du hittar värdnamnet i Azure Portal.
• Den Azure-prenumeration som du använde för att skapa instansen. Antingen dess namn eller dess ID fungerar. Du hittar prenumerationen på sidan Översikt för din instans i Azure Portal.

Ladda ned Postman

Ladda sedan ned skrivbordsversionen av Postman-klienten.

Hämta bearer-token

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

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

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

1. Kontrollera först att du är inloggad i Azure med rätt 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 bearer-token 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 flikarna nedan för att välja mellan API:er för dataplanet och kontrollplanet.

   • Dataplanet
   • 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 är resurs-ID:t för Azure Digital Twins tjänstslutpunkt.

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

   Anteckning

   Om du behöver åtkomst till din Azure Digital Twins-instans med hjälp av ett huvudnamn för tjänsten eller ett användarkonto som tillhör en annan Azure Active Directory-klientorganisation från instansen måste du begära en token från Azure Digital Twins-instansens "hemklient". Mer information om den här processen finns i Skriva kod för appautentisering.

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

   

Nu ska du konfigurera Postman att använda denna token för att göra API-begäranden till Azure Digital Twins.

Om Postman-samlingar

Begäranden i Postman sparas i samlingar (grupper av begäranden). När du skapar en samling för att gruppera dina begäranden kan du använda gemensamma inställningar för många begäranden samtidigt. Detta kan förenkla auktoriseringen 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 Azure Digital Twins kan du komma igång genom att importera en förbyggd samling med alla Azure Digital Twins begäranden. Du kanske vill göra detta om du utforskar API:erna och snabbt vill konfigurera ett projekt med exempel på förfrågningar.

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 bara anropar de API:er som 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 en 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örbyggd samling begäranden för Azure Digital Twins-API:er.

Ladda ned samlingsfilen

Det första steget när du importerar API-uppsättningen är att ladda ned en samling. Välj fliken nedan för ditt val av dataplan eller kontrollplan för att se de förbyggda samlingsalternativen.

Så här laddar du ned den valda samlingen till datorn så att du kan importera den till Postman.

1. Använd länkarna ovan för att öppna samlingsfilen i GitHub i webbläsaren.
2. Välj raw-knappen för att öppna filens råtext.
3. Kopiera texten från fönstret och klistra in den i en ny fil på datorn.
4. Spara filen med filnamnstillägget .json (filnamnet kan vara vad du vill, så länge du kommer ihåg det för att hitta filen senare).

Importera samlingen

Importera sedan samlingen till Postman.

1. Välj knappen Importera i Postman-huvudfönstret.

2. I fönstret Importera som följer väljer du Upload Filer och navigerar till samlingsfilen på datorn som du skapade tidigare. Välj Öppna.

3. Välj knappen Importera för att bekräfta.

   

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

Fortsätt sedan till nästa avsnitt för att lägga till en bearer-token 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 hämta en meny. Välj Redigera.

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

1. Kontrollera att du är på fliken Auktorisering i dialogrutan Redigera för din samling.

   

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

   

Ytterligare konfiguration

Utforska begäranden

Utforska sedan begärandena i API Azure Digital Twins 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 Azure Digital Twins REST API referensdokumentationen.

Du kan redigera informationen 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 den redigerbara informationen.

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

   

3. Ange nödvändig information om rubriker eller brödtext på respektive flik.

När all nödvändig information har angetts kan du köra begäran med knappen Skicka.

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

Skapa en egen samling

I stället för att importera den befintliga samlingen av 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 Azure Digital Twins REST API referensdokumentationen.

Skapa en Postman-samling

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

   

   Välj en typ av Samling.

   

2. Då öppnas en flik där du kan fylla 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.

   

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

Konfigurera auktorisering

Följ dessa steg för att lägga till en bearer-token i samlingen för auktorisering. Här använder du det tokenvärde som du samlade in i avsnittet Hämta bearer-token för att kunna använda det för alla API-begäranden i din samling.

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

   

2. Ange Typ till OAuth 2.0, klistra in din åtkomsttoken i rutan Åtkomsttoken och 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 den nya samlingen om du vill.

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

Lägga till en enskild begäran

Nu när din samling har ställts in 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.

   

   Välj en typ av Begäran.

   

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.

   

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

Ange information om begäran

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

För att fortsätta med en exempelfråga använder den här artikeln fråge-API:et (och dess referensdokumentation )för att fråga efter alla digitaltvillingarna 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 POST https://digitaltwins-host-name/query?api-version=2020-10-31 .

2. I Postman anger du typen för begäran och anger url:en för begäran och fyller i platshållarna i URL:en efter behov. Det är här du ska använda din instanss värdnamn från avsnittet Krav.

   

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 api-version fylls parametern i automatiskt när url:en för begäran 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 Typ till Ärv auktorisering 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 huvudena 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 huvudalternativen, 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 tillhandahålla frågetexten. Här är ett exempel på en brödtext för den här begäran som frågar efter alla digital twins i instansen:

   

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

7. I referensdokumentationen finns 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.

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

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 kan du läsa Azure Digital Twins API:er och SDK:er,eller läsa referensdokumentationen för REST-API:erna.