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.

   

   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:

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.

Métodos HTTP

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

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.

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:

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

Otros encabezados

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.

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.

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:

• Agregar una variable compartida al contexto de ejecución del complemento
• Variables compartidas

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