Descubra a URL da sua organização usando a a API da Web

Artigo
07/06/2017

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Esse serviço de descoberta para API da Web Microsoft Dynamics 365 permite que seus aplicativos determinem, em tempo de execução, as organizações, também conhecidas como instâncias, às quais pertence o usuário conectado. Você pode recuperar informações detalhadas sobre essas instâncias, como a URL do serviço da instância, a versão de lançamento do Dynamics 365, a ID da instância e muito mais. Você pode usar o $filter padrão e parâmetros $select para um serviço de API Web solicitar personalização da devolução de lista dos dados da instância. O serviço de Descoberta tem suporte de todos os tipos de implantação do Dynamics 365: Online, no local e IFD.

Os aplicativos clientes do podem precisam de acesso a uma instância Dynamics 365 na qual a URL da instância pode alterar ao longo do tempo. Por exemplo, quando uma instância Dynamics 365 for movida de um datacenter Microsoft Dynamics 365 (online) do outro. O serviço de descoberta permite que a instância de clientes persista à ID da instância ou instância do nome exclusivo e use o serviço de descoberta a consulta a URL da instância atual de acesso.

Além de serviços específicos de descoberta, datacenter que está disponível em 2011 pontos de extremidade (SOAP) com a API, também há um serviço de descoberta global somente da API que mede todas os datacenters operacionais. Para obter mais informações sobre o serviço de descoberta do ponto de extremidade de 2011, consulte Descubra a URL da sua organização usando o Serviço da Organização.

Informações fornecidas pelo serviço de descoberta

Informações da organização armazenadas na entidade Instance de serviço de descoberta. Para ver o tipo de informação contida nessa entidade, envie uma solicitação de HTTP GET ao serviço para uma de suas instâncias.

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

No exemplo acima, globais do serviço de3 descoberta do Microsoft Dynamics 365 (online) são usados para obter as informações da organização da instância com um único nome de "myorg". Mais detalhes sobre a solicitação são expandidos mediante posteriormente neste tópico.

Escopo de informações devolvido

Globais do serviço de descoberta, o conjunto de entidades Instances retorna o cluster, instâncias de que o usuário tem acesso em todas as geografias, quando um filtro é aplicado. Os dados retornados têm um escopo conforme descrito a seguir.

Inclui todas as instâncias na nuvem comercial onde o usuário é provisionado e habilitado, exceto em instâncias de nuvens independentes não são devolvidas
Não inclui as instâncias em que a conta de usuário é desativado
Não inclui as instâncias em que os usuários são filtrados de baseada em uma instância do grupo de segurança
Não inclui as instâncias em que o usuário tem acesso depois de ser um administrador delegado
Se o usuário da chamada tem acesso a nenhuma resposta, a remoção simplesmente retorna uma lista vazia

Como acessar os serviços de descoberta

Normalmente, o endereço da API do serviço de descoberta com este formato: <service base address>/api/discovery/. Os endereços para cada tipo de implantação são identificados abaixo. É fácil localizar os endereços e o número de versão da API da implantação no aplicativo web Dynamics 365 navegando em Configurações > Recursos de personalização > Desenvolvedor

Serviços de descoberta do Dynamics 365 (online)

O endereço de serviço globais do serviço de descoberta é: https://globaldisco.crm.dynamics.com/. Isso resulta ao endereço https://globaldisco.crm.dynamics.com/api/discovery/.

O endereço de serviço globais do serviço de descoberta de um centro de dados é: https://disco.crm[N].dynamics.com/. Isso resulta ao endereço de descoberta de https://disco.crm[N].dynamics.com/api/discovery/. Cada datacenter tem N números associados a ele. Para obter uma lista completa de datacenters disponíveis Microsoft Dynamics 365 (online), e os número N, consulte Baixar os pontos de extremidade usando a página de recursos do Desenvolvedor do Microsoft Dynamics 365.

Local e do serviço de descoberta

O endereço de serviço do serviço de descoberta local ou para implantação da IFD será: http[s]://{servername}/ ou http[s]://dev.{servername}/. Isso resulta ao endereço http[s]://{servername}/api/discovery/ ou http[s]://dev.{servername}/api/discovery/.

Usando o serviço de descoberta

Uma entidade definida nomeada como Instances é usada para obter informações de instância. Você pode usar $select e $filter com a entidade de instâncias definida para filtrar os dados devolvidos. Você também pode usar para obter $metadata o documento de metadados de serviço.

Autenticação

Instancias API da Web Microsoft Dynamics 365 (online) do serviço de descoberta precisam de autenticação com tokens de acesso ao OAuth. No local ou instâncias de IFD de descoberta da API adotam o módulo de autenticação de implantação, suportando tokens integrados de Autenticação do Windows (IWA) ou de um provedor de token OAuth confiável. Sessão de autenticação de aplicativo Web não suportada.

Quando o serviço de descoberta estiver configurado para autenticação de OAuth, uma solicitação é enviada para os disparadores de API de um token de acesso a um desafio de portador autoridade de ponto de extremidade "comuns" e a ID de recursos do serviço. Da mesma forma, quando uma implantação no local estiver configurada para OAuth, devoluções de um desafio de portador a URL de autoridade no local e a ID de recursos do serviço.

Controle de versão da API Web

Controle de versão do serviço de descoberta para um datacenter ou um local/IFD tem suporte e consiste consistente com numeração de versões como usado pelo serviço da organização. Entretanto, o serviço de descoberta globais Microsoft Dynamics 365 (online) não está associado ao número de versão Dynamics 365 de implantação. Em vez disso, ele usa seu próprio global numeração de versões. Até a data da redação, globais do serviço Microsoft Dynamics 365 (online) de descoberta que está na versão 1.0 (v1.0). Por exemplo:

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

Suporte do CORS

O serviço Web de descoberta API suporte a NÚCLEOS padrão para acesso de origem entre a API do serviço Web de organização. Para obter mais informações sobre suporte a CORS, consulte Use o OAuth com compartilhamento de recursos entre origens para conectar um aplicativo de página única ao Microsoft Dynamics 365.

Exemplos

Obter detalhes de uma instância específica. Se você deixar o GUID, todas as instâncias as quais o usuário autenticado tem acesso a são devolvidas.
```
GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)
GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)
```

Você pode usar o atributo UniqueName como uma chave alternativa.

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

Recuperação de uma lista filtrada, instâncias disponíveis pela produção.

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0

Recuperar o valor de ID de propriedade da instância específica.

GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value

Microsoft Dynamics 365

Partilhar via