Componer solicitudes HTTP y administrar errores

  • Artículo

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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.

En este tema

Dirección URL y versiones de API web

Métodos HTTP

Encabezados de HTTP

Identificar códigos de estado

Errores de análisis de 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.

Elemento

Descripción

Protocolo

El protocolo adecuado, https:// o http://.

URL base

Se trata de la dirección URL que utiliza normalmente para abrir la aplicación web.

  • Para Microsoft Dynamics 365 (online): use <tenant name>.crm.dynamics.com.

  • Para Implementación con conexión a Internet (IFD): use la dirección URL correspondiente para su instancia. Será: <organization name>.<domain name>.

  • Para Dynamics 365 (local): use <server name>/<organization name>

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]/. Las versiones válidas para esta publicación son:

  • v8.0/ Para Actualización 0.1 de Microsoft Dynamics CRM Online 2016 y Actualización 0.1 de Microsoft Dynamics CRM 2016

  • v8.1/ Para Actualización 1 de Microsoft Dynamics CRM Online 2016 y Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ para Actualización de diciembre de 2016 para Dynamics 365 (online y local)

El valor específico que use no es importante con esta versión, siempre que haya aplicado las actualizaciones o los Service Pack correspondientes. Más información: Compatibilidad de versiones

Recurso

El nombre, la función o la acción de entidad que desea usar.

La dirección URL que use se conformará con estas partes: protocolo + URL base + ruta de la API web + versión + recurso.

Compatibilidad de versiones

En esta versión hemos aplicado varios cambios aditivos con cada actualización o Service Pack. Cuando se aplican estas actualizaciones, agregan las mismas capacidades a las versiones secundarias posteriores. Por este motivo, si puede usar la versión 8.2, las versiones 8.1 y 8.0 tendrán las mismas capacidades. Esto es posible debido a que todos los cambios han sido aditivos o son correcciones de errores que abordan los elementos enumerados en Limitaciones de la API web de Microsoft Dynamics 365. No se introdujeron cambios importantes.

Nota

La siguiente versión principal (v9) presenta las capacidades que solo están disponibles con esa versión. Las versiones secundarias posteriores pueden proporcionar capacidades adicionales que no se aplicarán a las versiones secundarias anteriores. El código redactado para v8.x seguirá funcionando en v9.x cuando haga referencia a v8.2 en la dirección URL que use.

Para la versión v8.x, use la última versión que pueda y sepa que las actualizaciones o los Service Pack dentro de esta versión principal no introducirán cambios importantes. No obstante, esto será diferente en futuras versiones, donde deberá prestar más atención a la versión del servicio al que se dirija.

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 entidades de modelo.

Encabezados de 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 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. Usar encabezados OData-Version y OData-MaxVersion establecidos en un valor de 4.0.

Todos los encabezados HTTP deben incluir al menos los siguientes encabezados.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

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 (POST) o actualizar (PATCH) operaciones para entidades, incluya la preferencia return=representation. 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 estado204 (No Content) para reflejar que no se devuelve ningún dato en el cuerpo de la respuesta de forma predeterminada.

    Nota

    Esta funcionalidad se agregó con Actualización de diciembre de 2016 para Dynamics 365 (online y local).

  • Para devolver valores con formato con una consulta, incluya la preferencia odata.include-annotationsestablecida como Microsoft.Dynamics.CRM.formattedvaluemediante el encabezado Prefiera.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 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 MSCRMCallerID con el valor systemuserid del usuario que desea suplantar.Más información:Suplantar a otro usuario utilizando la API web.

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

  • Para habilitar la detección de duplicados para una solicitud POST, puede usar el encabezado MSCRM.SuppressDuplicateDetection: false.Más información:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • Para controlar si una operación de upsert debe crear o actualizar realmente una entidad, también puede usar los encabezados If-Matchy If-None-Match.Más información:Aplicar Upsert a una 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.

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 Dynamics 365 incluyen lo siguiente.

Código

Descripción

Tipo

200 OK

Esto se produce cuando la operación devuelva datos en el cuerpo de la respuesta.

Correcto

201 Created

Cuente con esto cuando la operación POST de la entidad se realice correctamente y haya especificado la preferencia return-representation en su solicitud.

Nota

Esta funcionalidad se agregó con Actualización de diciembre de 2016 para Dynamics 365 (online y local).

Correcto

204 No Content

Esto se produce cuando la operación sea correcta pero no devuelva datos en el cuerpo de la respuesta.

Correcto

304 Not Modified

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 Forbidden

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 Unauthorized

Esto se produce para los siguientes tipos de errores:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Error de cliente

413 Payload Too Large

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 Not Found

Esto se produce 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

Esto se produce para los siguientes tipos de errores:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Error de cliente

500 Internal Server Error

Esto es de esperar cuando una solicitud POST para crear una entidad habilita la detección de duplicados, y la entidad que se creará sería un duplicado.Más información:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

Error de servidor

501 Not Implemented

Esto se produce cuando alguna operación solicitada no se implementa.

Error de servidor

503 Service Unavailable

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

Ver también

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

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright