Trabalhar com o Customer Insights – APIs de dados

Dynamics 365 Customer Insights – Dados fornece APIs para criar seus próprios aplicativos com base nos seus dados no Customer Insights. Você pode encontrar detalhes sobre essas APIs na referência da API, que inclui informações sobre operações, parâmetros e respostas.

Introdução à tentativa das APIs

Um administrador deve habilitar o acesso à API aos seus dados. Depois que o acesso estiver habilitado, qualquer usuário poderá usar a API com a chave de assinatura.

1. Entre no Customer Insights – Dados ou inscreva-se para uma avaliação do Customer Insights.

2. Vá para Configurações>Permissões e selecione a aba APIs.

3. Se o acesso da API ao ambiente não estiver configurado, selecione Ativar.

   Quando você habilita as APIs, cria uma chave de assinatura primária e uma secundária para o seu ambiente que você usa nas requisições da API. Para regenerar as chaves, selecione Regenerar primária ou Regenerar secundária na aba APIs .

4. Selecione Explorar nossas APIs para experimentar as APIs.

5. Pesquise e selecione uma operação de API e selecione Experimentar.

   

6. No painel lateral, defina o valor no menu suspenso Autorização como implícito. O Authorization cabeçalho é adicionado com um token do portador. Sua chave de assinatura é preenchida automaticamente.

7. Opcionalmente, adicione todos os parâmetros de consulta necessários.

8. Role até a parte inferior do painel lateral e selecione Enviar.

   A resposta HTTP é exibida na parte inferior do painel.

Criar um novo registro de aplicativo no portal do Azure

Crie um novo registro de aplicativo para usar as APIs em uma aplicação do Azure usando permissões delegadas.

1. Conclua a seção Introdução.

2. Entre no portal do Azure com a conta que pode acessar os dados do Customer Insights.

3. Pesquise e selecione registros de aplicativo.

4. Selecione Novo registro, forneça o nome da inscrição e escolha o tipo de conta.

   Opcionalmente, adicione uma URL de redirecionamento. http://localhost é suficiente para desenvolver um aplicativo em seu computador local.

5. Selecione Registrar.

6. Ao registrar seu novo aplicativo, vá para permissões da API.

7. Selecione Adicionar uma permissão e selecione AI do Dynamics 365 para Customer Insights no painel lateral.

8. Para o tipo de permissão, selecione permissões delegadas e, em seguida, selecione a permissão user_impersonation .

9. Selecione Adicionar permissões.

10. Selecione Conceder consentimento do administrador para... para concluir o registro do aplicativo.

11. Para acessar a API sem que um usuário entre, vá para Definir permissões de aplicativo servidor a servidor.

Você pode usar a ID do aplicativo/cliente para este registro de aplicativo com a MSAL (Biblioteca de Autenticação da Microsoft) para obter um token de portador a ser enviado com sua solicitação para a API.

Para obter informações sobre como usar as APIs em nossas bibliotecas de clientes, consulte as bibliotecas de clientes do Customer Insights.

Definir permissões de aplicativo de servidor para servidor

Crie um cadastro de app que não precise de interação do usuário e que possa rodar em um servidor.

1. No registro de aplicativo no portal do Azure, acesse as permissões de API.

2. Selecione Adicionar permissão.

3. Selecione a guia APIs que minha organização usa e escolha Dynamics 365 AI for Customer Insights na lista.

4. Para o tipo de permissão, selecione permissões de aplicativo e, em seguida, selecione a permissão api.access .

5. Selecione Adicionar permissões.

6. Volte para as permissões de API para o registro do aplicativo.

7. Selecione Conceder consentimento do administrador para... para concluir o registro do aplicativo.

8. Adicione o nome do registro do aplicativo como usuário no Customer Insights – Dados.

   1. Abra o Customer Insights – Dados, vá paraAs Permissões de > e selecione Adicionar usuários.

   2. Pesquise o nome do registro do aplicativo, selecione-o nos resultados da pesquisa e selecione Salvar.

Exemplos de consultas

Para obter uma breve lista de consultas de exemplo OData para trabalhar com as APIs, consulte exemplos de consulta OData.

Bibliotecas de clientes do Customer Insights

Comece a usar as bibliotecas de cliente disponíveis para o Customer Insights – APIs de dados. Você pode encontrar todo o código-fonte da biblioteca e aplicações de exemplo em um repositório do GitHub.

C# NuGet

Use as bibliotecas de cliente C# de NuGet.org. Atualmente, o pacote tem como destino as estruturas netstandard2.0 e netcoreapp2.0. Para mais informações sobre o pacote NuGet, veja Microsoft.Dynamics. CustomerInsights.Api.

Adicionar a biblioteca de clientes do C# a um projeto em C#

1. No Visual Studio, abra o Gerenciador de Pacotes NuGet para seu projeto.

2. Pesquise Microsoft.Dynamics.CustomerInsights.Api.

3. Selecione Instalar para adicionar o pacote ao projeto.

   Como alternativa, execute este comando no Console do Gerenciador de Pacotes NuGet: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Usar a biblioteca de clientes do C#

1. Use a Biblioteca de Autenticação da Microsoft (MSAL) para obter um AccessToken usando seu registro do Azure App existente.

2. Depois de autenticar e adquirir um token, construa um novo HttpClient ou use um já existente. Defina DefaultRequestHeaders "Authorization" como Bearer "token de acesso" e defina Ocp-Apim-Subscription-Key como a chave de assinatura do seu ambiente Customer Insights - Data.

   Redefina o cabeçalho autorização quando apropriado. Por exemplo, quando o token expira.

3. Passe este HttpClient para a construção do cliente CustomerInsights.

4. Faça chamadas com o cliente para os "métodos de extensão", por exemplo, GetAllInstancesAsync. Se você preferir acessar o Microsoft.Rest.HttpOperationResponse subjacente, use os "métodos de mensagem HTTP", por exemplo, GetAllInstancesWithHttpMessagesAsync.

5. A resposta é um tipo provável object porque o método pode retornar vários tipos (por exemplo, IList<InstanceInfo> e ApiErrorResult). Para verificar o tipo de retorno, use os objetos nos tipos de resposta especificados na página de detalhes da API para essa operação.

   Se precisar de mais informações sobre a solicitação, use os métodos de mensagem http para acessar o objeto raw response.

pacote Node.js

Use as bibliotecas de cliente do Node.js disponíveis no NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Pacote Python

Use as bibliotecas de cliente Python disponíveis por meio do PyPi: https://pypi.org/project/customerinsights/