Compartilhar via

Trabalhar com APIs do Customer Insights - Data

  • Artigo

O Dynamics 365 Customer Insights - Data fornece APIs para criar seus próprios aplicativos com base em seus dados no Customer Insights. Os detalhes dessas APIs estão listados na Referência de API. Eles incluem informações adicionais sobre operações, parâmetros e respostas.

Observação

As tabelas do Customer Insights - Data também podem ser acessadas usando APIs do Dataverse. É recomendável usar as APIs do Dataverse para consultar dados do Customer Insights, pois elas oferecem uma filtragem mais extensa, mais taxa de transferência e menos latência. Para obter mais informações, consulte APIs do Dataverse para Customer Insights.

Introdução à tentativa das APIs

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

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

  2. Acesse Configurações>Permissões e selecione a guia APIs.

  3. Se o acesso da API ao ambiente não tiver sido configurado, selecione Habilitar.

    A habilitação das APIs cria uma chave de assinatura primária e secundária para o ambiente, que é usada nas solicitações de API. Para regenerar as chaves, selecione Regenerar primária ou Regenerar secundária na guia APIs.

  4. Selecione Explorar nossas APIs para experimentar as APIs.

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

    Como testar as APIs.

  6. No painel lateral, defina o valor no menu suspenso Autorização como implícito. O cabeçalho Authorization será adicionado com um token de portador. Sua chave de assinatura será 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 será exibida na parte inferior do painel.

Criar um registro de aplicativo no portal do Azure

Crie um novo registro de aplicativo para usar as APIs em um aplicativo 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. Procure e selecione Registros de aplicativo.

  4. Selecione Novo registro, forneça um nome de aplicativo e escolha o tipo de conta.

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

  5. Selecione Registrar.

  6. No seu novo registro de aplicativo, vá para Permissões de API.

  7. Selecione Adicionar uma permissão e 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 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 de servidor para servidor.

Você pode usar a ID do aplicativo/cliente para esse registro de aplicativo na Biblioteca de Autenticação da Microsoft (MSAL) a fim de obter um token de portador para envio com sua solicitação à 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

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 do seu aplicativo no portal do Azure, vá para Permissões de API.

  2. Selecione Adicionar permissão.

  3. Selecione a guia APIs que minha organização usa e escolha Dynamics 365 AI para 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 Permissões de API para o registro do seu aplicativo.

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

  8. Adicione o nome do registro do aplicativo como um usuário no Customer Insights - Data.

    1. Abra o Customer Insights - Data, vá até Configurações>Permissões e selecione Adicionar usuários.

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

Consultas de amostra

Para ver 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 clientes disponíveis para as APIs do Customer Insights - Data. Todo o código-fonte da biblioteca e os aplicativos de exemplo podem ser encontrados em um repositório do GitHub.

C# NuGet

Use as bibliotecas de clientes C# de NuGet.org. Atualmente, o pacote é direcionado às estruturas netstandard2.0 e netcoreapp2.0. Para obter 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 o seu projeto.

  2. Procure Microsoft.Dynamics.CustomerInsights.Api.

  3. Selecione Instalar para adicionar o pacote ao projeto.

    Se desejar, 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. 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 com êxito, crie ou use um HttpClient existente com a "Autorização" DefaultRequestHeaders definida como "Token de acesso" de Portador e Ocp-Apim-Subscription-Key definida como a chave de assinatura do ambiente do Customer Insights - Data.

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

  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 o acesso ao Microsoft.Rest.HttpOperationResponse subjacente for preferencial, use os "métodos de mensagem http", por exemplo, GetAllInstancesWithHttpMessagesAsync.

  5. A resposta provavelmente será do tipo 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 Detalhes da API dessa 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 bruto.

Pacote NodeJS

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

Pacote Python

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