Découvrir les organisations d’utilisateur

Votre application cliente peut se connecter à plusieurs environnements Dataverse. Utilisez le service de découverte global pour trouver les environnements auxquels l’utilisateur de votre application peut accéder.

Dans Power Apps, vous pouvez choisir parmi une liste d’environnements à votre disposition. Le service de découverte global est la source de ces données. Dans votre propre application, vous pouvez fournir un contrôle de sélection pour permettre aux utilisateurs de choisir l’environnement qu’ils souhaitent utiliser. Leur choix déterminera à quel environnement votre application doit se connecter.

Avec Dataverse pour les applications, l’allocation du serveur et de l’organisation peut évoluer dans le cadre de la gestion et de l’équilibrage de charge du centre de données. Par conséquent, le service de découverte global permet de découvrir le serveur qui sert une instance à un moment donné.

Pour plus d′informations :

• Choisir un environnement
• Vue d’ensemble des environnements

Service de découverte global

Le service de découverte global, parfois appelé GDS, est un ensemble de points de terminaison OData v4.0 disponibles pour 5 clouds différents.

Le tableau suivant offre l’emplacement GDS pour chaque cloud.

Pour plus d′informations :

• Dynamics 365 US Government
• Power Platform et les applications Dynamics 365 – traités par 21Vianet en Chine

Limitations

Le service de découverte global ne renvoie pas d’informations lorsque :

• Le compte utilisateur est désactivé.
• Les utilisateurs ont été filtrés selon un groupe de sécurité d’instance.
• 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.

Authentification

L’utilisateur appelant doit acquérir un jeton OAuth 2.0 de Microsoft Entra ID, puis ajouter ce jeton dans l’en-tête d’autorisation des appels d’API. Pour plus d’informations : Utilisation d’OAuth avec Microsoft Dataverse.

Prise en charge de CORS

Le service de découverte prend en charge CORS standard pour l’accès entre origine. 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.

Utiliser Insomnia pour se connecter au service de découverte global

Vous pouvez utiliser la même approche décrite pour l’API Web Dataverse ici : Utiliser Insomnia avec l’API Web Dataverse, mais au lieu des variables d’environnement décrites dans cette rubrique, utilisez la syntaxe suivante pour accéder au cloud commercial.

{
   "cloudUrl": "https://globaldisco.crm.dynamics.com",
   "globalDiscoUrl": "{{cloudUrl}}/api/discovery/v2.0/",
   "redirecturl": "https://localhost",
   "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{cloudUrl}}",
   "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
}

Ensuite, dans l’onglet Autorisation, choisissez OAuth 2 et définissez ou vérifiez les valeurs suivantes :

Utilisez GET _.globalDiscoUrl comme URL de demande et sélectionnez Envoyer.

Vous devriez maintenant pouvoir interroger le service de découverte global à l’aide d’Insomnia.

Documents de service

Pour accéder au service de découverte global pour chaque cloud, ajoutez /api/discovery/v2.0/ à l’URL. Exécutez une requête GET sur cette URL pour afficher le document de service, qui ne contient qu’un seul EntitySet : Instances.

Ajoutez $metadata à l’URL du cloud et envoyez une requête GET pour afficher le CSDL (Common Schema Definition Language). Ce document XML fournit des détails sur l’entité Instance et les clés secondaires définies pour celle-ci.

Instance EntitySet

La table suivante décrit les propriétés de l’entité Instance depuis le document de service CDSL $metadata.

Vous pouvez utiliser ces noms de propriété avec le paramètre de requête $select OData pour récupérer uniquement les données dont vous avez besoin. Dans la plupart des cas, vous n’aurez besoin que des propriétés FriendlyName et ApiUrl. Par exemple :

Demande :

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>

Réponse :

HTTP/1.1 200 OK
Content-Length: 625
Content-Type: application/json; odata.metadata=minimal
odata-version: 4.0

{
  "@odata.context":"https://10.0.1.76:20193/api/discovery/v2.0/$metadata#Instances(ApiUrl,FriendlyName)",
  "value":[
    {
      "ApiUrl":"https://yourorganization.api.crm.dynamics.com",
      "FriendlyName":"Your Organization"
    }
  ]
}

Utilisez la propriété FriendlyName pour l’interface utilisateur de votre application afin que l’utilisateur reconnaisse le nom de l’environnement. Utilisez l’ApiUrl pour se connecter à Dataverse.

Le reste des propriétés est principalement destiné au filtrage.

Filtrage

Il existe deux manières de filtrer les instances renvoyées :

• Utilisation des valeurs de clés
• Utilisation d’options de requête $filter OData

Utiliser une des valeurs de clés

Vous pouvez utiliser la valeur Id ou UniqueName pour filtrer la liste pour renvoyer uniquement l’instance spécifiée.

Ces deux requêtes seront un tableau avec un seul élément :

GET https://globaldisco.crm.dynamics.com/Instances(6bcbf6bf-1f2a-4ab9-9901-2605b314d72d)?$select=ApiUrl,FriendlyName,Id,UniqueName

GET https://globaldisco.crm.dynamics.com/Instances(UniqueName='unq6bcbf6bf1f2a4ab999012605b314d')?$select=ApiUrl,FriendlyName,Id,UniqueName

Vous pouvez également utiliser l’une des valeurs de clés secondaires suivantes : Region,State , Version pour filtrer selon des valeurs spécifiques. Par exemple, utilisez la requête ci-dessous pour renvoyer uniquement les instances où la région est NA représentant l’Amérique du Nord.

GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl

Utilisation d’options de requête $filter OData

Vous pouvez utiliser les options de requête $filter OData ainsi que toutes les propriétés qui s’appliquent, y compris les propriétés de clé secondaire.

Vous pouvez utiliser les opérateurs de comparaison, logiques et de regroupement suivants :

Vous pouvez utiliser les fonctions de requête de chaîne suivantes :

Utiliser le ServiceClient Dataverse

Pour les applications .NET, vous pouvez utiliser Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync Method pour appeler les services de découverte globaux.

 // Set up user credentials
var creds = new System.ServiceModel.Description.ClientCredentials();
creds.UserName.UserName = userName;
creds.UserName.Password = password;

//Call DiscoverOnlineOrganizationsAsync
DiscoverOrganizationsResult organizationsResult = await ServiceClient.DiscoverOnlineOrganizationsAsync(
        discoveryServiceUri: new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"),
        clientCredentials: creds,
        clientId: clientId,
        redirectUri: new Uri(redirectUrl),
        isOnPrem: false,
        authority: "https://login.microsoftonline.com/organizations/",
        promptBehavior: PromptBehavior.Auto);

return organizationsResult;

Tandis que la méthode DiscoverOnlineOrganizationsAsync utilise le même point de terminaison OData et permet qu’il soit transmis dans le paramètre discoveryServiceUri, elle ne renvoie pas de données sous la forme d’une Instance. Les données sont renvoyées sous forme de DiscoverOrganizationsResult Class qui comprend une OrganizationDetailCollection Property qui contient une collection d’instances OrganizationDetail Class. Cette classe contient les mêmes informations que les types Instance renvoyés par le service OData.

Utiliser CrmServiceClient

Pour les applications .NET Framework, vous pouvez continuer à utiliser le CrmServiceClient.DiscoverGlobalOrganizations Method pour appeler le service de découverte global.

  // Set up user credentials
  var creds = new System.ServiceModel.Description.ClientCredentials();
  creds.UserName.UserName = userName;
  creds.UserName.Password = password;

  // Call to get organizations from global discovery
  var organizations = CrmServiceClient.DiscoverGlobalOrganizations(
        discoveryServiceUri:new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"), 
        clientCredentials: creds, 
        user: null, 
        clientId: clientId,
        redirectUri: new Uri(redirectUrl), 
        tokenCachePath: "",
        isOnPrem: false,
        authority: string.Empty, 
        promptBehavior: PromptBehavior.Auto);

  return organizations.ToList();

Comme la méthode ServiceClient.DiscoverOnlineOrganizationsAsync, la méthode CrmServiceClient.DiscoverGlobalOrganizations ne renvoie pas non plus les données en tant qu’une Instance. Elle renvoie une OrganizationDetailCollection qui contient une collection d’instances OrganizationDetail Class contenant les mêmes informations que les types d’Instance renvoyés par le service OData.

Voir aussi

Exemple : Service de découverte global (C #)
Exemple : Accéder au service de découverte avec CrmServiceClient
Exemple : Blazor WebAssembly avec service de découverte global