Detectar organizaciones de usuario

  • Artículo

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.com
Utilizado por empresas del sector privado. Esta es la nube más utilizada.
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
Utilizado por los 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:

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: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 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).