Componer solicitudes HTTP y administrar errores

La interacción con la API web se realiza creando y enviando solicitudes HTTP. Debe saber cómo establecer los encabezados HTTP apropiados y administrar los errores incluidos en la respuesta.

Dirección URL y versiones de API web

Para buscar el URL de la API Web para su entorno:

Inicie sesión en Power Apps y seleccione el entorno en la esquina superior derecha.
Seleccione el botón Configuración en la esquina superior derecha y , a continuación, seleccione Recursos de desarrollador.

Desde aquí, puede copiar el valor para el punto final de la API web. Para obtener más información, consulte Visualización de recursos para desarrolladores.

En la siguiente tabla se describen las partes del URL:

Parte	Descripción
Protocolo	`https://`
Nombre del entorno	El nombre único que se aplica a su entorno. Si el nombre de la empresa es Contoso, puede ser `contoso`.
Región	El entorno normalmente está en un centro de datos que esté cerca de usted geográficamente. Para Norteamérica es `crm`. Para Sudamérica `crm2`. Para Japón `crm7`. Para obtener la lista completa, consulte Regiones del centro de datos.
URL base	Este valor suele ser `dynamics.com.`, pero algunos centros de datos usan valores diferentes. Consulte Regiones de centros de datos.
Ruta de la API web	La ruta a la API web es `/api/data/`.
Versión	La versión se expresa de esta manera: `v[Major_version].[Minor_version][PatchVersion]/`. La versión actual es `v9.2`.
Recurso	El `EntitySetName` de la tabla o el nombre de función o la acción que desea usar.

La URL que utiliza se compone de estas partes:

Protocolo + Nombre + del entornoRegión + Dirección URL + baseRuta de acceso de + API webVersión + Recurso.

Longitud máxima de la dirección URL

La longitud máxima de la dirección URL aceptada por es de 32 KB (32 768 caracteres). Esta longitud es adecuada para la mayoría de los tipos de solicitudes, excepto ciertas GET operaciones que requieren parámetros de consulta de cadena muy largos, como las consultas que usan FetchXml. Si envía solicitudes dentro del cuerpo de una solicitud $batch, puede enviar solicitudes con URL de hasta 64 KB (65 536 caracteres). Obtenga más información sobre cómo enviar FetchXml dentro de una solicitud $batch.

Longitud máxima del segmento OData

La longitud máxima de cualquier segmento individual en una solicitud de OData es de 260 caracteres. Si un único segmento de la solicitud OData tiene más de 260 caracteres de longitud, la solicitud devuelve 400 Bad Request - Invalid URL. El segmento es la parte "Recurso" de la dirección URL e incluye todos los caracteres necesarios para describir el punto de conexión y los parámetros insertados.

Por ejemplo, si la solicitud es api/data/v9.2/MyApi(MyParameter='longvalue'), MyApi(MyParameter='longvalue') es el segmento que no puede superar los 260 caracteres. Use siempre alias de parámetros con funciones de OData. Por ejemplo, componer su función como /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' acorta el segmento a solo MyApi(MyParameter=@alias). Obtenga más información sobre el uso de alias de parámetros con funciones de API web.

Compatibilidad de versiones

Esta versión presenta funcionalidades que las versiones anteriores no admiten. Las versiones secundarias posteriores pueden proporcionar más funcionalidades que las versiones secundarias anteriores no admiten. El código escrito para v9.0 sigue funcionando en versiones futuras al hacer referencia a v9.0 en la dirección URL.

A medida que se introducen nuevas funcionalidades, podrían entrar en conflicto con versiones anteriores. Estos cambios importantes son necesarios para mejorar el servicio. La mayoría de las veces, las funcionalidades son las mismas entre versiones, pero no asuma que lo son.

Nota

A diferencia de las versiones secundarias v8.x, las versiones futuras no aplican nuevas funcionalidades ni otros cambios a versiones anteriores. Preste atención a la versión del servicio que usa y pruebe su código si cambia la versión empleada.

Métodos HTTP

La siguiente tabla enumera los métodos HTTP que puede usar con la API web de Dataverse.

método	Uso
`GET`	Utilice al recuperar datos, incluidas las llamadas a funciones. El código de estado esperado para una recuperación correcta es `200 OK`.
`POST`	Use para crear entidades o llamar a acciones.
`PATCH`	Use para actualizar entidades o realizar operaciones de upsert.
`DELETE`	Use para eliminar entidades o propiedades individuales de entidades.
`PUT`	Use en situaciones limitadas para actualizar propiedades individuales de entidades. Este método no se recomienda para actualizar la mayoría de las entidades. Use `PUT` para actualizar definiciones de tabla. Más información: Usar la API web con definiciones de tabla

Encabezados HTTP

Todas las solicitudes HTTP deben incluir al menos los siguientes encabezados.

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Aunque el protocolo OData permite los formatos JSON y ATOM, la API web solo admite JSON. Cada solicitud debe incluir el valor del encabezado Accept de application/json, aunque no se espere ningún cuerpo de la respuesta. La API web devuelve cualquier error en la respuesta como JSON. Aunque el código debe funcionar incluso si no se incluye este encabezado, incluyéelo como procedimiento recomendado.

La versión actual de OData es la 4.0, pero las versiones futuras podrían introducir nuevas funcionalidades. Para asegurarse de que no hay ambigüedad sobre la versión de OData que se aplica al código, incluya siempre una instrucción explícita de la versión actual de OData y la versión máxima. Use los dos encabezados OData-Version y OData-MaxVersion establecidos en un valor de 4.0.

Las consultas que expanden las propiedades de navegación con valores de colección podrían devolver datos almacenados en caché para esas propiedades que no reflejan los cambios recientes. Incluya el encabezado If-None-Match: null en el cuerpo de la solicitud para reemplazar la memoria caché del explorador de la solicitud de la API web. Para obtener más información, vea Protocolo de transferencia de hipertexto (HTTP/1.1): Solicitudes condicionales 3.2 : If-None-Match.

Cada solicitud que incluya datos de JSON en el cuerpo de la solicitud debe incluir un encabezado Content-Type con un valor de application/json.

Content-Type: application/json

Puede usar otros encabezados para habilitar funcionalidades específicas.

Preferir encabezados

Use el encabezado Prefer con los siguientes valores para especificar preferencias.

Valor preferido	Descripción
`return=representation`	Utilice esta preferencia para devolver datos al crear operaciones (`POST`) o actualizar operaciones (`PATCH`) para entidades. Al aplicar esta preferencia a una `POST` solicitud, una respuesta correcta tiene el estado `201 Created` . Para una `PATCH` solicitud, una respuesta correcta tiene un estado `200 OK.` Sin esta preferencia, ambas operaciones devuelven el estado `204 No Content` para reflejar que el cuerpo de la respuesta no contiene datos. Más información: Crear con datos devueltos y Actualizar con datos devueltos
`odata.include-annotations`	Ver Solicitar anotaciones
`odata.maxpagesize`	Utilice esta preferencia para especificar cuántas páginas desea devolver en una consulta. Más información: Página de resultados
`odata.track-changes`	La característica de seguimiento de cambios mantiene los datos sincronizados de forma eficaz mediante la detección de los datos que han cambiado desde que los datos se extrajeron inicialmente o se sincronizaron por última vez. Más información: Uso del seguimiento de cambios para sincronizar los datos con sistemas externos
`respond-async`	Específica que la solicitud debe procesarse de forma asincrónica. Más información: Operaciones en segundo plano (versión preliminar)

Nota

Puede especificar varios Prefer encabezados mediante valores separados por comas. Por ejemplo: Prefer: respond-async,odata.include-annotations="*"

Solicitar anotaciones

Puede solicitar que se devuelvan diferentes datos de anotación de OData con los resultados mediante el encabezado de solicitud Prefer: odata.include-annotations. Puede optar por devolver todas las anotaciones o especificar anotaciones específicas. La siguiente tabla describe las anotaciones que admite la web API de Dataverse:

Anotación	Descripción
`OData.Community.Display.V1.FormattedValue`	Devuelve valores de cadena formateados que puede usar en su aplicación. Más información: Valores con formato
`Microsoft.Dynamics.CRM.associatednavigationproperty` `Microsoft.Dynamics.CRM.lookuplogicalname`	Devuelve información sobre columnas de búsqueda relacionadas. Más información: Búsqueda de datos de propiedades y búsquedas de varias tablas
`Microsoft.Dynamics.CRM.totalrecordcount` `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded`	Cuando se usa la `$count` opción de consulta, la `@odata.count` anotación indica el número de registros, pero solo se pueden devolver 5000 registros de tabla estándar a la vez. En el caso de las tablas elásticas, el límite de tamaño de página es 500. Solicite la `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded` anotación para obtener un valor booleano que indica si el número total de registros que coinciden con la consulta supera el límite máximo de tamaño de página para el tipo de tabla que está usando. Más información: Recuento del número de filas
`Microsoft.Dynamics.CRM.globalmetadataversion`	Puede almacenar en caché esta anotación en la aplicación. El valor cambia cuando se produce cualquier cambio de esquema, lo que indica que es posible que tenga que actualizar los datos de esquema almacenados en caché de la aplicación. Más información: Datos del esquema de caché
`Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` `Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` `Microsoft.PowerApps.CDS.HelpLink` `Microsoft.PowerApps.CDS.TraceText` `Microsoft.PowerApps.CDS.InnerError.Message`	Estas anotaciones proporcionan más detalles cuando se devuelven errores. Más información: Incluir más detalles sobre los errores

Para solicitar anotaciones específicas, incluyéndolas como valores separados por comas. También puede utilizar el carácter '*' como comodín. Por ejemplo, el siguiente Prefer encabezado de solicitud incluye solo los valores formateados y las anotaciones adicionales de detalles de error.

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

Propina

Para devolver todas las anotaciones, use el encabezado de solicitud Prefer: odata.include-annotations="*".

Otros encabezados

Encabezado	valor	Descripción
`CallerObjectId`	Id. de objeto de usuario Microsoft Entra ID	Utilice este encabezado para suplantar a otro usuario cuando la persona que llama tenga los privilegios para hacerlo. Establezca el valor del identificador de objeto de Microsoft Entra ID del usuario a suplantar. Estos datos están en el atributo (columna) Tabla/entidad de usuario (SystemUser) AzureActiveDirectoryObjectId. Más información: Suplantar a otro usuario utilizando la API web.
`If-Match`	Valor de `Etag` o `*`	Utilice este encabezado para aplicar simultaneidad optimista y asegurarse de no sobrescribir los cambios que otra persona haya hecho en el servidor desde que usted recuperó un registro. Más información: Aplicar simultaneidad optimista e If-Match. También puede utilizar este encabezado con `*` para prevenir que una operación `PATCH` cree un registro. Más información: Impedir la creación en upsert.
`If-None-Match`	`null` o `*`	Este encabezado debe usarse en todas las solicitudes con un valor de `null` como se describe en Encabezados HTTP, pero también se puede utilizar para prevenir que una operación `POST` realice una actualización. Más información: Impedir la actualización en upsert y If-None-Match.
`MSCRM.SolutionUniqueName`	nombre único de la solución	Utilice este encabezado cuando desee crear un componente de solución y asociarlo con una solución no administrada. Más información: Crear y actualizar definiciones de tabla mediante la API web.
`MSCRM.SuppressDuplicateDetection`	`false`	Use este encabezado con el valor `false` para habilitar detección de duplicados al crear o actualizar un registro. Más información: Compruebe si hay registros duplicados.
`MSCRM.BypassCustomPluginExecution`	`true`	Use este encabezado cuando desee omitir el código de complemento personalizado y el autor de la llamada tiene el `prvBypassCustomPlugins` privilegio. Más información: Omitir lógica de negocios personalizada.
`Consistency`	`Strong`	Utilice este encabezado cuando deba tener la versión más reciente de un elemento almacenado en caché. Los elementos almacenados en caché incluyen: definiciones de metadatos, etiquetas, permisos de usuario y permisos de equipo. Por ejemplo, si aplica un cambio a alguna definición, etiqueta o permiso de metadatos y tiene un código que debe usar la última definición dentro de los 30 segundos posteriores al cambio, puede usar este encabezado para asegurarse de obtener la última versión. El uso de este encabezado conlleva una pequeña penalización de rendimiento, por lo que no la use todo el tiempo.

Al ejecutar operaciones por lotes, es necesario aplicar muchos encabezados diferentes en la solicitud y en cada parte enviada en el cuerpo. Más información:Ejecute las operaciones por lotes mediante API web

Identificar códigos de estado

Tanto si la solicitud HTTP es correcta como si no, la respuesta incluye un código de estado. La siguiente tabla describe los códigos de estado devueltos por la API web de Microsoft Dataverse.

Código	Descripción	Tipo
`200 OK`	Espere este código de estado cuando la operación devuelva datos en el cuerpo de la respuesta.	Éxito
`201 Created`	Cuente con este código de estado cuando la operación POST de la entidad se realice correctamente y haya especificado la preferencia `return=representation` en su solicitud.	Éxito
`204 No Content`	Espere este código de estado cuando su operación sea exitosa, pero no devuelva datos en el cuerpo de la respuesta.	Éxito
`304 Not Modified`	Espere este código de estado al comprobar si se ha modificado una entidad desde la última vez que se recuperó. Más información:Recuperaciones condicionales.	Redirección
`403 Forbidden`	Espere este código de estado para los siguientes tipos de errores: - `AccessDenied` - `AttributePermissionReadIsMissing` - `AttributePermissionUpdateIsMissingDuringUpdate` - `AttributePrivilegeCreateIsMissing` - `CannotActOnBehalfOfAnotherUser` - `CannotAddOrActonBehalfAnotherUserPrivilege` - `CrmSecurityError` - `InvalidAccessRights` - `PrincipalPrivilegeDenied` - `PrivilegeCreateIsDisabledForOrganization` - `PrivilegeDenied` - `unManagedinvalidprincipal` - `unManagedinvalidprivilegeedepth`	Error de cliente
`401 Unauthorized`	Espere este código de estado para los siguientes tipos de errores: - `BadAuthTicket` - `ExpiredAuthTicket` - `InsufficientAuthTicket` - `InvalidAuthTicket` - `InvalidUserAuth` - `MissingCrmAuthenticationToken` - `MissingCrmAuthenticationTokenOrganizationName` - `RequestIsNotAuthenticated` - `TamperedAuthTicket` - `UnauthorizedAccess` - `UnManagedInvalidSecurityPrincipal`	Error de cliente
`413 Payload Too Large`	Espere este código de estado cuando la longitud de la solicitud sea demasiado grande. Más información sobre las limitaciones de tamaño de la carga útil de solicitud y respuesta	Error de cliente
`400 BadRequest`	Espere este código de estado cuando un argumento no sea válido.	Error de cliente
`404 Not Found`	Espere este código de estado cuando no exista el recurso.	Error de cliente
`405 Method Not Allowed`	Este error se produce porque el método y las combinaciones de recursos no son correctas. Por ejemplo, no puede utilizar DELETE o PATCH en una colección de entidades. Espere esto para los siguientes tipos de errores: - `CannotDeleteDueToAssociation` - `InvalidOperation` - `NotSupported`	Error de cliente
`412 Precondition Failed`	Espere este código de estado para los siguientes tipos de errores: - `ConcurrencyVersionMismatch` - `DuplicateRecord`	Error de cliente
`429 Too Many Requests`	Espere este código de estado cuando se superen los límites de la API. Más información: Límites de API de protección de servicios	Error de cliente
`501 Not Implemented`	Espere este código de estado cuando alguna operación solicitada no se implementa.	Error de servidor
`503 Service Unavailable`	Espere este código de estado cuando el servicio de la API web no está disponible.	Error de servidor

Errores de análisis de la respuesta

La respuesta incluye detalles sobre los errores como JSON en el formato siguiente.

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}

Incluir más detalles sobre los errores

Algunos errores incluyen más detalles a través de anotaciones. Cuando una solicitud incluye el Prefer: odata.include-annotations="*" encabezado, la respuesta incluye todas las anotaciones que contienen más detalles sobre los errores y una dirección URL que puede dirigirle a instrucciones específicas para el error.

Los desarrolladores que escriben complementos pueden establecer algunos de estos detalles. Por ejemplo, supongamos que tiene un complemento que produce un error mediante el constructor InvalidPluginExecutionException(OperationStatus, Int32, String). Este constructor acepta un OperationStatus valor, un código de error entero personalizado y un mensaje de error.

Un complemento sencillo podría tener este aspecto:

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

Al registrar este complemento en el mensaje Crear de una entidad de cuenta y la solicitud para crear una cuenta incluye la odata.include-annotations="*" preferencia, la solicitud y la respuesta tienen un aspecto similar al del ejemplo siguiente:

Solicitud:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

Respuesta:

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

En la tabla siguiente se describe la anotación en la respuesta.

Anotación y descripción	valor
`@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` El valor de OperationStatus establecido por el constructor InvalidPluginExecutionException(OperationStatus, Int32, String).	`1`
`@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` El valor de `SubErrorCode` establecido por el constructor InvalidPluginExecutionException(OperationStatus, Int32, String).	`12345`
`@Microsoft.PowerApps.CDS.HelpLink` Dirección URL que contiene información sobre el error y puede redirigirle a instrucciones sobre cómo solucionar el error.	`http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform`
`@Microsoft.PowerApps.CDS.TraceText` Contenido escrito en el registro de seguimiento del complemento mediante el método ITracingService.Trace(String, Object[]). Esta anotación incluye la traza de pila del complemento porque el autor del complemento la registró.	`[MyNamespace: MyNamespace.MyClass ]` `[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass :Create of account]` `Entering MyClass plug-in.` `StackTrace:` `at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)`
`@Microsoft.PowerApps.CDS.InnerError.Message` El mensaje de error encontrado en InnerError para la excepción. Este mensaje debe ser el mismo que el mensaje de error, excepto en ciertos casos especiales que son solo para uso interno.	`Example Error Message.`

Nota

No se garantiza que el @Microsoft.PowerApps.CDS.HelpLink proporcione una guía para cada error. Las instrucciones se pueden proporcionar de forma proactiva, pero normalmente se proporcionan de forma reactiva en función de la frecuencia con la que se usa el vínculo. Utilice el vínculo. Si no proporciona instrucciones, el uso del vínculo ayuda al equipo del producto a realizar un seguimiento de que las personas necesitan más instrucciones sobre el error. A continuación, el equipo puede priorizar las instrucciones con orientación sobre los errores que las personas más necesitan. Los recursos a los que el vínculo puede dirigirle pueden ser documentación, vínculos a recursos de la comunidad o sitios externos.

Si no desea recibir todas las anotaciones de la respuesta, puede especificar qué anotaciones desea devolver. En lugar de usar Prefer: odata.include-annotations="*", use el siguiente valor para recibir solo valores con formato para las operaciones que recuperan datos y el vínculo de ayuda si se produce un error: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink".

Más información: Anotaciones de la solicitud

Agregar una variable compartida desde la API web

Puede establecer un valor de cadena que esté disponible para los complementos dentro de la colección ExecutionContextSharedVariables. Para obtener más información, consulte:

Consulte también

Realizar operaciones mediante la API web
Consultar datos utilizando la API web
Crear una fila de tabla usando la API web
Recuperar una fila de tabla usando la API web
Actualizar y eliminar filas de tablas usando la API web
Asociar y anular la asociación de filas de tabla mediante la API web
Usar funciones de la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realice operaciones condicionales mediante la API web.

Comentarios

Resultoulle útil esta páxina?

Last updated on 2026-03-11

Compartir por

Componer solicitudes HTTP y administrar errores

Dirección URL y versiones de API web

Longitud máxima de la dirección URL

Longitud máxima del segmento OData

Compatibilidad de versiones

Métodos HTTP

Encabezados HTTP

Preferir encabezados

Solicitar anotaciones

Otros encabezados

Identificar códigos de estado

Errores de análisis de la respuesta

Incluir más detalles sobre los errores

Agregar una variable compartida desde la API web

Consulte también

Comentarios

Recursos adicionais