Componer solicitudes HTTP y administrar errores
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.
|
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:
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:
|
Error de cliente |
401 Unauthorized |
Esto se produce para los siguientes tipos de errores:
|
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:
|
Error de cliente |
412 Precondition Failed |
Esto se produce para los siguientes tipos de errores:
|
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