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 :
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.comUtilisé par les entreprises du secteur privé. Ce cloud est le plus couramment utilisé. |
| GCC | https://globaldisco.crm9.dynamics.comCloud 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.usUtilisé 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.usUtilisé par les employés et sous-traitants du Département de la Défense des États-Unis. |
| Chine | https://globaldisco.crm.dynamics.cnUtilisés par les entreprises en Chine pour respecter les exigences de réglementation. |
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 :
| Champ | Valeur |
|---|---|
| TYPE D’AUTORISATION | Implicite |
| URL D’AUTORISATION | _.authurl |
| ID CLIENT | _.clientid |
| URL DE REDIRECTION | _.redirecturl |
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.
| 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 : InstanceLocked1 : PendingServiceInstanceMove2 : InstanceFailed3 : Provisioning 4 : InActiveOrganizationStatus5 : NewInstance6 : 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
$filterOData
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é).