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. Os detalhes dessas APIs estão listados na referência à API. Eles incluem informações adicionais sobre operações, parâmetros e respostas.

Comece a experimentar as 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 à API ao ambiente não tiver sido configurado, selecione Habilitar.

   Habilitar as APIs cria uma chave de assinatura primária e secundária para seu ambiente que é usada nas solicitações de API. Para regenerar as chaves, selecione regenerar primário ou regenerar secundário na guia 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 um aplicativo 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 um nome de aplicativo 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. Em seu novo registro de aplicativo, acesse as permissões de 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 registro de aplicativo que não precise de interação do usuário e possa ser executado 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. Todos os aplicativos de exemplo e código-fonte da biblioteca podem ser encontrados em um repositório 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 obter mais informações sobre o pacote NuGet, consulte 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 o registro de aplicativo existente do Azure.

2. Depois de autenticar e adquirir um token com êxito, construa um novo ou use um existente HttpClient com o DefaultRequestHeaders "Authorization" definido como Bearer "token de acesso" e Ocp-Apim-Subscription-Key definido para a chave de assinatura do seu Customer Insights - ambiente de dados.

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

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

4. Faça chamadas com o cliente para os "métodos de extensão", por exemplo, GetAllInstancesAsync. Se o acesso ao subjacente Microsoft.Rest.HttpOperationResponse for preferencial, 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 mais informações sobre a solicitação forem necessárias, use os métodos de mensagem http para acessar o objeto de resposta bruta.

Pacote NodeJS

Use as bibliotecas de cliente nodeJS disponíveis por meio do NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Pacote do Python

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