Detectar organizaciones de usuario

La aplicación cliente puede conectarse a varios entornos de 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. 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 determina a qué entorno debe conectarse la aplicación.

Con Dataverse, la asignación de servidor y organización puede cambiar como parte de la administración y el equilibrio de carga 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:

• Elegir un entorno
• Información general de entornos

Servicio de detección global

El servicio detección global, a veces denominado GDS, es un conjunto de puntos de conexión de OData v4.0 que están disponibles para cinco nubes diferentes.

Nota

Aunque tanto la API web de Dataverse como el servicio de detección global son puntos de conexión de OData v4.0, son puntos de conexión independientes con comportamientos diferentes.

La siguiente tabla ofrece la ubicación de GDS de cada nube.

Nube	URL y descripción
Comercial	https://globaldisco.crm.dynamics.com Utilizado por empresas del sector privado. Esta nube es la nube más usada.
GCC	https://globaldisco.crm9.dynamics.com Nube de la comunidad gubernamental. Utilizado por empleados y contratistas del sector público en los Estados Unidos.
USG	https://globaldisco.crm.microsoftdynamics.us Utilizado por empleados y contratistas del gobierno federal de los Estados Unidos. También se denomina GCC High.
DOD	https://globaldisco.crm.appsplatform.us Usado por empleados y contratistas del Departamento de Defensa de los Estados Unidos.
China	https://globaldisco.crm.dynamics.cn Usada por compañías en China para cumplir los requisitos reglamentarios.

Más información:

• Dynamics 365 Gobierno de EE. UU.
• Aplicaciones Power Platform y Dynamics 365: operadas por 21Vianet en China

Limitaciones

El servicio de detección global no devuelve información cuando:

• La cuenta del usuario está deshabilitada.
• Un grupo de seguridad de instancia filtra al usuario.
• El usuario obtiene acceso al ser un administrador delegado.

Si el usuario que realiza la llamada no puede acceder a ninguna instancia, la respuesta devuelve una lista vacía.

Autenticación

El usuario que realiza la llamada debe obtener un token de OAuth 2.0 de Microsoft Entra ID y agregar ese token en el encabezado Autorización de las llamadas API. Para obtener más información, consulte Uso de la autenticación de 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 la compatibilidad con CORS, consulte Usar OAuth con CORS para conectar una aplicación de una sola página.

Usar Insomnia para conectarse al servicio de detección global

Use el mismo enfoque descrito para la API web de Dataverse en Usar Insomnia con Dataverse Web API. En lugar de las variables de entorno descritas en ese artículo, use las siguientes variables para acceder 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"
}

En la pestaña Autorización , elija OAuth 2 y establezca o compruebe los valores siguientes:

Campo	valor
TIPO DE CONCESIÓN	Implícito
URL DE AUTORIZACIÓN	_.authurl
CLIENTID	_.clientid
URL DE REDIRECCIÓN	_.redirecturl

Utilice GET _.globalDiscoUrl como URL de solicitud y seleccione Enviar.

Ahora puede consultar el Global Discovery Service mediante Insomnia.

Documentos de servicios

Para acceder al servicio de detección global para cada nube, anexe /api/discovery/v2.0/ a la dirección URL. Realice una solicitud GET a esta URL para ver el documento de servicio, que contiene un único conjunto de entidades: 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.

Property	Tipo	Descripción
ApiUrl	String	Se debe utilizar la ubicación de las aplicaciones cliente de servicios web.
DatacenterId	String	El identificador del centro de datos en el que está la instancia.
DatacenterName	String	El nombre del centro de datos en el que está la instancia. Este valor suele ser nulo.
EnvironmentId	String	El EnvironmentId de la instancia.
FriendlyName	String	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	String	Información con el propósito proporcionado cuando se creó el entorno.
Region	String	Un código de 2-3 letras para la región donde se encuentra el entorno.
SchemaType	String	Solo para uso interno.
State	Int32	Si la organización está 0:habilitada o 1:deshabilitada.
StatusMessage	Int32	Uno de los siguientes valores: 0:InstanceLocked 1:PendingServiceInstanceMove 2:InstanceFailed 3:Provisioning 4:InActiveOrganizationStatus 5:NewInstance 6: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	String	El nombre usado para la URL.
Version	String	La versión actual del entorno.
Url	String	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. Use ApiUrl para conectarse a Dataverse.

El resto de las propiedades son principalmente para filtrar.

Filtering

Puede filtrar las instancias devueltas de dos maneras:

• Usar valores clave
• Use las opciones de consulta de OData $filter

Usar valores clave

Use el Id valor o UniqueName para filtrar la lista y devolver solo la instancia especificada.

Nota

A diferencia de la API web de Dataverse, el Servicio de detección global no admite recuperar un Instance específico mediante el uso de Id ni de ninguna de las claves alternativas definidas para ese elemento. GDS siempre devuelve una matriz de valores.

Ambas consultas siguientes devuelven 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 de clave alternativos para filtrar por valores específicos: Region, , StateVersion. Por ejemplo, use la consulta siguiente para devolver solo las instancias en las que la región representa NA 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 con cualquiera de las propiedades que se aplican, incluidas las propiedades de clave alternativas.

Puede usar 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:

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

Nota

A diferencia de la API web de Dataverse, las cadenas de búsqueda del Servicio de detección global distinguen entre mayúsculas y minúsculas.

Usar ServiceClient de Dataverse

Para aplicaciones .NET, utilice Dataverse.Client.ServiceClient.el método DiscoverOnlineOrganizationsAsync para llamar a los servicios globales de detección.

 // 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 el método DiscoverOnlineOrganizationsAsync usa el mismo punto de conexión de OData y permite pasarlo en el parámetro discoveryServiceUri, no devuelve datos con la forma de una instancia. Devuelve datos como una clase DiscoverOrganizationsResult que incluye una propiedad OrganizationDetailCollection que contiene una colección de instancias de clase OrganizationDetail . Esta clase contiene la misma información que los tipos de Instance devueltos por el servicio OData.

Nota

Aunque el parámetro DiscoverOnlineOrganizationsAsync.discoveryServiceUri acepta una dirección URL del Servicio global de detección, el método ignora cualquier opción de consulta $select o $filter. El DiscoverOnlineOrganizationsAsync.discoveryServiceUri parámetro es opcional. Si no lo proporciona, el método tiene como valor predeterminado la nube comercial.

Usar CrmServiceClient

Para las aplicaciones de .NET Framework, siga usando el método CrmServiceClient.DiscoverGlobalOrganizations 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();

Al igual que el ServiceClient.DiscoverOnlineOrganizationsAsync método , el CrmServiceClient.DiscoverGlobalOrganizations método tampoco devuelve datos como instancia. Devuelve un objeto OrganizationDetailCollection que contiene una colección de instancias de clase OrganizationDetail . Esta colección contiene la misma información que los Instance tipos devueltos por el servicio OData.

Consulte también

Ejemplo: Muestra del Servicio de detección global (C#)
Ejemplo: Acceder al servicio de detección usando CrmServiceClient
Ejemplo: Blazor WebAssembly con Global Discovery