Documentation de référence relative à Swagger sur Azure Digital Twins
Important
Une nouvelle version du service Azure Digital Twins a été publiée. En fonction des fonctionnalités étendues du nouveau service, le service Azure Digital Twins d’origine (décrit dans ce jeu de documentation) a été supprimé.
Pour afficher la documentation du nouveau service, consultez la documentation Azure Digital Twins active.
Chaque instance Azure Digital Twins provisionnée inclut sa propre documentation de référence sur Swagger générée automatiquement.
Swagger, ou OpenAPI, regroupe des informations complexes sur les API au sein d’une ressource de référence interactive et indépendante du langage. Swagger fournit des documents de référence essentiels sur les charges utiles JSON, les méthodes HTTP et les points de terminaison à utiliser pour effectuer des opérations sur une API.
Résumé de Swagger
Swagger propose un résumé interactif de votre API, qui comporte les éléments suivants :
- Informations sur l’API et le modèle objet.
- Points de terminaison d’API REST spécifiant les méthodes HTTP, les chemins contextuels, les paramètres, les en-têtes et les charges utiles de demande nécessaires.
- Test des fonctionnalités de l’API.
- Exemple d’informations de réponse utilisées pour valider et confirmer les réponses HTTP.
- Informations sur les codes d’erreur.
Swagger est un outil très pratique qui facilite le développement et le test des appels passés aux API de gestion Azure Digital Twins.
Conseil
Vous pouvez obtenir un premier aperçu de Swagger qui illustre le jeu de fonctionnalités de l’API. Pour ce faire, rendez-vous à l’adresse docs.westcentralus.azuresmartspaces.net/management/swagger.
Vous pouvez accéder à votre propre documentation Swagger générée pour l’API Gestion à l’adresse suivante :
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| Nom | Remplacer par |
|---|---|
| YOUR_INSTANCE_NAME | Nom de votre instance Azure Digital Twins |
| YOUR_LOCATION | Région de serveur dans laquelle votre instance est hébergée |
Documents de référence
La documentation de référence sur Swagger, générée automatiquement, fournit un rapide aperçu des concepts importants, des points de terminaison des API de gestion disponibles, ainsi qu'une description de chaque modèle objet pour faciliter le développement et les tests.
Un bref résumé décrit l’API.
Les modèles objet des API de gestion sont également répertoriés.
Vous pouvez sélectionner chacun des modèles objet listés pour obtenir un résumé plus détaillé des principaux attributs.
Les modèles objet Swagger générés sont pratiques pour lire la totalité des objets et API Azure Digital Twins disponibles. Les développeurs peuvent utiliser cette ressource quand ils créent des solutions sur Azure Digital Twins.
Résumé des points de terminaison
Swagger fournit également une vue d'ensemble détaillée de tous les points de terminaison qui composent les API de gestion.
Chaque point de terminaison listé inclut également les informations obligatoires de la demande, et notamment les suivantes :
- Paramètres obligatoires.
- Types de données de paramètre obligatoires.
- Méthode HTTP permettant d’accéder à la ressource.
Sélectionnez chaque ressource pour afficher son contenu supplémentaire afin d’obtenir une vue d’ensemble plus détaillée.
Utiliser Swagger pour tester des points de terminaison
L’une des fonctionnalités les plus puissantes de Swagger est la possibilité de tester directement un point de terminaison d’API sur l’interface utilisateur de la documentation.
Une fois que vous avez sélectionné un point de terminaison spécifique, le bouton Essayer s’affiche.
Développez cette section pour faire apparaître les champs d’entrée de chaque paramètre obligatoire et de chaque paramètre facultatif. Entrez les valeurs correctes, puis sélectionnez Exécuter.
Après avoir exécuté le test, vous pouvez valider les données de réponse.
Données de la réponse de Swagger
Chaque point de terminaison listé inclut également des données de corps de réponse pour la validation de votre développement et de vos tests. Ces exemples incluent les codes d’état et JSON des requêtes HTTP réussies.
Les exemples incluent également des codes d’erreur pour faciliter le débogage ou l’amélioration des tests ayant échoué.
Autorisation OAuth 2.0 avec Swagger
Notes
- L’utilisateur principal qui a créé la ressource Azure Digital Twins se voit attribuer le rôle d’administrateur de l’espace, et est en mesure de créer des attributions de rôles supplémentaires pour d’autres utilisateurs. Ces utilisateurs et leurs rôles peuvent être autorisés à appeler les API.
Suivez les étapes du guide de démarrage rapide pour créer et configurer une application Azure Active Directory. Vous pouvez aussi réutiliser une inscription d’application existante.
Ajoutez l’URI de redirection suivant à votre inscription d’application Azure Active Directory :
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlNom Remplacer par Exemple YOUR_SWAGGER_URL Votre URL de documentation API REST de gestion disponible sur le portail https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerActivez la case à cocher Octroi> implicitedes jetons d’accès pour autoriser l’utilisation du flux d’octroi implicite OAuth 2.0. Sélectionnez Configurer, puis Enregistrer.
Copiez l’ID de client de votre application Azure Active Directory.
À l’issue de l’inscription de l’application Azure Active Directory, procédez comme suit :
Cliquez sur le bouton Autoriser sur la page de votre instance Swagger.
Collez l’ID d’application dans le champ client_id.
Vous serez ensuite redirigé vers le modal de réussite suivant.
Pour en savoir plus sur les demandes de test interactif protégées par OAuth 2.0, lisez la documentation officielle.
Étapes suivantes
Pour plus d’informations sur les modèles objet Azure Digital Twins et le graphe d’intelligence spatiale, voir Comprendre les modèles objet Azure Digital Twins.
Pour savoir comment s’authentifier auprès d’une API Gestion, voir S’authentifier auprès des API.