Componer solicitudes HTTP y administrar errores

Artículo
09/26/2023

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 luego seleccione su 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 Extremo de la API web. Más información: Ver 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 al entorno. Si el nombre de su empresa es Contoso, entonces puede ser `contoso`.
Región	El entorno normalmente está en un centro de datos que tenga cercano geográficamente. Para Norteamérica es `crm`. Para América del Sur `crm2`, para Japón `crm7`. Para obtener la lista completa, consulte Regiones de centros de datos
URL base	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 entorno + Región + URL base + Ruta de la API Web + Versión + Recurso.

Longitud máxima de la dirección URL

La longitud máxima de la URL aceptada es de 32 KB (32768 caracteres). Esto debería ser adecuado para la mayoría de los tipos de solicitudes, excepto ciertas GET operaciones que requieren parámetros de consulta de cadenas muy largas, como consultas que utilizan 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.

Compatibilidad de versiones

Esta versión incorpora funciones que no están disponibles en las versiones anteriores. Las versiones secundarias posteriores pueden proporcionar más capacidades que no se agregarán retroactivamente a las versiones secundarias anteriores. El código redactado para v9.0 seguirá funcionando en futuras versiones cuando haga referencia a v9.0 en su dirección URL.

A medida que se lancen nuevas versiones, es posible que entren en conflicto con las versiones anteriores. Estos cambios importantes son necesarios para ir mejorando el servicio. La mayoría de las veces, las funciones permanecen igual entre las versiones, pero no debería suponer que lo harán.

Nota

A diferencia de las versiones v8.x de menor importancia, las nuevas funciones u otros cambios que se agreguen a las versiones futuras no se aplicarán a las versiones anteriores. Preste atención a la versión del servicio que usa y probar el código si cambia la versión utilizada.

Métodos HTTP

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

método	Uso
`GET`	Use para recuperar datos, incluida la llamada 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. Los errores devueltos en la respuesta se devolverán como JSON. Pese a que su código debería funcionar aunque este encabezado no esté incluido, se recomienda incluirlo como procedimiento recomendado

La versión de OData actual es la 4.0, pero las versiones futuras pueden permitir nuevas funciones. Para asegurarse de que no haya ambigüedades sobre la versión de OData que será aplicada al código del futuro, debe incluir siempre una instrucción explícito de la versión actual de OData y la versión máxima para aplicar en el código. Use los dos encabezados OData-Version y OData-MaxVersion establecidos en un valor de 4.0.

Las consultas que expanden propiedades de navegación valorada como colección pueden devolver datos en caché para las propiedades que no reflejan 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. Más información: 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

Puede usar el encabezado Preferir con los valores a continuación 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. Cuando esta preferencia se aplica a una solicitud de `POST`, una respuesta correcta tendrá el estado `201 Created`. Para una solicitud `PATCH`, una respuesta correcta tendrá un estado `200 OK.`. Sin esta preferencia aplicada, ambas operaciones devolverán el estado `204 No Content` para reflejar que no se devuelve ningún dato en el cuerpo de la respuesta de forma predeterminada. Más información: Crear con datos devueltos & 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 permite mantener los datos sincronizados de forma eficiente detectando qué datos se han modificado 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

Se pueden especificar varios encabezados Preferir utilizando 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:

Annotation	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: Datos de propiedades de búsqueda
`Microsoft.Dynamics.CRM.totalrecordcount` `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded`	Cuando utiliza la opción de consulta `$count`, la anotación `@odata.count` indica la cantidad de registros, pero solo se pueden devolver 5000 registros a la vez. Solicite `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded` para obtener un valor booleano que le indicará si el número total de registros que coinciden con la consulta supera los 5000. Más información: Recuento del número de filas
`Microsoft.Dynamics.CRM.globalmetadataversion`	Esta anotación se devuelve en la solicitud y puede almacenarla en caché en su aplicación. El valor cambia cuando se produce un cambio de esquema, lo que indica que es posible que deba actualizar cualquier dato de esquema que su aplicación haya almacenado en caché. Más información: Almacenar en caché datos de esquema
`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 con errores

Si solo desea anotaciones específicas, puede solicitarlas como valores separados por comas. También puede utilizar el carácter '*' como comodín. Por ejemplo, el siguiente encabezado de solicitud Prefer solo incluye los valores formateados y las anotaciones de detalles de errores adicionales:

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

Sugerencia

Es común usar simplemente el encabezado de solicitud Prefer: odata.include-annotations="*" para devolver todas las anotaciones.

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) AzureActiveDirectoryObjectId de la tabla/entidad de usuario (SystemUser). 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 para asegurarse de no sobrescribir los cambios que otra persona aplicó en el servidor desde que recuperó un registro. Más información: Aplicar la 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: Evitar realizar operaciones de 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: Evitar actualización en upsert e 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: Búsqueda de registros de duplicados
`MSCRM.BypassCustomPluginExecution`	`true`	Use este encabezado cuando desee omitir el código de complemento personalizado y la persona que llama tiene el privilegio `prvBypassCustomPlugins`. Más información: Omitir la lógica empresarial 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. Usar este encabezado incurre en una pequeña penalización de rendimiento, por lo que no debe usarse todo el tiempo.

Al ejecutar operaciones por lotes, deberá aplicar muchos encabezados en la solicitud y con 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	Type
`200 OK`	Espere este código de estado cuando la operación devuelva datos en el cuerpo de la respuesta.	Correcto
`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.	Correcto
`204 No Content`	Espere este código de estado cuando la operación sea correcta, pero no devuelva datos en el cuerpo de la respuesta.	Correcto
`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.	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. Esto se produce 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 se superan 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

Los detalles sobre los errores se incluyen como JSON en la respuesta en el siguiente formato.

{  
 "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 con los errores

Algunos errores pueden incluir más detalles mediante anotaciones. Cuando una solicitud incluye el encabezado Prefer: odata.include-annotations="*", la respuesta incluye todas las anotaciones que contienen más detalles sobre los errores y una URL que puede dirigirle a una guía específica para solucionar el error.

Algunos de estos detalles los pueden configurar los desarrolladores que escriben complementos. Por ejemplo, supongamos que tiene un complemento que arroja un error al usar el constructor InvalidPluginExecutionException(OperationStatus, Int32, String). Este constructor le permite pasar un valor OperationStatus, un código de error de 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;
            }
        }
    }
}

Cuando este complemento se registra en la creación de una entidad account, y la solicitud para crear una cuenta incluye la preferencia odata.include-annotations="*", la solicitud y la respuesta tienen el siguiente aspecto:

Solicitud:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.1/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 describen 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` Una URL que contiene información sobre el error que puede redirigirlo a una guía sobre cómo abordar 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 el seguimiento de pila del complemento porque el autor del complemento lo 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. La guía se puede proporcionar de forma proactiva, pero lo más común es que se proporcione de forma reactiva según la frecuencia con la que se utilice el vínculo. Utilice el vínculo. Si no proporciona orientación, su uso del vínculo nos ayuda a detectar que las personas necesitan más orientación sobre el error. Luego, podemos priorizar la inclusión de orientación sobre errores que más necesitan las personas. Los recursos a los que el vínculo puede dirigirlo pueden ser documentación, vínculos a recursos comunitarios o sitios externos.

Si no desea recibir todas las anotaciones en la respuesta, puede especificar qué anotaciones desea que se devuelvan. En lugar de usar Prefer: odata.include-annotations="*", puede usar el siguiente valor para recibir solo valores formateados para operaciones que recuperan datos y el vínculo de ayuda si ocurre 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 ExecutionContext en la colección SharedVariables. Más información:

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
Realizar operaciones condicionales mediante la API web

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Componer solicitudes HTTP y administrar errores

Dirección URL y versiones de API web

Longitud máxima de la dirección URL

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 con los errores

Agregar una variable compartida desde la API web

Consulte también

Comentarios

Recursos adicionales