Usar Insomnia con la API web de Dataverse

Existen muchas herramientas API de cliente que puede utilizar para autenticarse en entornos de Microsoft Dataverse para redactar y enviar solicitudes de API web. Estas herramientas facilitan el aprendizaje, la prueba y la realización de consultas ad hoc mediante la API web de Dataverse.

Este artículo tiene dos objetivos:

1. Demostrar una estrategia para autenticar y conectarse a Dataverse usando Cliente API de Insomnia con un Id. de aplicación de Microsoft Entra (cliente) proporcionado por Microsoft que está aprobado previamente para todos los entornos de Dataverse. Esto significa que no necesita registrar una aplicación para comenzar a usar la API web de Dataverse.
2. Introducción a algunas operaciones básicas de datos que puede realizar utilizando la API Web de Dataverse en el contexto del cliente de la API de Insomnia. De esta manera, puede utilizar Insomnia para seguir experimentando y aprendiendo sobre la API web de Dataverse.

Privacidad

Las solicitudes que envía con las herramientas API cliente contienen información que podría ser sensible. Muchos desarrolladores no quieren que esta información se suba a un servicio en la nube.

El Bloc de notas local de Insomnia no requiere que cree una cuenta y no almacena información sobre las solicitudes que envía. Las instrucciones proporcionadas aquí describen cómo utilizar únicamente el Bloc de notas local de Insomnia. Puede optar por crear una cuenta y utilizar todas las características de Insomnia si lo desea. Si desea una versión que no tenga opciones para crear una cuenta y se centre en la privacidad, consulte Insomnia.

Instalar Insomnia

Consulte la Documentación de Insomnia sobre los pasos para instalar Insomnia. Las instrucciones son diferentes para macOS, Windows y Linux.

Para Windows, el instalador es un ejecutable (exe) que usted descarga y ejecuta. Cuando se complete la instalación, es posible que se le ofrezcan diferentes opciones. Estas opciones no deberían interferir con las instrucciones de este artículo, pero podrían cambiar. En el momento en que se escribió este artículo, se presentaban estas opciones:

• Para tener la opción de habilitar funciones para sincronizar datos con la nube, elija Seguir almacenando localmente en Local Vault.

• Para tener la opción de crear una cuenta, elija Usar el Bloc de notas local. Más información sobre el Bloc de notas de Insomnia

  

Configurar el entorno base

Utilice entornos de Insomnia para almacenar variables de entorno. Las variables de entorno son un objeto JSON que contiene pares de datos clave-valor a los que puede hacer referencia para muchos propósitos.

El entorno base se asigna a cada espacio de trabajo y se puede obtener acceso a las variables que contiene en todo el espacio de trabajo.

1. Después de abrir Insomnia, seleccione el ícono de configuración al lado del entorno base para abrir el cuadro de diálogo Administrar entornos. O bien, utilice el método abreviado de teclado Ctrl + E.

2. Copie el siguiente JSON:

   {
      "url": "https://yourorg.api.crm.dynamics.com",
      "version": "9.2",
      "webapiurl": "{{ _.url }}/api/data/v{{ _.version }}/",
      "redirecturl": "https://localhost",
      "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{ _.url }}",
      "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
   }
   

3. Pegue el JSON en el entorno base.

4. Edite el valor de la propiedad url y reemplace el valor https://yourorg.api.crm.dynamics.com que coincida con la URL de su Dataverse entorno.

   Puede encontrar el punto final de la API web para su entorno siguiendo las instrucciones de Ver recursos del desarrollador. Elimine /api/data/v9.2 de la URL punto de conexión de la API web. Esta URL debe terminar en dynamics.com.

   Debería esperar que las referencias a las variables _.url y _.version no se resuelvan inmediatamente, por lo que verá advertencias como esta:

   

   Sin embargo, después de cerrar la ventana y volver a abrirla, podrá ver que las variables ahora se conocen y se han resuelto.

   

Crear entornos secundarios (opcional)

Si solo necesita conectarse a un único entorno de Dataverse, puede utilizar el entorno base. Si necesita conectarse a varios entornos, puede crear entornos secundarios para cada entorno de Dataverse. Por ejemplo, puede crear un entorno secundario para sus entornos de desarrollo y prueba de Dataverse.

1. Tal como hizo con el entorno base, seleccione el icono de configuración al lado del entorno base para abrir el cuadro de diálogo Administrar entornos. O bien, utilice el método abreviado de teclado Ctrl + E.

2. Seleccione el icono para crear un nuevo entorno. Los entornos pueden ser compartidos o privados. Elija Entorno privado.

3. Haga doble clic en el nombre del Nuevo entorno que creó y cámbiele el nombre como desee, puede darle el nombre del entorno de Dataverse que desee. al que conectarse o algo así como Entorno de desarrollo.

4. Copie el siguiente JSON:

   {
      "url": "https://yourdevorg.api.crm.dynamics.com"
   }
   

5. Pegue el JSON en el entorno que ha creado.

6. Edite el valor de propiedad url para representar el punto de conexión de API web para su otro entorno, tal como lo hizo para el entorno base.

   Nota

   Solo necesita incluir la propiedad url en el entorno secundario. Cuando se selecciona el entorno secundario, este valor anula el valor de url especificado en el entorno base. También puede incluir cualquiera de las otras 5 propiedades si lo desea, pero el valor de la propiedad url es el único que es diferente para cada entorno de Dataverse.

Configurar solicitudes

Después de configurar su entorno base y cualquier entorno secundario, está listo para configurar una solicitud.

1. Seleccione el botón Nueva solicitud HTTP o utilice el método abreviado de teclado Ctrl+N .

2. Después del método HTTP, que es GET de forma predeterminada, escriba _. y espere un momento. Insomnia muestra una lista de variables disponibles para elegir:

   

3. Elija la variable _.webapiurl. El campo URL PREVIEW debe mostrar el valor utilizando el valor de propiedad url para el entorno seleccionado.

4. En la pestaña Aut. , use el menú desplegable para seleccionar OAuth 2.0 AUTH TYPE.

   

5. Edite la configuración de autenticación como se muestra en la siguiente tabla, utilizando las variables de entorno que creó:

   Campo	valor
   GRANT TYPE	Implícito
   AUTHORIZATION URL	_.authurl
   CLIENT ID	_.clientid
   REDIRECT URL	_.redirecturl

6. Seleccione Enviar.

   Debería abrirse un cuadro de diálogo para introducir las credenciales del entorno.

   Después de introducir sus credenciales, debería ver resultados en el panel Vista previa, que tiene este aspecto:

   {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
   "value": [
      {
         "name": "aadusers",
         "kind": "EntitySet",
         "url": "aadusers"
      },
      {
         "name": "accounts",
         "kind": "EntitySet",
         "url": "accounts"
      },
      {
         "name": "aciviewmappers",
         "kind": "EntitySet",
         "url": "aciviewmappers"
      },
      {
         "name": "actioncards",
         "kind": "EntitySet",
         "url": "actioncards"
      },
      ...
   

   Este resultado es el documento de servicio de API web. Puede ver el documento de servicio enviando una solicitud GET a la raíz de la URL del servicio API web. Enumera los nombres de conjuntos de entidades para todas las tablas en su entorno de Dataverse. Cuando pueda ver el documento de servicio, se habrá autenticado correctamente en su entorno de Dataverse.

   Sugerencia

   Se trata de una forma cómoda de encontrar o verificar el nombre del conjunto de entidades de una tabla con la que esté trabajando.

Ver el documento CSDL $metadata

El documento Common Schema Definition Language (CSDL) $metadata es la fuente de verdad para todo lo relacionado con la API web. Se recomienda hacer referencia al mismo con frecuencia.

1. Edite la URL agregando $metadata?annotations=true después de la variable _.webapiurl. La URL debe ser:

   GET _.webapiurl $metadata?annotations=true

2. Seleccione Enviar.

En el panel Vista previa, debería ver un mensaje que dice Respuesta de más de 5 MB oculta por motivos de rendimiento, con las opciones para Guardar en archivo y Mostrar de todos modos. El archivo es grande, pero debería poder obtener una vista previa sin problemas.

Buscar definiciones de tipos

El documento CSDL $metadata es grande. La vista previa de Insomnia proporciona una herramienta de filtrado de respuestas en la parte inferior. Puede usar consultas de XPath para filtrar la respuesta y encontrar lo que necesita. La siguiente tabla muestra algunos ejemplos:

Obtenga más información sobre los tipos definidos en el documento CSDL $metadata

Enviar una solicitud WhoAmI

Ahora que está autenticado, modifique su solicitud para invocar la función WhoAmI. Como WhoAmI es una función, utiliza un método GET. Esta función no tiene parámetros, por lo que es fácil de usar. Más información sobre el uso de las funciones de la API web

1. Edite la URL agregando WhoAmI después de la variable _.webapiurl. La URL debe ser:

   GET _.webapiurl WhoAmI

2. Establezca encabezados de solicitud.

   Como se describe en los encabezados HTTP, cada solicitud de API web debe tener un conjunto específico de encabezados de solicitud y es posible que deba modificar los valores de los encabezados para diferentes comportamientos.

   En la pestaña Encabezados, seleccione el botón Agregar para introducir cada uno de los siguientes encabezados comunes:

   Encabezado	valor
   Accept	application/json
   OData-MaxVersion	4.0
   OData-Version	4.0
   If-None-Match	null
   Prefer	odata.include-annotations="*"

   Estos encabezados no cambian el comportamiento de la función WhoAmI, pero es bueno empezar a agregarlos desde el principio.

3. Seleccione Enviar.

   En el panel Vista previa, debería ver los datos correspondientes al tipo complejo WhoAmIResponse.

   {
      "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
      "BusinessUnitId": "77164db8-dbc7-ee11-907a-00224803d046",
      "UserId": "e6b56e50-a3d5-ee11-9078-000d3a59a579",
      "OrganizationId": "100462a3-76cb-ee11-9075-00224806e300"
   }
   

Recuperar datos

Para utilizar Insomnia para recuperar registros, debe configurar el nombre del conjunto de entidades para el recurso.

1. Cambie la URL para eliminar WhoAmI después de la variable _.webapiurl y reemplácela con accounts, el nombre del conjunto de entidades para el tipo de entidad de cuenta. La URL debe ser:

   GET _.webapiurl accounts

2. En la pestaña Parámetros, establezca los parámetros para su consulta.

   Puede agregar parámetros individualmente seleccionando el botón Agregar. Pero también puede seleccionar la opción Edición masiva, que puede que le resulte más fácil.

   1. Seleccione la opción Edición masiva.
   2. Copie los siguientes parámetros:

   $top: 3
   $select: name,revenue,address1_city
   $expand: primarycontactid($select=fullname)
   $filter: address1_city eq 'Redmond'
   

   Esta consulta devuelve columnas seleccionadas de los tres registros de cuentas principales ubicados en la ciudad de Redmond e incluye información sobre cualquier contacto relacionado especificado como contacto principal de las cuentas.

   1. Pegue los valores en el campo QUERY PARAMETERS.

      La consulta debe tener este aspecto:

      

3. Seleccione Enviar.

   En el panel Vista preliminar, debe ver los resultados como los siguientes:

   {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city,primarycontactid(fullname))",
   "@Microsoft.Dynamics.CRM.totalrecordcount": -1,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
   "@Microsoft.Dynamics.CRM.globalmetadataversion": "2341840",
   "value": [
      {
         "@odata.etag": "W/\"2343103\"",
         "name": "City Power & Light (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
         "revenue": 100000.0,
         "address1_city": "Redmond",
         "accountid": "01eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Scott Konersmann (sample)",
         "contactid": "15eaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      },
      {
         "@odata.etag": "W/\"2343104\"",
         "name": "Contoso Pharmaceuticals (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$60,000.00",
         "revenue": 60000.0,
         "address1_city": "Redmond",
         "accountid": "03eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Robert Lyon (sample)",
         "contactid": "17eaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      },
      {
         "@odata.etag": "W/\"2343106\"",
         "name": "A. Datum Corporation (sample)",
         "revenue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
         "revenue": 10000.0,
         "address1_city": "Redmond",
         "accountid": "07eaf28f-81e1-ee11-904d-000d3a3517c4",
         "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
         "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
         "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
         "address1_composite": "Redmond",
         "primarycontactid": {
         "fullname": "Rene Valdes (sample)",
         "contactid": "1beaf28f-81e1-ee11-904d-000d3a3517c4"
         }
      }
   ]
   }
   

   Nota

   Estos resultados incluyen muchos valores de anotación como @OData.Community.Display.V1.FormattedValue porque el Prefer: odata.include-annotations="*" encabezado de solicitud establecido en Enviar una solicitud WhoAmI está configurado para devolver todas las anotaciones. Aprender a solicitar anotaciones específicas

Obtenga más información sobre cómo consultar datos

Creación de un registro

Con Insomnia, puede definir varias solicitudes que puede reutilizar. La manera fácil de crear una nueva solicitud que mantenga cualquier configuración que tenga es duplicar una solicitud existente. En este paso, duplicamos la solicitud definida en la sección Recuperar datos y creamos una nueva solicitud para crear un registro.

1. La solicitud que creó en Recuperar datos tiene el nombre predeterminado Nueva solicitud, a menos que lo haya cambiado. Cambie el nombre de la solicitud Recuperar cuentas.

2. Cuando pasa el cursor sobre la solicitud Recuperar cuentas, seleccione el menú desplegable y seleccione Duplicar.

   

3. En el cuadro de diálogo Duplicar solicitud, establezca Nuevo nombre en Crear cuenta.

4. En la nueva solicitud Crear cuenta, cambie el método HTTP de GET a POST. La URL ya está configurada para usar el nombre del conjunto de entidades accounts, por lo que no necesita cambiar nada más aquí. La URL debe ser:

   POST _.webapiurl accounts

5. En la pestaña Parámetros, puede eliminar todos los parámetros porque no se utilizan para la operación de creación.

6. En la pestaña Cuerpo, use el menú desplegable para seleccionar JSON desde el grupo TEXT:

   

7. Copie el siguiente JSON:

   {
      "name": "An Example Account record (sample)",
      "revenue": 10000.0,
      "address1_city": "Redmond"
   }
   

8. Pegue el JSON en el campo Cuerpo.

   Nota

   Antes de presionar Enviar para crear el registro, mire los datos en las pestañas Aut. y Encabezados. Como ha creado esta solicitud duplicando la solicitud Recuperar cuentas, toda la información que configuró previamente se reutiliza.

9. Pulse Enviar para crear el registro.

   Debería ver que el servicio devolvió 204 Sin contenido, por lo que no hay contenido para ver en el panel Vista previa.

   La URL del registro creado es visible en la lista Encabezados. Busque el encabezado de respuesta odata-entityid. El valor debería ser algo similar a esto:

   https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
   

   Esta URL contiene el valor del campo de clave principal para el registro creado, en este caso el valor de propiedad accountid.

Más información acerca de la creación de registros

Recupera un registro

Ahora que creó un registro de cuenta y conoce el valor del campo de clave principal, puede recuperarlo usando ese valor. Comience duplicando la solicitud Recuperar cuentas.

1. Duplique la solicitud Recuperar cuentas.

2. Asígnele el nombre Recuperar cuenta.

3. Edite la URL para agregar el valor accountid entre paréntesis después del nombre del conjunto de entidades. Si el accountid de la cuenta que creó en Crear un registro era 5b4ced1c-88e1-ee11-904c-6045bd05e9d4, edite la URL para que sea:

   GET _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

4. En la pestaña Parámetros, elimine los parámetros $top, $expand y $filter , dejando solo el parámetro $select para limitar el número de columnas devueltas.

5. En la pestaña Encabezados, seleccione la casilla de verificación junto al encabezado Prefer para desactivarlo y que no se devuelvan anotaciones.

6. Seleccione Enviar.

   La respuesta debería devolver 200 OK, y el panel Vista previa debería contener datos como los siguientes:

   {
      "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city)/$entity",
      "@odata.etag": "W/\"2343128\"",
      "name": "An Example Account record (sample)",
      "revenue": 10000.0000000000,
      "address1_city": "Redmond",
      "accountid": "5b4ced1c-88e1-ee11-904c-6045bd05e9d4",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond"
   }
   

Más información acerca de la recuperación de registros

Eliminar un registro

Ahora que ha creado y recuperado un registro utilizando el valor de la clave primaria, puede eliminarlo.

1. Duplique la solicitud Recuperar cuenta. Nombre la nueva solicitud Eliminar cuenta.

2. Cambie el método HTTP de GET a DELETE.

   La URL aún debe contener los datos con el accountid del registro que creó y recuperó antes:

   DELETE _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

3. En la pestaña Parámetros, elimine el parámetro $select porque no tiene sentido para una operación de eliminación.

4. Seleccione Enviar.

   Debería ver que el servicio devolvió 204 Sin contenido, por lo que no hay contenido para ver en el panel Vista previa.

5. Intente enviar la solicitud Recuperar cuenta ahora, devuelve 404 No encontrado y el panel Vista previa muestra este error:

   {
      "error": {
         "code": "0x80040217",
         "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
      }
   }
   

6. Vuelva a habilitar el encabezado Prefer para la solicitud Recuperar cuenta para que se devuelvan todas las anotaciones.

7. Envíe la solicitud nuevamente y ahora podrá ver que muchas anotaciones se devuelven con la respuesta 404 No encontrado:

   {
      "error": {
         "code": "0x80040217",
         "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionSourceKey": "Plugin/Microsoft.Crm.Common.ObjectModel.AccountService",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepKey": "81cbbb1b-ea3e-db11-86a7-000a3a5473e8",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiDepthKey": "1",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiActivityIdKey": "ef7da2d8-c3bc-40f3-b67f-9d2981341086",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiPluginSolutionNameKey": "System",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepSolutionNameKey": "System",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionCategory": "ClientError",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionMessageName": "ObjectDoesNotExist",
         "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionHttpStatusCode": "404",
         "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040217&client=platform",
         "@Microsoft.PowerApps.CDS.InnerError.Message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
      }
   }
   

   Estos detalles no son útiles en este contexto, porque el problema es obvio. Pero estos detalles podrían resultar útiles en otros escenarios. Obtenga más información sobre cómo incluir más detalles con errores

Más información acerca de la eliminación de registros

Pasos siguientes

Obtenga más información sobre lo que puede hacer con la API web de Dataverse: