Trabalhar com o Customer Insights - APIs de dados

Dynamics 365 Customer Insights - Os dados fornecem APIs para criar seus próprios aplicativos com base em seus dados no Customer Insights. Pode encontrar detalhes sobre estas APIs na referência da API, que inclui informações sobre operações, parâmetros e respostas.

Começar a experimentar as APIs

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

1. Inicie sessão no Customer Insights - Dados ou inscreva-se numa versão experimental do Customer Insights.

2. Vá para Configurações>de permissões e selecione a guia APIs .

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

   Quando ativas as APIs, crias uma chave de subscrição primária e uma secundária para o teu ambiente que usas nos pedidos da API. Para regenerar as chaves, selecione Regenerar primária ou Regenerar secundária no separador das APIs .

4. Selecione Explorar nossas APIs para experimentar as APIs.

5. Procure e selecione uma operação de API e selecione Experimentá-la.

   

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

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

8. Desloque-se para a parte inferior do painel lateral e selecione Enviar.

   A resposta HTTP é exibida na parte inferior do painel.

Criar um novo registo de aplicação no portal do Azure

Crie um novo registo de aplicação para usar as APIs numa aplicação 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, em seguida, selecione Registos de aplicações.

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

   Opcionalmente, adicione um URL de redirecionamento. http://localhost é suficiente para desenvolver uma aplicação no seu computador local.

5. Selecione Registar.

6. No registo da nova aplicação, vá a permissões da API.

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

8. Em 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 de administrador para... para concluir o registro do aplicativo.

11. Para aceder à API sem que um utilizador inicie sessão, vá a Definir permissões de aplicação servidor a servidor.

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

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

Definir permissões de aplicativo de servidor para servidor

Cria um registo de aplicação que não exija interação do utilizador e que possa correr num servidor.

1. No seu Registo de Aplicação no portal do Azure, aceda a Permissões de API.

2. Selecione Adicionar uma permissão.

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

4. Em 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 seu aplicativo.

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

8. Adicione o nome do registro do aplicativo como usuário em Customer Insights - Dados.

   1. Abra Customer Insights - Dados, vá para Configurações>de permissões e selecione Adicionar usuários.

   2. Procure o nome do registo da sua aplicação, selecione-o nos resultados da pesquisa e selecione Guardar.

Exemplos de consultas

Para obter uma pequena 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. Podes encontrar todo o código-fonte da biblioteca e aplicações de exemplo num repositório do GitHub.

C# NuGet

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

Adicionar a biblioteca de cliente C# a um projeto C#

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

2. Procure por 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 cliente C#

1. Utilize a Biblioteca de Autenticação da Microsoft (MSAL) para obter um AccessToken utilizando o seu registo de aplicações do Azure existente.

2. Depois de autenticar e adquirir um token, constrói um novo HttpClient ou usa um já existente. Defina o DefaultRequestHeaders "Authorization" para o "token de acesso" do Portador e defina Ocp-Apim-Subscription-Key para a chave de subscrição do seu ambiente Customer Insights - Dados.

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

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

4. Efetue chamadas com o cliente para os métodos de extensão, por exemplo, GetAllInstancesAsync. Se preferir aceder ao Microsoft.Rest.HttpOperationResponse subjacente, utilize os "métodos de mensagens HTTP", por exemplo, GetAllInstancesWithHttpMessagesAsync.

5. A resposta é provavelmente object tipo 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 o pedido, use os métodos de mensagem http para aceder ao objeto raw response.

pacote Node.js

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

Pacote Python

Use as bibliotecas de cliente Python disponíveis através do PyPi: https://pypi.org/project/customerinsights/