Trabajar con API de Customer Insights - Data

Dynamics 365 Customer Insights - Data proporciona API para crear sus propias aplicaciones basadas en los datos de Customer Insights. Los detalles de estas API se enumeran en la Referencia de las API. Incluyen información adicional sobre operaciones, parámetros y respuestas.

Nota

Las tablas de Customer Insights - Data también se pueden acceder mediante API de Dataverse. Le recomendamos que utilice Dataverse API para consultar los datos de Customer Insights, ya que ofrecen un filtrado más extenso, mayor rendimiento y menor latencia. Para obtener más información, consulte API de Dataverse para Customer Insights.

Comenzar a usar las API

Un administrador debe habilitar el acceso API a sus datos. Una vez habilitado el acceso, cualquier usuario puede utilizar la API con la clave de suscripción.

1. Inicie sesión en Customer Insights - Data o regístrese para obtener una versión de prueba de Customer Insights.

2. Vaya a Configuración>Permisos y seleccione la pestaña API.

3. Si no se ha configurado el acceso de API al entorno, seleccione Habilitar.

   La habilitación de las API crea una clave de suscripción primaria y secundaria para su entorno que se usa en las solicitudes de API. Para generar las claves, seleccione las opciones Regenerar principal o Regenerar secundaria en la pestaña API.

4. Seleccione Explorar nuestras API para probar las API.

5. Busque y seleccione una operación API y seleccione Pruébelo.

   

6. En el panel lateral, establezca el valor en el menú desplegable Autorización a implícito. El encabezado Authorization se agrega con un token de portador. Su clave de suscripción se completará automáticamente.

7. Opcionalmente, agregue todos los parámetros de consulta necesarios.

8. Desplácese hacia la parte inferior del panel lateral y seleccione Enviar.

   La respuesta HTTP se mostrará en la parte inferior del panel.

Crear un registro de nueva aplicación en Azure Portal

Crear un nuevo registro de aplicación para usar las API en una aplicación de Azure usando permisos delegados.

1. Complete la sección de introducción.

2. Inicie sesión en Azure Portal con la cuenta que puede acceder a los datos de Customer Insights.

3. Busque la aplicación y después seleccione Registros de aplicaciones.

4. Seleccione Nuevo registro, facilite un nombre de aplicación y elija el tipo de cuenta.

   Opcioonalmente, agregue una URL de redireccionamiento. http://localhost es suficiente para desarrollar una aplicación en su equipo local.

5. Seleccione Registrar.

6. En el registro de su nueva aplicación, vaya a Permisos de API.

7. Seleccione Agregar un permiso y seleccione Dynamics 365 AI para Customer Insights en el panel lateral.

8. En Tipo de permiso, seleccione Permisos delegados y seleccione el permiso user_impersonation.

9. Seleccione Agregar permisos.

10. Seleccione Otorgar consentimiento de administrador para... para completar el registro de la aplicación.

11. Para acceder a la API sin que un usuario inicie sesión, vaya a Establecer permisos de aplicación de servidor a servidor.

Puede utilizar la aplicación/id. de cliente para el registro de esta aplicación con la biblioteca de autenticación de Microsoft (MSAL) para obtener un token de portador para enviar con su solicitud a la API.

Para obtener información sobre el uso de las API en nuestras bibliotecas cliente, consulte Bibliotecas cliente de Customer Insights.

Establecer permisos de aplicaciones de servidor a servidor

Cree un registro de aplicación que no necesite la interacción del usuario y que se pueda ejecutar en un servidor.

1. En el registro de su aplicación en Azure Portal, vaya a Permisos de API.

2. Seleccione Agregar permiso.

3. Seleccione la pestaña API que usa mi organización y elija Dynamics 365 AI for Customer Insights en la lista.

4. Para Tipo de permiso, seleccione Permisos de aplicación y, después, seleccione el permiso api.access.

5. Seleccione Agregar permisos.

6. Vuelva a Permisos de API para el registro de su aplicación.

7. Seleccione Otorgar consentimiento de administrador para... para completar el registro de la aplicación.

8. Agregue el nombre del registro de la aplicación como usuario en Customer Insights - Data.

   1. Abra Customer Insights - Data, vaya a Ajustes>Permisos y seleccione Agregar usuarios.

   2. Busque el nombre del registro de su aplicación, selecciónelo en los resultados de búsqueda y seleccione Guardar.

Consultas de ejemplo

Para ver una breve lista de consultas de muestra de OData para trabajar con las API: Ejemplos de consultas de OData.

Bibliotecas de cliente de Customer Insights

Comience a utilizar las bibliotecas cliente disponibles para las API de Customer Insights - Data. Todo el código fuente de la biblioteca y las aplicaciones de muestra se pueden encontrar en un repositorio de GitHub.

C# NuGet

Use las bibliotecas de cliente C# de NuGet.org. Actualmente, el paquete se dirige a los marcos netstandard2.0 y netcoreapp2.0. Para obtener más información sobre el paquete NuGet, consulte Microsoft.Dynamics.CustomerInsights.Api.

Agregar la biblioteca de cliente de C# a un proyecto de C#

1. En Visual Studio, abra el NuGet Administrador de paquetes para su proyecto.

2. Busque Microsoft.Dynamics.CustomerInsights.Api.

3. Seleccione Instalar para agregar el paquete al proyecto.

   Alternativamente, ejecute este comando en la Consola del administrador de paquetes de NuGet: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Usar la biblioteca de cliente de C#

1. Utilice la Biblioteca de autenticación de Microsoft (MSAL) para obtener un AccessToken usando su Registro de la aplicación de Azure existente.

2. Después de autenticar y adquirir correctamente un token, construya uno nuevo o use un HttpClient existente con la "Autorización" DefaultRequestHeaders ajustada en Portador "token de acceso" y Ocp-Apim-Subscription-Key establecido en la clave de suscripción de su entorno de Customer Insights - Data.

   Restablezca el encabezado Autorización cuando sea apropiado. Por ejemplo, cuando haya expirado el token.

3. Pase este HttpClient a la construcción del cliente de CustomerInsights.

4. Realice llamadas con el cliente a los "métodos de extensión", por ejemplo, GetAllInstancesAsync. Si el acceso al Microsoft.Rest.HttpOperationResponse subyacente es preferible, utilice los "métodos de mensaje http", por ejemplo GetAllInstancesWithHttpMessagesAsync.

5. La respuesta probablemente sea del tipo object porque el método puede devolver varios tipos (por ejemplo, IList<InstanceInfo> y ApiErrorResult). Para comprobar el tipo de retorno, utilice los objetos en los tipos de respuesta especificados en la página de detalles de la API para esa operación.

   Si necesita más información sobre la solicitud, utilice los métodos de mensaje http para acceder al objeto de respuesta sin procesar.

Paquete NodeJS

Utilice las bibliotecas cliente de NodeJS disponibles a través de NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Paquete de Python

Utilice las bibliotecas cliente de Python disponibles a través de PyPi: https://pypi.org/project/customerinsights/