Componer solicitudes HTTP y administrar errores

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

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 acceder a la API web, debe crear una dirección URL con los componentes de la tabla siguiente.

Parte Descripción
Protocolo https://
Nombre de 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 estará disponible en un centro de datos que tenga cercano geográficamente.
Norteamérica: crm
Sudamérica: crm2
Canadá: crm3
Europa, Oriente Medio y África (EMEA): crm4
Área Asia Pacífico (APAC): crm5
Oceanía: crm6
Japón: crm7
India: crm8
Norteamérica 2: crm9
Reino Unido: crm11
Francia: crm12
Más valores se agregarán a lo largo del tiempo a medida que se abran nuevas regiones del centro de datos.
URL base dynamics.com.
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 válida para esta publicación es v9.1.
Recurso El nombre, la función o la acción de entidad (tabla) que desea usar.

La dirección URL que use se conformará con estas partes: protocolo + Nombre de entorno + región + dirección URL base + ruta de la API web + versión + recurso. Puede encontrar estos valores mencionados en la tabla anterior yendo con su navegador al portal de Power Apps, seleccione el icono de configuración (engranaje) en la barra de herramientas superior y elija Recursos de desarrollador en el menú.

Compatibilidad de versiones

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

A medida que se lancen nuevas versiones, es posible que entren en conflicto con las versiones anteriores. Esto es necesario 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. Deberá prestar atención a la versión del servicio que usa y probar el código si cambia la versión utilizada.

Métodos HTTP

Las solicitudes HTTP pueden aplicar una variedad de métodos diferentes. Cuando use la API web, utilizará únicamente los métodos descritos en la tabla siguiente.

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. Lo utilizará para actualizar definiciones de tabla.

Encabezados HTTP

Aunque el protocolo OData permite los formatos JSON y ATOM, la API web solo admite JSON. Por tanto, se pueden aplicar los siguientes encabezados.

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 en ese momento 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. Para obtener más información, consulte Protocolo de transferencia de hipertexto (HTTP/1.1): Solicitudes condicionales 3.2: If-None-Match.

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

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 encabezados adicionales para habilitar funcionalidades específicas.

  • Para devolver datos al crear operaciones (POST) o actualizar operaciones (PATCH) para entidades, incluya la preferencia return=representation. Cuando esta preferencia se aplica a una solicitud de POST, una respuesta correcta tendrá el estado 201 (Creados). Para una solicitud PATCH, una respuesta correcta tendrá un estado 200 (OK). Sin esta preferencia aplicada, ambas operaciones devolverán el estado 204 (sin contenido) para reflejar que no se devuelve ningún dato en el cuerpo de la respuesta de forma predeterminada.

  • Para devolver valores formateados con una consulta, incluya la preferencia odata.include-annotations establecida como Microsoft.Dynamics.CRM.formattedvalue mediante el encabezado Preferencia. Más información:Incluir valores con formato.

  • También puede usar el encabezado Prefer con la opción odata.maxpagesize para especificar el número de páginas desea devolver. Más información: Especifique el número de tablas (entidades) para devolver a una página

  • Para suplantar a otro usuario cuando el autor de la llamada tiene privilegios para ello, agregue el encabezado CallerObjectId con el valor de Id. de objeto de usuario de Azure Active Directory del usuario a suplantar. Estos datos están en el atributo (columna) AzureActiveDirectoryObjectId de la tabla/entidad SystemUser. Más información:Suplantar a otro usuario utilizando la API web.

  • Para aplicar simultaneidad optimista, puede aplicar el encabezado If-Match con un valor Etag. Más información:Aplicar simultaneidad optimista.

  • Para controlar si una operación de upsert debe crear o actualizar realmente una entidad, también puede usar los encabezados If-Match y If-None-Match. Más información: Aplicar una tabla (entidad).

  • Al ejecutar operaciones por lotes, deberá aplicar distintos encabezados en la solicitud y con cada parte enviada en el cuerpo. Más información:Ejecute las operaciones por lotes mediante API web

  • Cuando crea un componente de solución y desea asociarlo con una solución, utilice el encabezado de solicitud MSCRM.SolutionUniqueName y establezca el valor en el nombre único de la solución.

  • Cuando desee habilitar la detección de duplicados al crear un nuevo registro de entidad, establezca el valor del encabezado de la solicitud MSCRM.SuppressDuplicateDetection en falso. Más información: Búsqueda de registros de duplicados

  • Cuando desea omitir el código de complemento personalizado y la persona que llama tiene el privilegio prvBypassCustomPlugins, establezca la solicitud de encabezado MSCRM.BypassCustomPluginExecution a true. Más información: Omitir la lógica empresarial personalizada

Identificar códigos de estado

Tanto si la solicitud http es correcta como si no, la respuesta incluirá un código de estado. Los códigos de estado devueltos por la API web de Microsoft Dataverse incluyen lo siguiente.

Código Descripción Escriba
200 OK Esto se produce cuando la operación devuelva datos en el cuerpo de la respuesta. Correcto
201 Creados Cuente con esto cuando la operación POST de la entidad se realice correctamente y haya especificado la preferencia return=representation en su solicitud. Correcto
204 Sin contenido Esto se produce cuando la operación sea correcta pero no devuelva datos en el cuerpo de la respuesta. Correcto
304 Sin modificar Esto se produce al comprobar si se ha modificado una entidad desde la última vez que se recuperó. Más información:Recuperaciones condicionales. Redirección
403 Prohibido Esto se produce para los siguientes tipos de errores:

- AccessDenied
- AttributePermissionReadIsMissing
- AttributePermissionUpdateIsMissingDuringUpdate
- AttributePrivilegeCreateIsMissing
- CannotActOnBehalfOfAnotherUser
- CannotAddOrActonBehalfAnotherUserPrivilege
- CrmSecurityError
- InvalidAccessRights
- PrincipalPrivilegeDenied
- PrivilegeCreateIsDisabledForOrganization
- PrivilegeDenied
- unManagedinvalidprincipal
- unManagedinvalidprivilegeedepth
Error de cliente
401 No autorizado Esto se produce para los siguientes tipos de errores:

- BadAuthTicket
- ExpiredAuthTicket
- InsufficientAuthTicket
- InvalidAuthTicket
- InvalidUserAuth
- MissingCrmAuthenticationToken
- MissingCrmAuthenticationTokenOrganizationName
- RequestIsNotAuthenticated
- TamperedAuthTicket
- UnauthorizedAccess
- UnManagedInvalidSecurityPrincipal
Error de cliente
413 La carga es demasiado grande Espero esto cuando la solicitud sea demasiado larga. Error de cliente
400 BadRequest Esto se produce cuando un argumento no sea válido. Error de cliente
404 No encontrado Esto se produce cuando no exista el recurso. Error de cliente
405 Método no permitido 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 Error de condición previa Esto se produce para los siguientes tipos de errores:

- ConcurrencyVersionMismatch
- DuplicateRecord
Error de cliente
429 Demasiadas solicitudes Espere esto cuando 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 No implementado Esto se produce cuando alguna operación solicitada no se implementa. Error de servidor
503 Servicio no disponible Esto se produce cuando el servicio de la API web no está disponible. Error de servidor

Errores de análisis de la respuesta

Los detalles sobre errores se incluyen como JSON en la respuesta. Los errores tendrán este formato.

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

Importante

La estructura de los mensajes de error está cambiando. Se espera que este cambio se implemente en diferentes regiones en el período de agosto hasta octubre de 2020.

Antes de este cambio, los errores devueltos estaban en este formato:

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>",  
  "innererror": {  
   "message": "<A message describing the error, this is frequently the same as the outer message>",  
   "type": "Microsoft.Crm.CrmHttpException",  
   "stacktrace": "<Details from the server about where the error occurred>"  
  }  
 }  
}  

Estamos eliminando la propiedad innererror del mensaje de error. Debe eliminar cualquier código que espere analizar esta propiedad.

El OData Guía de respuesta a errores afirma "El par nombre / valor de error interno DEBERÍA utilizarse solo en entornos de desarrollo para evitar posibles problemas de seguridad relacionados con la divulgación de información.". Para alinearnos con esta guía, estamos eliminando esta propiedad.

Si descubre que una aplicación que usa depende de esta propiedad después de implementar este cambio, puede ponerse en contacto con el soporte y solicitar que el cambio se elimine temporalmente para su entorno. Esto proporcionará tiempo para que el desarrollador de la aplicación realice los cambios apropiados para eliminar esta dependencia.

Incluir detalles adicionales con errores

Algunos errores pueden incluir detalles adicionales mediante anotaciones. Cuando una solicitud incluye el encabezado Prefer: odata.include-annotations="*", la respuesta incluirá todas las anotaciones que incluirán detalles adicionales sobre los errores y una URL que se puede usar para ir a cualquier 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). Esto 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 tendrán 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"
}

Response

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

Esta respuesta incluye las siguientes anotaciones:

Anotación y descripción Value
@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 ITracingService.Trace(String, Object[]) Method. Esto 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. 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 específicas desea que se devuelvan. En lugar de usar Prefer: odata.include-annotations="*", puede usar lo siguiente 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".

Agregar una variable compartida desde la API web

Puede establecer un valor de cadena que estará disponible para los complementos dentro de ExecutionContext en la colección SharedVariables. Más información: Variables compartidas

Para pasar este valor usando la API web, simplemente use la opción de consulta tag.

Por ejemplo: ?tag=This is a value passed.

Dará como resultado el siguiente valor dentro de la colección SharedVariables cuando se envía mediante un webhook.

{
"key": "tag",
"value": "This is a value passed."
}

Esto también se puede hacer utilizando el Servicio de organización: Agregar una variable compartida del servicio de organización

Consultar también

Realizar operaciones mediante la API web
Consultar datos utilizando la API web
Crear una tabla (entidad) usando la API web
Recuperar una tabla (entidad) usando la API web
Actualizar y eliminar tablas (entidades) mediante la API web
Asociar y anular la asociación de tablas (entidades) 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