Partilhar via

Trabalhar com APIs do Customer Insights - Data

  • Artigo

O Dynamics 365 Customer Insights - Data fornece APIs para criar as suas próprias aplicações com base nos seus dados no Customer Insights. Os detalhes destas APIs estão listados na referência de API. Incluem informações adicionais sobre operações, parâmetros e respostas.

Nota

As tabelas Customer Insights - Data também podem ser acedidas através de APIs Dataverse. Recomendamos que utilize APIs Dataverse para consultar dados do Customer Insights, uma vez que oferecem filtragem mais extensiva, maior débito e menor latência. Para mais informações, consulte APIs do Dataverse para o Customer Insights.

Começar a experimentar as APIs

Um admin tem de ativar o acesso à API aos seus dados. Após o acesso estar ativo, qualquer utilizador pode utilizar a API com a chave de subscrição.

  1. Inicie sessão no Customer Insights - Data ou inscreva-se para uma versão de avaliação do Customer Insights.

  2. Aceda a Definições>Permissões e selecione o separador APIs.

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

    Ativar as APIs cria uma chave de subscrição primária e secundária para o seu ambiente que é utilizado nos pedidos da API. Para regenerar as chaves, selecione Regenerar primária ou Regenerar secundária no separador API.

  4. Selecione Explore as nossas API para experimentar as API.

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

    Como testar as APIs.

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

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

  8. Percorra a parte inferior do painel lateral e selecione Enviar.

    A resposta HTTP é apresentada no fundo do painel.

Crie o registo de uma nova aplicação no portal do Azure

Crie um novo registo da aplicação para utilizar as APIs numa aplicação do Azure utilizando permissões delegadas.

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

  2. Inicie sessão no portal Azure com a conta que pode aceder aos dados do Customer Insights.

  3. Pesquise e depois selecione Registos de aplicações.

  4. Selecione Novo registo, forneça um nome de aplicação 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 seu novo registo de Aplicação, aceda às permissões da API.

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

  8. Para 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 o consentimento do administrador para... completar o registo da aplicação.

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

Pode utilizar o ID de Aplicação/Cliente para este registo de aplicações com a Biblioteca de Autenticação da Microsoft (MSAL) para obter um token de portador para enviar juntamente com o seu pedido para a API.

Para obter informações sobre a utilização de APIs nas bibliotecas dos nossos clientes, consulte Bibliotecas de clientes do Customer Insights.

Permissões de aplicação de servidor a servidor

Crie um registo de aplicação que não necessite da interação com o utilizador e que possa ser executado num servidor.

  1. No registo da sua aplicação no portal Azure, aceda às permissões da API.

  2. Selecione Adicionar uma permissão.

  3. Selecione o separador APIs que a minha organização utiliza e escolha IA do Dynamics 365 para o Customer Insights da lista.

  4. Para Tipo de permissão, selecione Permissões da aplicação e, em seguida, selecione a permissão api.access.

  5. Selecione Adicionar permissões.

  6. Aceda novamente às permissões da API para registo da sua aplicação.

  7. Selecione Conceder o consentimento do administrador para... completar o registo da aplicação.

  8. Adicione o nome do registo da aplicação como utilizador no Customer Insights - Data.

    1. Abra o Customer Insights - Data, aceda a Definições>Permissões e selecione Adicionar utilizadores.

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

Consultas de amostra

Para uma pequena lista de consultas de amostra OData para trabalhar com as API, consulte Exemplos de consultas OData.

Bibliotecas de clientes Customer Insights

Começar a utilizar as bibliotecas de clientes disponíveis para APIs do Customer Insights - Data. Todos os códigos de origem da biblioteca e aplicações de exemplo podem ser encontrados num repositório do GitHub.

C# NuGet

Utilize as bibliotecas de cliente C# a partir de NuGet.org. Atualmente, o pacote destina-se aos enquadramentos netstandard2.0 e netcoreapp2.0. Para mais informações sobre o pacote NuGet, consulte Microsoft.Dynamics.CustomerInsights.Api.

Adicione a biblioteca C# ao projeto C#

  1. No Visual Studio, abra o NuGet Gestor do pacote para o seu projeto.

  2. Pesquisar por Microsoft.Dynamics.CustomerInsights.Api.

  3. Selecione Instalar para adicionar o pacote ao projeto.

    Em alternativa, executar este comando na NuGet Consola do Gestor de Pacotes: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Use 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 Azure existente.

  2. Depois de autenticar e adquirir um token com êxito, crie um ou utilize 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 subscrição do seu ambiente do Customer Insights - Data.

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

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

  4. Faça chamadas com o cliente para os "métodos de extensão", por exemplo, GetAllInstancesAsync. Se for preferido o acesso ao Microsoft.Rest.HttpOperationResponse subjacente, utilize os "métodos de mensagem http", por exemplo, GetAllInstancesWithHttpMessagesAsync.

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

    Se forem necessárias mais informações sobre o pedido, utilize os métodos de mensagem http para aceder ao objeto de resposta bruta.

Pacote NodeJS

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

Pacote Python

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