Detectar organizaciones de usuario
Su aplicación cliente puede conectarse a múltiples entornos Dataverse. Utilice Global Discovery Service para saber a qué entornos puede acceder el usuario de su aplicación.
En Power Apps puede seleccionar entre una lista de entornos disponibles para usted. El origen de esos datos es el Global Discovery Service. Dentro de su propia aplicación, puede proporcionar un control de selección para permitir a los usuarios elegir qué entorno quieren usar. Su elección determinará a qué entorno debe conectarse su aplicación.
Con Dataverse, la asignación de servidor y de organización puede cambiar como parte del equilibrio de carga y administración del centro de datos. Por lo tanto, el Global Discovery Service una forma de detectar qué servidor proporciona una instancia en un momento determinado.
Más información:
Servicio de detección global
El Global Discovery Service, a veces llamado GDS, es un conjunto de puntos finales de OData v4.0 que están disponibles para 5 nubes diferentes.
Nota
Aunque tanto Dataverse Web API y Global Discovery Service son puntos finales de OData v4.0, son puntos finales separados con diferentes comportamientos.
La siguiente tabla ofrece la ubicación de GDS de cada nube.
| Nube | URL y descripción |
|---|---|
| Comercial | https://globaldisco.crm.dynamics.comUtilizado por empresas del sector privado. Esta es la nube más utilizada. |
| GCC | https://globaldisco.crm9.dynamics.comNube de la comunidad gubernamental. Utilizado por empleados y contratistas del sector público en los Estados Unidos. |
| USG | https://globaldisco.crm.microsoftdynamics.usUtilizado por empleados y contratistas del gobierno federal de los Estados Unidos. También se denomina GCC High. |
| DOD | https://globaldisco.crm.appsplatform.usUtilizado por los empleados y contratistas del Departamento de Defensa de los Estados Unidos. |
| China | https://globaldisco.crm.dynamics.cnUsada por compañías en China para cumplir los requisitos reglamentarios. |
Más información:
- Dynamics 365 US Government
- Power Platform y las aplicaciones de Dynamics 365 operadas por 21Vianet en China
Limitaciones
El Global Discovery Service no devuelve información cuando:
- La cuenta del usuario está deshabilitada.
- Los usuarios se han filtrado basándose en un grupo de seguridad de la instancia.
- El usuario tiene acceso como resultado de ser administrador delegado.
Si el usuario que llama no tiene acceso a ninguna instancia, la respuesta devuelve simplemente una lista vacía.
Autenticación
El usuario que llama debe adquirir un token de OAuth 2.0 de Microsoft Entra ID y luego agregar ese token en el encabezado de Autorización de las llamadas API. Más información: Utilizar autenticación OAuth con Microsoft Dataverse.
Soporte técnico de CORS
El servicio de detección admite la norma CORS para acceso de origen cruzado. Para obtener más información sobre el soporte técnico de CORS, consulte Usar OAuth con uso compartido de recursos entre orígenes para conectar una aplicación de una sola página.
Usar Insomnia para conectarse al servicio de detección global
Puede utilizar el mismo enfoque descrito para la API web de Dataverse aquí: Usar Insomnia con la API web de Dataverse, pero en lugar de las variables de entorno descritas en ese tema, utilice lo siguiente para tener acceso a la nube comercial.
{
"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"
}
Luego, en la pestaña Autorización, elija OAuth 2 y establezca o verifique los siguientes valores:
| Campo | valor |
|---|---|
| GRANT TYPE | Implícito |
| AUTHORIZATION url | _.authurl |
| CLIENTID | _.clientid |
| REDIRECT URL | _.redirecturl |
Utilice GET _.globalDiscoUrl como URL de solicitud y seleccione Enviar.
Ahora debería poder consultar el servicio de detección global utilizando Insomnia.
Documentos de servicios
Para acceder al Global Discovery Service para cada nube, agregue /api/discovery/v2.0/ a la URL. Realice una solicitud GET en esta URL para ver el documento de servicio, que contiene solo un único EntitySet: Instances.
Adjunte $metadata a la URL de la nube y envíe una solicitud GET para ver el documento de servicio CSDL (Common Schema Definition Language). Este documento XML proporciona detalles sobre la entidad Instance y las claves alternativas definidas para ella.
Instancia EntitySet
La siguiente tabla describe las propiedades de la entidad Instance del documento de servicio CDSL $metadata.
| Propiedad | Tipo | Descripción |
|---|---|---|
ApiUrl |
Cadena | Se debe utilizar la ubicación de las aplicaciones cliente de servicios web. |
DatacenterId |
Cadena | El identificador del centro de datos en el que está la instancia. |
DatacenterName |
Cadena | El nombre del centro de datos en el que está la instancia. Este valor suele ser nulo. |
EnvironmentId |
Cadena | El EnvironmentId de la instancia. |
FriendlyName |
Cadena | Un nombre para la instancia que se muestra en powerapps.com y otras aplicaciones cliente que permiten seleccionar instancias. |
Id |
Guid | El OrganizationId para el entorno. |
IsUserSysAdmin |
Booleana | Si el usuario que llama tiene el rol del sistema Administrador para el entorno. |
LastUpdated |
DateTimeOffset | Cuando el entorno se actualizó por última vez. |
OrganizationType |
Int32 | El tipo de la organización. Los valores corresponden a OrganizationType EnumType |
Purpose |
Cadena | Información con el propósito proporcionado cuando se creó el entorno. |
Region |
Cadena | Un código de 2-3 letras para la región donde se encuentra el entorno. |
SchemaType |
Cadena | Para uso interno. |
State |
Int32 | Si la organización está 0:habilitada o 1:deshabilitada. |
StatusMessage |
Int32 | Uno de los siguientes valores: 0:InstanceLocked1:PendingServiceInstanceMove2:InstanceFailed3:Provisioning 4:InActiveOrganizationStatus5:NewInstance6:InstancePickerReady |
TenantId |
Guid | El identificador del inquilino asociado a la instancia |
TrialExpirationDate |
DateTimeOffset | La fecha en que vence el período de prueba de la instancia. |
UniqueName |
String | El nombre único para la instancia. |
UrlName |
Cadena | El nombre usado para la URL. |
Version |
Cadena | La versión actual del entorno. |
Url |
Cadena | La url de aplicación para el entorno. |
Puede usar estos nombres de propiedad con el parámetro de consulta OData $select para recuperar solo los datos que necesita. En la mayoría de los casos, todo lo que necesitará son las propiedades FriendlyName y ApiUrl. Por ejemplo:
Solicitud:
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>
Respuesta:
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"
}
]
}
Use la propiedad FriendlyName para la interfaz de usuario de su aplicación para que el usuario reconozca el nombre del entorno. Uso de ApiUrl para conectarse a Dataverse.
El resto de las propiedades son principalmente para filtrar.
Filtrado
Hay dos formas de filtrar las instancias devueltas:
- Usar valores clave
- Use las opciones de consulta de OData
$filter
Use uno de los valores clave
Puede usar el valor Id o UniqueName para filtrar la lista para devolver solo una instancia especificada.
Nota
A diferencia de Dataverse Web API, Global Discovery Service no proporciona la recuperación de una Instance utilizando el Id o cualquiera de las claves alternativas definidas para él. GDS siempre devuelve una matriz de valores.
Ambas consultas serán una matriz con un solo elemento:
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
También puede usar cualquiera de los siguientes valores clave alternativa: Region, State, Version para filtrar en valores específicos. Por ejemplo, use la consulta a continuación para devolver solo aquellas instancias donde la región es NA representando a Norteamérica.
GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl
Use las opciones de consulta de OData $filter
Puede usar las opciones de consulta de OData $filter también con cualquiera de las propiedades que se aplican, incluidas las propiedades clave alternativa.
Puede utilizar los siguientes operadores de comparación, lógicos y de agrupación:
| Operator | Descripción | Ejemplo |
|---|---|---|
| Operadores de comparación | ||
eq |
Es igual a | $filter=IsUserSysAdmin eq true |
ne |
No es igual a | $filter=IsUserSysAdmin ne true |
gt |
Mayor que | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z |
ge |
Mayor o igual que | $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z |
lt |
Menor que | $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z |
le |
Menor o igual que | $filter=TrialExpirationDate le 2022-07-14T00:00:00Z |
| Operadores lógicos | ||
and |
Lógico y | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true |
or |
Disyunción lógica | $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true |
not |
Negación lógica | $filter=not contains(Purpose,'test') |
| Agrupación de operadores | ||
( ) |
Agrupaciones por prioridad | (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z |
Puede usar las siguientes funciones de consulta de cadena:
| Función | Ejemplo |
|---|---|
contains |
$filter=contains(Purpose,'test') |
endswith |
$filter=endswith(FriendlyName,'Inc.') |
startswith |
$filter=startswith(FriendlyName,'A') |
Nota
A diferencia de Dataverse API web, las cadenas de búsqueda de Global Discovery Service distinguen entre mayúsculas y minúsculas.
Usar Dataverse ServiceClient
Para aplicaciones .NET puede usar Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync Method para llamar a los Global Discovery Services.
// 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;
Aunque que DiscoverOnlineOrganizationsAsync utiliza el mismo punto de conexión OData y permite que se pase en el parámetro discoveryServiceUri, no devuelve datos en forma de una Instancia. Los datos se devuelven como un DiscoverOrganizationsResult Class que incluye un OrganizationDetailCollection Property que contiene una colección de instancias OrganizationDetail Class. Esta clase contiene la misma información que los tipos de Instance devueltos por el servicio OData.
Nota
Mientras que el parámetro DiscoverOnlineOrganizationsAsync.discoveryServiceUri acepta una URL para Global Discovery Service, cualquier opción de consulta $select o $filter utilizada se ignorarán. El parámetro DiscoverOnlineOrganizationsAsync.discoveryServiceUri es opcional y, si no se proporciona, se establecerá de forma predeterminada en la nube comercial.
Usar CrmServiceClient
Para las aplicaciones de .NET Framework, puede continuar usando CrmServiceClient.DiscoverGlobalOrganizations Method para llamar al servicio de detección 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();
Como el método ServiceClient.DiscoverOnlineOrganizationsAsync, el método CrmServiceClient.DiscoverGlobalOrganizations tampoco devuelve datos como una Instancia. Devuelve un OrganizationDetailCollection que contiene una colección de instancias OrganizationDetail Class que contienen la misma información que los tipos Instance devueltos por el servicio OData.
Consulte también
Ejemplo: Muestra de Global Discovery Service (C#)
Ejemplo: Acceder al servicio de detección usando CrmServiceClient
Ejemplo: Blazor WebAssembly con Global Discovery
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).