Referenzdokumentation: Azure Digital Twins-Swagger
Wichtig
Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.
Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.
Jede bereitgestellte Azure Digital Twins-Instanz enthält ihre eigene automatisch generierte Swagger-Referenzdokumentation.
Swagger (oder OpenAPI) vereinigt komplexe API-Informationen in einer interaktiven und sprachunabhängigen Referenzressource. Swagger stellt wichtiges Referenzmaterial dazu bereit, welche JSON-Nutzlasten, HTTP-Methoden und speziellen Endpunkte zum Ausführen von Vorgängen für eine API zu verwenden sind.
Swagger-Zusammenfassung
Swagger stellt eine interaktive Zusammenfassung Ihrer API bereit. Dazu gehören:
- API- und Objektmodellinformationen
- REST-API-Endpunkte, die erforderliche Anforderungsnutzlasten, Header, Parameter, Kontextpfade und HTTP-Methoden angeben
- Testen von API-Funktionalitäten
- Beispielantwortinformationen zum Überprüfen und Bestätigen von HTTP-Antworten
- Fehlercodeinformationen
Swagger ist ein praktisches Tool zur Unterstützung beim Entwickeln und Testen von Aufrufen, die an die Azure Digital Twins-Verwaltungs-APIs gesendet werden.
Tipp
Es wird eine Swagger-Vorschau bereitgestellt, um den API-Funktionsumfang zu veranschaulichen. Diese Vorschau finden Sie unter docs.westcentralus.azuresmartspaces.net/management/swagger.
Ihre eigene generierte Dokumentation von Verwaltungs-API-Swagger finden Sie unter:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| Name | Ersetzen durch |
|---|---|
| YOUR_INSTANCE_NAME | Den Namen Ihrer Azure Digital Twins-Instanz |
| YOUR_LOCATION | Die Serverregion, in der Ihre Instanz gehostet wird |
Referenzmaterial
Das automatisch generierte Swagger-Referenzmaterial enthält eine schnelle Übersicht über wichtige Konzepte, verfügbare Verwaltungs-API-Endpunkte und eine Beschreibung aller Objektmodelle, die Sie beim Entwickeln und Testen verwenden können.
Eine präzise Zusammenfassung beschreibt die API.
Verwaltungs-API-Objektmodelle werden ebenfalls aufgelistet.
Sie können jedes aufgelistete Objektmodell auswählen, um eine detailliertere Zusammenfassung der Schlüsselattribute zu erhalten.
Die generierten Swagger-Objektmodelle eignen sich ideal zum Lesen aller verfügbaren Objekte und APIs von Azure Digital Twins. Entwickler können diese Ressource verwenden, wenn sie Lösungen in Azure Digital Twins erstellen.
Zusammenfassung der Endpunkte
Swagger stellt auch eine umfassende Übersicht über alle Endpunkte bereit, aus denen die Verwaltungs-APIs bestehen.
Für jeden aufgelisteten Endpunkt werden auch die erforderlichen Anforderungsinformationen aufgeführt. Dazu gehören:
- Erforderliche Parameter
- Datentypen der erforderlichen Parameter
- HTTP-Methode zum Zugreifen auf die Ressource
Wählen Sie die einzelnen Ressourcen aus, um deren zusätzlichen Inhalt anzuzeigen und so eine detailliertere Übersicht zu erhalten.
Verwenden von Swagger zum Testen von Endpunkten
Eine der leistungsstarken Funktionalitäten von Swagger besteht darin, einen API-Endpunkt direkt über die Benutzeroberfläche der Dokumentation zu testen.
Nachdem Sie einen bestimmten Endpunkt ausgewählt haben, wird die Schaltfläche Jetzt ausprobieren angezeigt.
Erweitern Sie diesen Abschnitt, um Eingabefelder für jeden erforderlichen und optionalen Parameter anzuzeigen. Geben Sie die richtigen Werte ein, und wählen Sie Ausführen aus.
Wenn Sie den Test ausgeführt haben, können Sie die Antwortdaten überprüfen.
Swagger-Antwortdaten
Jeder aufgelistete Endpunkt enthält auch Antworttextdaten, um Ihre Entwicklung und Tests zu überprüfen. Diese Beispiele enthalten die Statuscodes und JSON für erfolgreiche HTTP-Anforderungen.
Die Beispiele enthalten auch Fehlercodes zur Unterstützung beim Debuggen oder Verändern von fehlgeschlagenen Tests.
Swagger-OAuth 2.0-Autorisierung
Hinweis
- Der Benutzerprinzipal, der die Azure Digital Twins-Ressource erstellt hat, verfügt über eine Raumadministrator-Rollenzuweisung und kann zusätzliche Rollenzuweisungen für andere Benutzer erstellen. Solche Benutzer und ihre Rollen können für das Aufrufen der APIs autorisiert werden.
Führen Sie die Schritte in diesem Schnellstart zum Erstellen und Konfigurieren einer Azure Active Directory-Anwendung aus. Alternativ können Sie eine vorhandene App-Registrierung wiederverwenden.
Fügen Sie Ihrer Azure Active Directory-App-Registrierung den folgenden Umleitungs-URI hinzu:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlName Ersetzen durch Beispiel YOUR_SWAGGER_URL Dokumentations-URL Ihrer Verwaltungs-REST-API aus dem Portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerAktivieren Sie das Kontrollkästchen">Implizite Zugriffstoken", um den impliziten OAuth 2.0-Grant-Fluss zu ermöglichen. Wählen Sie Konfigurieren und dann Speichern aus.
Kopieren Sie die Client-ID Ihrer Azure Active Directory-App.
Nach Abschluss der Azure Active Directory-Registrierung:
Wählen Sie auf Ihrer Swagger-Seite die Schaltfläche Autorisieren aus.
Fügen Sie die Anwendungs-ID in das Feld client_id ein.
Sie werden dann zum folgenden Erfolgsmodal umgeleitet.
Wenn Sie weitere Informationen zum interaktiven Testen von Anforderungen benötigen, die durch OAuth 2.0 geschützt sind, lesen Sie die offizielle Dokumentation.
Nächste Schritte
Weitere Informationen zu Azure Digital Twins-Objektmodellen und zum Raumintelligenzgraph finden Sie unter Grundlegendes zum Azure Digital Twins-Objektmodell.
Wie eine Authentifizierung über Ihre Verwaltungs-API erfolgt, erfahren Sie unter Authentifizieren über APIs.