Referensdokumentation för Azure Digital Twins Swagger
Viktigt
En ny version av Azure Digital Twins-tjänsten har släppts. Mot bakgrund av den nya tjänstens utökade funktioner har den ursprungliga Azure Digital Twins-tjänsten (som beskrivs i den här dokumentationsuppsättningen) dragits tillbaka.
Om du vill visa dokumentationen för den nya tjänsten går du till den aktiva Dokumentationen om Azure Digital Twins.
Varje etablerad Azure Digital Twins-instans innehåller sin egen automatiskt genererade Swagger-referensdokumentation.
Swagger, eller OpenAPI, förenar komplex API-information i en interaktiv och språkagnostisk referensresurs. Swagger tillhandahåller kritiskt referensmaterial om vilka JSON-nyttolaster, HTTP-metoder och specifika slutpunkter som ska användas för att utföra åtgärder mot ett API.
Swagger-sammanfattning
Swagger ger en interaktiv sammanfattning av ditt API, som innehåller:
- API- och objektmodellinformation.
- REST API-slutpunkter som anger nödvändiga nyttolaster för begäran, huvuden, parametrar, kontextsökvägar och HTTP-metoder.
- Testning av API-funktioner.
- Exempel på svarsinformation som används för att verifiera och bekräfta HTTP-svar.
- Felkodsinformation.
Swagger är ett praktiskt verktyg för att hjälpa till med utvecklings- och testningsanrop som görs till Azure Digital Twins Management-API:er.
Tips
En Swagger-förhandsversion tillhandahålls för att demonstrera API-funktionsuppsättningen. Den finns på docs.westcentralus.azuresmartspaces.net/management/swagger.
Du kan komma åt din egen genererade Swagger-dokumentation för hanterings-API:et på:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| Name | Ersätt med |
|---|---|
| YOUR_INSTANCE_NAME | Namnet på din Azure Digital Twins-instans |
| YOUR_LOCATION | Den serverregion som instansen finns i |
Referensmaterial
Det automatiskt genererade Swagger-referensmaterialet ger en snabb översikt över viktiga begrepp, tillgängliga hanterings-API-slutpunkter och en beskrivning av varje objektmodell för utveckling och testning.
En kortfattad sammanfattning beskriver API:et.
Hanterings-API-objektmodeller visas också.
Du kan välja varje objektmodell i listan för en mer detaljerad sammanfattning av nyckelattribut.
De genererade Swagger-objektmodellerna är praktiska att läsa alla tillgängliga Azure Digital Twins-objekt och API:er. Utvecklare kan använda den här resursen när de skapar lösningar på Azure Digital Twins.
Sammanfattning av slutpunkt
Swagger ger också en grundlig översikt över alla slutpunkter som utgör HANTERINGS-API:er.
Varje listad slutpunkt innehåller också nödvändig information om begäran, till exempel:
- Obligatoriska parametrar.
- Obligatoriska parameterdatatyper.
- HTTP-metod för att komma åt resursen.
Välj varje resurs om du vill visa ytterligare innehåll för att få en mer detaljerad översikt.
Använda Swagger för att testa slutpunkter
En av de kraftfulla funktionerna som Swagger tillhandahåller är möjligheten att testa en API-slutpunkt direkt via dokumentationsgränssnittet.
När du har valt en specifik slutpunkt visas knappen Prova .
Expandera avsnittet om du vill visa indatafält för varje obligatorisk och valfri parameter. Ange rätt värden och välj Kör.
När du har kört testet kan du verifiera svarsdata.
Swagger-svarsdata
Varje listad slutpunkt innehåller även svarstextdata för att verifiera din utveckling och dina tester. Dessa exempel omfattar statuskoder och JSON för lyckade HTTP-begäranden.
Exemplen innehåller också felkoder som hjälper dig att felsöka eller förbättra misslyckade tester.
Swagger OAuth 2.0-auktorisering
Anteckning
- Användarens huvudnamn som skapade Azure Digital Twins-resursen har en rolltilldelning för utrymmesadministratör och kan skapa ytterligare rolltilldelningar för andra användare. Dessa användare och deras roller kan ha behörighet att anropa API:erna.
Följ stegen i snabbstarten för att skapa och konfigurera ett Azure Active Directory-program. Du kan också återanvända en befintlig appregistrering.
Lägg till följande omdirigerings-URI i din Azure Active Directory-appregistrering:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlName Ersätt med Exempel YOUR_SWAGGER_URL Dokumentations-URL för ditt REST API för hantering som finns i portalen https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerMarkera kryssrutan Implicit bevilja>åtkomsttoken för att tillåta att det implicita OAuth 2.0-beviljandeflödet används. Välj Konfigurera och sedan Spara.
Kopiera klient-ID:t för din Azure Active Directory-app.
När du har slutfört Azure Active Directory-registreringen:
Välj knappen Auktorisera på swagger-sidan.
Klistra in program-ID:t i fältet client_id .
Sedan omdirigeras du till följande lyckade modal.
Mer information om interaktiv testning av begäranden som skyddas av OAuth 2.0 finns i den officiella dokumentationen.
Nästa steg
Mer information om Azure Digital Twins-objektmodeller och diagram över rumslig intelligens finns i Förstå Azure Digital Twins-objektmodeller.
Mer information om hur du autentiserar med ditt hanterings-API finns i Autentisera med API:er.