Découvrir l’URL de votre organisation à l’aide de l’API web
Le service de découverte pour l’API Web Dynamics 365 for Customer Engagement permet à vos applications de déterminer au moment de l’exécution les organisations (instances) auxquelles appartient l’utilisateur connecté. Vous pouvez extraire des informations détaillées sur ces instances, telles que l’URL du service de l’instance, la version commerciale Customer Engagement, l’ID d’instance, etc. Vous pouvez utiliser $filter standard et les paramètres $select dans une demande de service API web pour personnaliser la liste de données d’instance renvoyée.
Note
La documentation qui s’applique aux utilisateurs en ligne est désormais disponible dans la documentation Power Apps à l’adresse : Découvrir l’URL pour votre organisation à l’aide de l’API Web.
Les applications clientes peuvent avoir besoin d’accéder à une instance Customer Engagement dont l’URL peut changer au fil du temps. Par exemple, si une instance Customer Engagement est déplacée d’un centre de données local à un autre. Le service de découverte permet aux instances clientes de persister l’ID d’instance ou le nom unique de l’instance, puis d’utiliser le service de découverte pour rechercher l’URL d’accès de l’instance actuelle.
Informations fournies par le service de découverte
Les informations sur l’organisation sont stockées dans l’entité Instance du service de découverte. Pour afficher le type d’informations contenues dans cette entité, envoyer une demande HTTP GET au service pour l’une de vos instances.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
Dans l’exemple ci-dessus, le service de découverte est utilisé pour obtenir les informations d’organisation de l’instance avec un nom unique : « monorg ». Des informations supplémentaires sur cette requête seront développées ultérieurement dans cette rubrique.
Étendue des informations renvoyées
Pour le service de découverte régional, l’ensemble d’entités Instances, renvoie l’ensemble des instances auxquelles l’utilisateur a accès à une région particulière, si aucun filtre n’est appliqué. Les données renvoyées ont une étendue comme décrit ci-dessous.
N’inclue pas les instances où le compte d’utilisateur est désactivé
N’inclue pas les instances où les utilisateurs ont été filtrés selon un groupe de sécurité d’instance
Ne comprend pas les instances auxquelles l’utilisateur a accès car il est administrateur délégué
Si l’utilisateur appelant n’a accès à aucune instance, la réponse renvoie simplement une liste vide
Comment accéder aux services de découverte
En général, l’adresse API web du service de découverte est au format suivant : <service base address>/api/discovery/. Les adresses pour chaque type de déploiement sont identifiées ci-dessous. Vous pouvez facilement rechercher les adresses de l’API Web et le numéro de version de votre déploiement dans l’application Web de Customer Engagement en allant dans Paramètres > Personnalisation > Ressources du développeur.
L’adresse de base du service de découverte pour un déploiement IFD et sur site est : http[s]://{servername}/ ou http[s]://dev.{servername}/. Ceci aboutit à l’adresse du service http[s]://{servername}/api/discovery/ ou http[s]://dev.{servername}/api/discovery/.
Utilisation du service de découverte
Un ensemble d’entités nommé Instances est utilisé pour obtenir des informations sur les instances. Vous pouvez utiliser $select et $filter avec l’ensemble d’entités Instances pour filtrer les données retournées. Vous pouvez également utiliser $metadata pour obtenir le document des métadonnées du service.
Authentification
Les instances IFD ou sur site de l’V4 Web de découverte adoptent le modèle d’authentification de leur déploiement, en prenant en charge les jetons IWA (authentification Windows intégrée) ou OAuth d’un fournisseur de jeton approuvé. L’authentification de session d’application web n’est pas prise en charge.
Contrôle de version API web
Le contrôle de version du service de découverte pour un centre de données ou sur site/IFD est pris en charge et est cohérent avec le numéro de version utilisé par le service de l’organisation. Par exemple :
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')
Prise en charge de CORS
L’API RESTful du service de découverte prend en charge CORS standard pour l’accès entre origine, tout comme l’API Web. Pour plus d’informations sur la prise en charge de CORS, consultez Utiliser OAuth avec le partage des ressources cross-origin pour connecter une application sur une seule page.
Exemples
Accédez aux détails d’une instance spécifique. Si vous excluez le GUID, toutes les instances auxquelles l’utilisateur authentifié a accès sont retournées.
GET https://dev.{servername}/api/discovery/v9.1/Instances(<guid>)Vous pouvez utiliser l’attribut UniqueName comme clé secondaire.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')Récupérez la liste d’instances disponibles, filtrée par le type de production.
GET https://dev.{servername}/api/discovery/v9.1/Instances?$select=DisplayName,Description&$filter=Type+eq+0Récupérez la valeur d’une propriété spécifique de l’ID d’une instance.
GET https://dev.{servername}/api/discovery/v9.1/Instances(UniqueName='myorg')/Id/$value