Descobrir organizações de usuários

Seu aplicativo cliente pode se conectar a vários ambientes do Dataverse. Use o Serviço de Descoberta Global para localizar quais ambientes o usuário do aplicativo pode acessar.

Em Power Apps, você pode selecionar em uma lista de ambientes disponíveis para você. O Serviço de Descoberta Global é a fonte desses dados. Em seu próprio aplicativo, você pode fornecer um controle seleto para permitir que os usuários escolham qual ambiente eles desejam usar. A escolha deles determina a qual ambiente seu aplicativo deve se conectar.

Com o Dataverse, a alocação de servidor e organização pode ser alterada como parte do gerenciamento de datacenter e do balanceamento de carga. Portanto, o Serviço de Descoberta Global fornece uma maneira de descobrir qual servidor está atendendo uma instância em um determinado momento.

Mais informações:

Serviço de Descoberta Global

O serviço de Descoberta Global, às vezes chamado de GDS, é um conjunto de pontos de conexão OData v4.0 disponíveis em cinco nuvens diferentes.

Note

Embora a API Web do Dataverse e o serviço de Descoberta Global sejam pontos de extremidade OData v4.0, eles são pontos de extremidade separados com comportamentos diferentes.

A tabela a seguir fornece o local do GDS para cada nuvem.

Nuvem URL e Descrição
Comercial https://globaldisco.crm.dynamics.com
Usado por empresas do setor privado. Essa nuvem é a nuvem mais usada.
GCC https://globaldisco.crm9.dynamics.com
Nuvem comunitária governamental. Usado por funcionários do setor público e empreiteiros no Estados Unidos.
USG https://globaldisco.crm.microsoftdynamics.us
Usado por funcionários e contratados do governo federal dos Estados Unidos. Também conhecido como GCC High.
Departamento de Defesa https://globaldisco.crm.appsplatform.us
Usado por funcionários e empreiteiros do Departamento de Defesa do Estados Unidos.
China https://globaldisco.crm.dynamics.cn
Usado por empresas na China para cumprir os requisitos regulatórios.

Mais informações:

Limitações

O Serviço de Descoberta Global não retorna informações quando:

  • A conta do usuário está desabilitada.
  • Um grupo de segurança de instância filtra o usuário.
  • O usuário obtém acesso sendo um administrador delegado.

Se o usuário de chamada não puder acessar nenhuma instância, a resposta retornará uma lista vazia.

Authentication

O usuário de chamada deve obter um token OAuth 2.0 de Microsoft Entra ID e adicionar esse token no cabeçalho autorização das chamadas à API. Para obter mais informações, consulte Usar a autenticação OAuth com Microsoft Dataverse.

Suporte a CORS

O Serviço de Descoberta dá suporte ao padrão CORS para acesso entre origens. Para obter mais informações sobre o suporte ao CORS, consulte Usar o OAuth com o compartilhamento de recursos entre origens para conectar um aplicativo Single-Page.

Use o Insomnia para se conectar ao Serviço de Descoberta Global

Use a abordagem descrita para a API Web do Dataverse em Usar o Insomnia com a API Web do Dataverse. Em vez das variáveis de ambiente descritas nesse artigo, use as variáveis a seguir para acessar a nuvem 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"
}

Na guia Autorização , escolha OAuth 2 e defina ou verifique os seguintes valores:

Field Value
TIPO DE GRANT Implícito
URL DE AUTORIZAÇÃO _.authurl
CLIENTID _.clientid
URL DE REDIRECIONAMENTO _.redirecturl

Use GET _.globalDiscoUrl como a URL de Solicitação e selecione Enviar.

Agora você pode fazer consultas ao Global Discovery Service usando o Insomnia.

Serviço de serviço

Para acessar o Serviço de Descoberta Global para cada nuvem, acrescente /api/discovery/v2.0/ à URL. Execute uma GET solicitação nesta URL para exibir o documento de serviço, que contém apenas um único EntitySet: Instances.

Acrescente $metadata à URL da nuvem e envie uma GET solicitação para exibir o documento do serviço CSDL (Common Schema Definition Language). Este documento XML fornece detalhes sobre a Instance entidade e as chaves alternativas definidas para ela.

EntitySet da instância

A tabela a seguir descreve as propriedades da entidade Instance do documento de serviço CDSL $metadata.

Property Tipo Descrição
ApiUrl String A localização que os aplicativos cliente de serviços web devem usar.
DatacenterId String A ID do data center em que a instância está localizada.
DatacenterName String O nome do data center em que a instância está localizada. Esse valor normalmente é nulo.
EnvironmentId String A EnvironmentId para a instância.
FriendlyName String Um nome para a instância exibida em powerapps.com e outros aplicativos cliente que permitem a seleção de instâncias.
Id Guid A OrganizationId para o ambiente.
IsUserSysAdmin booleano Se o usuário de chamada tem a função de administrador do sistema para o ambiente.
LastUpdated DateTimeOffset Quando o ambiente foi atualizado pela última vez.
OrganizationType Int32 O tipo da organização. Os valores correspondem ao OrganizationType EnumType
Purpose String Informações para a finalidade fornecidas quando o ambiente foi criado.
Region String Um código de 2 a 3 letras para a região em que o ambiente está localizado.
SchemaType String Somente para uso interno.
State Int32 Se a organização está 0:habilitada ou 1:desabilitada.
StatusMessage Int32 Um dos seguintes valores:
0:InstanceLocked
1:PendingServiceInstanceMove
2:InstanceFailed
3:Provisioning
4:InActiveOrganizationStatus
5:NewInstance
6:InstancePickerReady
TenantId Guid A ID do locatário associado à instância
TrialExpirationDate DateTimeOffset Data em que o período de teste da instância expira.
UniqueName String O nome único da instância.
UrlName String O nome usado para a URL.
Version String A versão atual do ambiente.
Url String A URL do aplicativo do ambiente.

Você pode usar esses nomes de propriedade com o parâmetro de consulta OData $select para recuperar apenas os dados necessários. Na maioria dos casos, tudo o que você precisará são as propriedades ApiUrl e FriendlyName. Por exemplo:

Solicitação:

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>

Resposta:

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 a FriendlyName propriedade da interface do usuário do aplicativo para que o usuário reconheça o nome do ambiente. Use o ApiUrl para se conectar ao Dataverse.

O restante das propriedades são principalmente para filtragem.

Filtragem

Você pode filtrar as instâncias retornadas de duas maneiras:

  • Usar valores-chave
  • Usar opções de consulta OData $filter

Usar valores-chave

Use o valor UniqueName ou Id para filtrar a lista e retornar somente a instância especificada.

Note

Ao contrário da API Web do Dataverse, o Serviço de Descoberta Global não oferece suporte para recuperar um(a) Instance específico(a) usando Id ou qualquer uma das chaves alternativas definidas para ele. O GDS sempre retorna uma matriz de valores.

Ambas as consultas a seguir retornam uma matriz com um único item:

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

Você também pode usar qualquer um dos seguintes valores de chave alternativa para filtrar valores específicos: Region, , StateVersion. Por exemplo, use a consulta a seguir para retornar somente as instâncias em que a Região representa NA a América do Norte.

GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl

Usar opções de consulta do OData $filter

Você pode usar opções de consulta OData $filter com qualquer uma das propriedades que se aplicam, incluindo as propriedades de chave alternativa.

Você pode usar os seguintes operadores de comparação, lógica e agrupamento:

Operador Descrição Exemplo
Operadores de comparação
eq Igual $filter=IsUserSysAdmin eq true
ne Não Igual $filter=IsUserSysAdmin ne true
gt Maior que $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z
ge Maior ou igual $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z
lt Menor que $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z
le Inferior ou igual $filter=TrialExpirationDate le 2022-07-14T00:00:00Z
Operadores lógicos
and E lógico $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true
or OU lógico $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true
not Negação lógica $filter=not contains(Purpose,'test')
Operadores de agrupamento
( ) Agrupamento de precedência (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z

Você pode usar as seguintes funções de consulta de cadeia de caracteres:

Função Exemplo
contains $filter=contains(Purpose,'test')
endswith $filter=endswith(FriendlyName,'Inc.')
startswith $filter=startswith(FriendlyName,'A')

Note

Ao contrário da API Web do Dataverse, as cadeias de pesquisa do Serviço de Descoberta Global fazem distinção entre maiúsculas e minúsculas.

Usando o Dataverse ServiceClient

Para aplicativos .NET, use Dataverse.Client.ServiceClient.Método DiscoverOnlineOrganizationsAsync para chamar os Serviços de Descoberta 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;

Embora o método DiscoverOnlineOrganizationsAsync use o mesmo endpoint OData e permita que seja passado como parâmetro em discoveryServiceUri, ele não retorna dados na forma de uma Instância. Ele retorna dados como uma classe DiscoverOrganizationsResult que inclui uma propriedade OrganizationDetailCollection que contém uma coleção de instâncias de classe OrganizationDetail . Essa classe contém as mesmas informações que os Instance tipos retornados pelo serviço OData.

Note

Embora o parâmetro DiscoverOnlineOrganizationsAsync.discoveryServiceUri aceite uma URL para o Serviço de Descoberta Global, o método ignora quaisquer opções de consulta $filter ou $select. O DiscoverOnlineOrganizationsAsync.discoveryServiceUri parâmetro é opcional. Se você não o fornecer, o método usará a nuvem comercial por padrão.

Use CrmServiceClient

Para aplicativos .NET Framework, continue usando o método CrmServiceClient.DiscoverGlobalOrganizations para chamar o Serviço de Descoberta 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();

Assim como o ServiceClient.DiscoverOnlineOrganizationsAsync método, o CrmServiceClient.DiscoverGlobalOrganizations método também não retorna dados como uma Instância. Ele retorna um OrganizationDetailCollection que contém uma coleção de instâncias da Classe OrganizationDetail . Essa coleção contém as mesmas informações que os Instance tipos retornados pelo serviço OData.

Consulte Também

Exemplo: Exemplo do Serviço de Descoberta Global (C#)
Exemplo: acessar o serviço de descoberta usando CrmServiceClient
Exemplo: Blazor WebAssembly com Descoberta Global

  • Last updated on