Découvrir les organisations d’utilisateur

  • Article

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 :

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.

Notes

Alors que l’API Web Dataverse et le service de découverte global sont des points de terminaison OData v4.0, ce sont des points de terminaison distincts avec des comportements différents.

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

Cloud URL et description
Commercial https://globaldisco.crm.dynamics.com
Utilisé par les entreprises du secteur privé. Ce cloud est le plus couramment utilisé.
GCC https://globaldisco.crm9.dynamics.com
Cloud de la communauté du secteur public. Utilisé par les employés et sous-traitants du secteur public aux États-Unis.
USG https://globaldisco.crm.microsoftdynamics.us
Utilisé par les employés et les sous-traitants du gouvernement fédéral des États-Unis. Également connues sous le nom de GCC High.
DOD https://globaldisco.crm.appsplatform.us
Utilisé par les employés et sous-traitants du Département de la Défense des États-Unis.
Chine https://globaldisco.crm.dynamics.cn
Utilisés par les entreprises en Chine pour respecter les exigences de réglementation.

Pour plus d′informations :

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 auprès 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 , consultez Utiliser OAuth avec le partage des ressources cross-origin pour connecter une application sur une seule page.

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

Vous pouvez utiliser la même approche décrite pour l’API Web Dataverse ici : Configurer un environnement Postman, mais au lieu des variables d’environnement décrites dans ce sujet, procédez comme suit pour accéder au cloud commercial.

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

Puis, dans l’onglet Autorisation Postman, définissez ou vérifiez les valeurs suivantes :

Champ Valeur
Type OAuth 2.0
Ajouter des données d’autorisation à En-têtes de demandes
Préfixe d’en-tête Porteur
Type d’autorisation Implicite
URL de rappel http://localhost
URL d’authentification {{authurl}}
ID client {{clientid}}
Authentification client Envoyer comme en-tête d’authentification de base

Utilisez {{globalDiscoUrl}} comme l’URL de la requête et dans l’onglet Autorisation, cliquez sur Obtenir un nouveau jeton d’accès.

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

En savoir plus : YouTube : Mise en route à l’aide de Postman avec l’API Web Microsoft Dataverse

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.

Property Type Description
ApiUrl Chaîne L’emplacement des applications clientes de services Web doit être utilisé.
DatacenterId Chaîne ID du centre de données où se situe l’instance.
DatacenterName Chaîne Nom du centre de données où se situe l’instance. Cette valeur est généralement nulle.
EnvironmentId Chaîne ID d’environnement de l’instance.
FriendlyName Chaîne Nom pour l’instance qui s’affiche dans powerapps.com et d’autres applications clientes qui permettent de sélectionner des instances.
Id Guid ID de l’organisation pour l’environnement.
IsUserSysAdmin Booléen Indique si l’utilisateur appelant a le rôle d’administrateur système pour l’environnement.
LastUpdated DateTimeOffset Lorsque l’environnement a été mis à jour pour la dernière fois.
OrganizationType Int32 Type d’organisation. Les valeurs à correspondent à OrganizationType EnumType
Purpose Chaîne Informations fournies à juste titre lors de la création de l’environnement.
Region Chaîne Code à 2 ou 3 lettres pour la région où se trouve l’environnement.
SchemaType Chaîne Réservé exclusivement à un usage interne.
State Int32 Indique si l’organisation est 0 : activée ou 1 : désactivée.
StatusMessage Int32 Une des valeurs suivantes :
0 : InstanceLocked
1 : PendingServiceInstanceMove
2 : InstanceFailed
3 : Provisioning
4 : InActiveOrganizationStatus
5 : NewInstance
6 : InstancePickerReady
TenantId Guid ID du client associé à l’instance
TrialExpirationDate DateTimeOffset La date à laquelle la période d’évaluation de l’instance expire.
UniqueName Chaîne Le nom unique de l’instance.
UrlName Chaîne Nom utilisé pour l’URL.
Version Chaîne Version actuelle de l’environnement.
Url Chaîne URL de l’application pour l’environnement.

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.

Notes

Contrairement à l’API Web Dataverse, le service de découverte global ne permet pas de récupérer une Instance spécifique en utilisant l’Id ou l’une des clés secondaires définies pour lui. GDS retourne toujours un tableau de valeurs.

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 :

Opérateur Description Exemple
Opérateurs de comparaison
eq Égal à $filter=IsUserSysAdmin eq true
ne Différent de $filter=IsUserSysAdmin ne true
gt Supérieur(e) à $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z
ge Supérieur ou égal à $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z
lt Inférieur(e) à $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z
le Inférieur ou égal à $filter=TrialExpirationDate le 2022-07-14T00:00:00Z
Opérateurs logiques
and ET logique $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true
or OU logique $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true
not Négation logique $filter=not contains(Purpose,'test')
Opérateurs de groupement
( ) Groupement de priorité (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z

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

Function Exemple
contains $filter=contains(Purpose,'test')
endswith $filter=endswith(FriendlyName,'Inc.')
startswith $filter=startswith(FriendlyName,'A')

Notes

Contrairement à l’API Web Dataverse, les chaînes de recherche de service de requête global sont sensibles à la casse.

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.

Notes

Tandis que le paramètre DiscoverOnlineOrganizationsAsync.discoveryServiceUri accepte une URL vers le service de découverte global, toute option de requête $select ou $filter utilisée sera ignorée. Le paramètre DiscoverOnlineOrganizationsAsync.discoveryServiceUri est facultatif et s’il n’est pas fourni, il sera défini par défaut sur le cloud commercial.

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

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).