Compartir a través de


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:

  1. Inicie sesión en Power Apps y luego seleccione su entorno en la esquina superior derecha.

  2. Seleccione el botón Configuración en la esquina superior derecha y , a continuación, seleccione Recursos de desarrollador.

    Menú de recursos para desarrolladores

    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: Resultados de la página
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 formateados
Microsoft.Dynamics.CRM.associatednavigationproperty
Microsoft.Dynamics.CRM.lookuplogicalname
Devuelve información sobre columnas de búsqueda relacionadas. Más información: Buscar datos de propiedades
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: Cuenta el 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. Obtenga información sobre las limitaciones de tamaño de la solicitud y la carga útil 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.

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 mediante 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).