Compartir a través de

Detectar organizaciones de usuario

Su 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 en 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 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 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 realiza la llamada debe adquirir un token OAuth 2.0 de Microsoft Entra ID y, a continuación, agregar ese token en el encabezado de Autorización de las llamadas de API. Más información: Utilizar 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 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
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 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.

Property Tipo Descripción
ApiUrl String 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 String 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 String 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 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 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. Use ApiUrl para conectarse a Dataverse.

El resto de las propiedades son principalmente para filtrar.

Filtering

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 la API web de Dataverse, el Servicio de detección global no proporciona la recuperación de una Instance específica utilizando Id o cualquiera de las claves alternativas definidas para ella. 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:

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, puede usar Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync para 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 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 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

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 aplicaciones .NET Framework, puede continuar para usar 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();

Como el método ServiceClient.DiscoverOnlineOrganizationsAsync, el método CrmServiceClient.DiscoverGlobalOrganizations tampoco devuelve datos como una Instancia. Devuelve una OrganizationDetailCollection, que contiene una colección de instancias de Clase OrganizationDetail que contiene la misma información que los tipos de Instance 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

  • Last updated on