Så här skickar du begäranden till Azure Digital Twins-API:er med Postman
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:
- 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.
- 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:
- 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.
Kontrollera först att du är inloggad i Azure med lämpliga autentiseringsuppgifter genom att köra det här kommandot:
az login
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.
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.
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.
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.
Den nyligen importerade samlingen kan nu ses från din huvudsakliga Postman-vy på fliken Samlingar.
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.
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.
Kontrollera att du är på fliken Auktorisering i redigeringsdialogrutan för samlingen.
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.
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å.
Gå till fliken Variabler i redigeringsdialogrutan för samlingen.
Använd följande tabell för att ange värdena för variablerna i samlingen:
Olika API-uppsättning beskrivning 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. Om samlingen har extra variabler fyller du även i och sparar dessa värden.
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:
Välj den i listan för att hämta dess redigerbara information.
De flesta begäranden i exempelsamlingen är förkonfigurerade för körning utan att göra några ytterligare ändringar.
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:
Fyll i värden för variablerna som visas på fliken Params under Sökvägsvariabler.
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
Om du vill skapa en samling väljer du knappen Nytt i postman-huvudfönstret.
Välj en typ av samling.
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.
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.
Gå fortfarande till fliken Auktorisering i redigeringsdialogrutan för den nya samlingen.
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 samlingen har konfigurerats kan du lägga till dina egna begäranden till Azure Digital Twin-API:erna.
Om du vill skapa en begäran använder du knappen Nytt igen.
Välj en typ av begäran.
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 dess redigerbara information.
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.
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
.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.
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.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.
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.
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:
Mer information om hur du skapar Azure Digital Twins-frågor finns i Fråga tvillingdiagrammet.
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.
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.
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.
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för