Usar Insomnia con la API web de Dataverse

Puede usar muchas herramientas de cliente de API para autenticarse en entornos de Microsoft Dataverse y 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:

Muestre una estrategia para autenticarse y conectarse a Dataverse mediante el Insomnia API client con un identificador de aplicación de Microsoft Entra (cliente) proporcionado por Microsoft que está preaprobado para todos los entornos de Dataverse. Con esta estrategia, no es necesario registrar una aplicación para empezar a usar la API web de Dataverse.
Le presentaremos algunas operaciones de datos básicas que puede realizar mediante la API web de Dataverse en el contexto del cliente API de Insomnia. Con este enfoque, puede usar Insomnio para continuar experimentando y obtener información sobre la API web de Dataverse.

Nota

Las instrucciones de este artículo representan la experiencia proporcionada por Insomnia cuando se escribió este artículo. La experiencia del usuario probablemente cambie con el tiempo y es posible que este artículo no represente la experiencia actual. El artículo solo se actualiza cuando se producen cambios que interrumpen fundamentalmente los pasos descritos aquí. Obtenga más información en la documentación de Insomnio.

Privacidad

Las solicitudes que envíe mediante las herramientas de API de cliente contienen información que podría ser confidencial. Muchos desarrolladores no quieren cargar esta información en 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.

Otras opciones

También puede usar PowerShell con Visual Studio Code para autenticarse con Dataverse Web API como alternativa. Comienza a usar la API web con PowerShell y Visual Studio Code.

PowerShell con Visual Studio Code:

Utiliza el registro de la aplicación de Azure AD, por lo que no es necesario proporcionar un id. de aplicación (cliente).
No envía ninguna información sobre sus solicitudes a ninguna parte.
Es el punto de partida de una serie completa de ejemplos de API web que puede ejecutar.

Instalar Insomnia

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

Para Windows, el instalador es un archivo ejecutable que se descarga y ejecuta. Cuando finalice la instalación, es posible que pueda ver diferentes opciones. Estas opciones no deberían interferir con las instrucciones de este artículo, pero podrían cambiar. Cuando se escribió este artículo, el instalador presenta 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. Obtenga más información sobre Insomnia Scratch Pad.

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.

Asigne el entorno base a cada área de trabajo. Puede acceder a las variables dentro de ella en todo el área de trabajo.

Después de abrir Insomnia, seleccione el icono de engranaje 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.

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"
}

Pegue el JSON en el entorno base.
Edite el valor de la url propiedad y reemplace el https://yourorg.api.crm.dynamics.com valor para que coincida con la dirección URL del entorno de Dataverse.

Puede encontrar el punto de conexión de API web para su entorno mediante las instrucciones de Visualización de recursos para desarrolladores. Elimine /api/data/v9.2 de la URL punto de conexión de la API web. Esta URL debe terminar en dynamics.com.

Es posible que vea advertencias de que las referencias a las _.url variables y _.version no se resuelven inmediatamente, como la siguiente advertencia:

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

Creación de entornos secundarios (opcional)

Si solo necesita conectarse a un único entorno de Dataverse, use el entorno base. Si necesita conectarse a varios entornos, cree entornos secundarios para cada entorno de Dataverse. Por ejemplo, cree un sub-entorno para los entornos de desarrollo y prueba de Dataverse.

Tal como hizo con el entorno base, seleccione el icono de engranaje 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.
Seleccione el icono para crear un nuevo entorno. Los entornos pueden ser compartidos o privados. Elija Entorno privado.
Haga doble clic en el nombre del nuevo entorno que ha creado y cámbielo como desee. Puede asignarle el nombre del entorno de Dataverse al que quiere conectarse o algo parecido al entorno de desarrollo.

Copie el siguiente JSON:

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

Pegue el JSON en el entorno que ha creado.
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 tiene que incluir la url propiedad en el subentorno. Al seleccionar el sub-entorno, este valor invalida el url valor especificado en el entorno base. También puede incluir cualquiera de las cinco otras propiedades si lo desea, pero el valor de la url propiedad es el único que es diferente para cada entorno de Dataverse.

Configurar solicitudes

Después de configurar el entorno base y cualquier subconfiguración, está listo para configurar una solicitud.

Seleccione el botón Nueva solicitud HTTP o utilice el método abreviado de teclado Ctrl+N .
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:
Elija la variable _.webapiurl. El campo URL PREVIEW muestra el valor utilizando el valor de la propiedad para el url entorno seleccionado.
En la pestaña Aut., use el menú desplegable para seleccionar OAuth 2.0AUTH TYPE.

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

Campo	valor
TIPO DE CONCESIÓN	Implícito
URL DE AUTORIZACIÓN	`_.authurl`
ID. DE CLIENTE	`_.clientid`
URL DE REDIRECCIÓN	`_.redirecturl`

Seleccione Enviar.

Se abre un cuadro de diálogo para escribir las credenciales del entorno.

Después de escribir las credenciales, verá los resultados en el panel Vista previa que tiene un aspecto similar al siguiente:
```
{
"@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 autenticó correctamente en el 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. Haga referencia a él con frecuencia.

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

GET _.webapiurl$metadata?annotations=true
Seleccione Enviar.

En el panel Vista previa, verá un mensaje que indica Respuesta de más de 5 MB se ha ocultado para mejorar el rendimiento, con las opciones Guardar en un archivo y Mostrar igualmente. El archivo es grande, pero puede obtener una vista previa sin problemas.

Buscar definiciones de tipos

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

Find	Consulta XPath
Todos los tipos de entidades	`//*[local-name() = 'EntityType']`
EntityType de cuenta	`//*[local-name() = 'EntityType'][@Name = 'account']`
Todas las funciones	`//*[local-name() = 'Function']`
La función WhoAmI	`//*[local-name() = 'Function'][@Name = 'WhoAmI']`
Todas las acciones	`//*[local-name() = 'Action']`
La acción CreateMultiple	`//*[local-name() = 'Action'][@Name = 'CreateMultiple']`
Tipos los tipos complejos	`//*[local-name() = 'ComplexType']`
El tipo complejo WhoAmIResponse	`//*[local-name() = 'ComplexType'][@Name = 'WhoAmIResponse']`
Todos los tipos de enumeración	`//*[local-name() = 'EnumType']`
El tipo de enumeración AccessRights	`//*[local-name() = 'EnumType'][@Name = 'AccessRights']`

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

Enviar una solicitud WhoAmI

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

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

GET _.webapiurl WhoAmI
Establezca encabezados de solicitud.

Como se describe en encabezados HTTP, cada solicitud de API web debe tener un conjunto específico de encabezados de solicitud. Es posible que tenga que modificar los valores de encabezado para distintos 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.

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

Seleccione Enviar.

En el panel Vista previa , 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": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
   "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
   "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

Recuperar datos

Para usar Insomnio para recuperar registros, establezca el nombre del conjunto de entidades para el recurso.

Cambie la dirección URL para quitarla WhoAmI después de la _.webapiurl variable. Reemplácelo por accounts, el nombre del conjunto de entidades para el tipo de entidad de cuenta. La URL debe ser:

GET _.webapiurl accounts
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 primeros registros de cuenta ubicados en la ciudad de Redmond. También incluye información sobre cualquier contacto relacionado especificado como contacto principal para las cuentas.
1. Pegue los valores en el campo QUERY PARAMETERS.
  
  La consulta debe tener este aspecto:

Seleccione Enviar.

En el panel Vista previa , verá 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. Obtenga información sobre cómo solicitar anotaciones específicas.

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

Creación de un registro

Mediante el uso de Insomnio, puede definir varias solicitudes que puede reutilizar. Una manera sencilla de crear una nueva solicitud que mantenga cualquier configuración que tenga es duplicar una solicitud existente. En este paso, duplique la solicitud definida en la sección Recuperar datos y cree una nueva solicitud para crear un registro.

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.
Cuando pasa el cursor sobre la solicitud Recuperar cuentas, seleccione el menú desplegable y seleccione Duplicar.
En el cuadro de diálogo Duplicar solicitud, establezca Nuevo nombre en Crear cuenta.
En la nueva solicitud Crear cuenta, cambie el método HTTP de GET a POST. La dirección URL ya está establecida para usar el nombre del accounts conjunto de entidades, por lo que no es necesario cambiar nada más aquí. La URL debe ser:

POST _.webapiurl accounts
En la pestaña Parámetros , elimine todos los parámetros porque no se usan para la operación de creación.
En la pestaña Cuerpo, use el menú desplegable para seleccionar JSON desde el grupo TEXT:

Copie el siguiente JSON:

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

Pegue el JSON en el campo Cuerpo.

Nota

Antes de seleccionar Enviar para crear el registro, examine los datos en las pestañas Autenticación y Encabezados . Dado que creó esta solicitud duplicando la solicitud Recuperar cuentas , vuelve a usar toda la información que configuró anteriormente.
Seleccione Enviar para crear el registro.

Verá que el servicio devolvió 204 Sin contenido, por lo que no hay contenido que 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

Después de crear un registro de cuenta y obtener el valor del campo de clave principal, use ese valor para recuperar el registro. Comience duplicando la solicitud Recuperar cuentas.

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

GET _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
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.
En la pestaña Encabezados, seleccione la casilla de verificación junto al encabezado Prefer para desactivarlo y que no se devuelvan anotaciones.

Seleccione Enviar.

La respuesta devuelve 200 OK y el panel Vista previa contiene 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

Después de crear y recuperar un registro mediante el valor de clave principal, puede eliminarlo.

Duplique la solicitud Recuperar cuenta. Nombre la nueva solicitud Eliminar cuenta.
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)
En la pestaña Parámetros, elimine el parámetro $select porque no tiene sentido para una operación de eliminación.
Seleccione Enviar.

Verá que el servicio devolvió 204 Sin contenido, por lo que no hay contenido que ver en el panel Vista previa .

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"
   }
}

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

Vuelva a enviar la solicitud. Ahora puede ver que se devuelven muchas anotaciones 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.

Obtenga más información sobre cómo eliminar registros.

Pasos siguientes

Para más información sobre lo que puede hacer con dataverse Web API, consulte los siguientes artículos:

Más información acerca de los tipos y operaciones de la API web

Realizar operaciones mediante la API web

Oharrak

Lagungarria al da orri hau?

Last updated on 2026-03-14

Partekatu honen bidez:

Usar Insomnia con la API web de Dataverse

Privacidad

Otras opciones

Instalar Insomnia

Configurar el entorno base

Creación de entornos secundarios (opcional)

Configurar solicitudes

Ver el documento CSDL $metadata

Buscar definiciones de tipos

Enviar una solicitud WhoAmI

Recuperar datos

Creación de un registro

Recupera un registro

Eliminar un registro

Pasos siguientes

Oharrak

Baliabide gehigarriak