Realizar operaciones condicionales mediante la API web
Microsoft Dataverse ofrece compatibilidad con un conjunto de operaciones condicionales que dependen del mecanismo de control de versiones de recursos HTTP estándar conocido como ETags.
ETags
El protocolo HTTP define una etiqueta de entidad o ETag en el término abreviado, para identificar versiones específicas de un recurso. Las ETags son identificadores opacos cuyos valores exactos dependen de la implementación. Los valores de ETag se producen en dos variedades: validación segura y débil. Una validación fuerte indica que un recurso único, identificado por un URI específico, es idéntico en el nivel binario si su valor ETag correspondiente no cambia. La validación débil solo garantiza que la representación del recurso equivale semánticamente al mismo valor de ETag.
Dataverse genera una propiedad @odata.etag de validación débil para todas las instancias de entidad y esta propiedad se devuelve automáticamente con cada registro de entidad recuperado. Para más información, consulte Recuperar una fila de tabla mediante la API web.
Encabezados If-Match e If-None-Match
Utilice los encabezados If-Match y If-None-Match con valores ETag para verificar si la versión actual de un recurso coincide con la última recuperada, coincide con alguna versión anterior o no coincide con ninguna versión. Estas comparaciones conforman la base de la compatibilidad de operaciones condicional. Dataverse proporciona ETags para admitir las recuperaciones condicionales, la simultaneidad optimista y las operaciones upsert limitadas.
Advertencia
El código de cliente no debe proporcionar ningún significado al valor específico de una ETag, ni a ninguna relación aparente entre las ETags más allá de la igualdad o la desigualdad. Por ejemplo, no se garantiza que un valor de ETag para una versión más reciente de un recurso sea mayor que el valor de ETag para una versión anterior. Además, el algoritmo usado para generar nuevos valores de ETag puede cambiar desigualdad entre las versiones de un servicio.
Recuperaciones condicionales
Las Etags le permiten optimizar recuperaciones de registros siempre que tenga acceso al mismo registro varias veces. Si previamente recuperó un registro, puede pasar el valor ETag con el encabezado If-None-Match para solicitar que se recuperen los datos solo si cambiaron desde la última vez que se recuperaron. Si los datos cambiaron, la solicitud devuelve un estado HTTP de 200 OK con los datos más recientes en el cuerpo de la solicitud. Si los datos no se modifican, se devuelve el código de estado HTTP 304 Not Modified para indicar que el registro no se ha modificado.
El siguiente par de mensajes de ejemplo devuelve datos para un registro de cuenta con el accountid igual a 00000000-0000-0000-0000-000000000001 cuando los datos no han cambiado desde que se recuperaron por última vez cuando se estableció el valor Etag. W/"468026"
Solicitud:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"
Respuesta:
HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Las siguientes secciones describen las limitaciones para usar recuperaciones condicionales.
La tabla debe tener habilitada la simultaneidad optimista
Compruebe si una tabla tiene habilitada la concurrencia optimista mediante la siguiente solicitud de API web. Las tablas que tienen habilitada la simultaneidad optimista tienen la propiedad EntityMetadata.IsOptimisticConcurrencyEnabled establecida en true.
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled
La consulta no debe incluir $expand
El Etag solo puede detectar si el registro individual que se está recuperando cambió. Cuando utiliza $expand en su consulta, es posible que se devuelvan más registros y no sea posible detectar si alguno de esos registros cambió o no. Si la consulta incluye $expand, 304 Not Modified nunca se devuelve.
La consulta no debe incluir anotaciones
Cuando el encabezado Prefer: odata.include-annotations se incluye con una GET solicitud, 304 Not Modified nunca se devuelve. Los valores de las anotaciones pueden referirse a valores de registros relacionados. Es posible que estos registros hayan cambiado y este cambio no se pudo detectar, por lo que sería incorrecto indicar que nada cambió.
Limitar operaciones de upsert
Por lo general, un upsert funciona creando un registro si no existe; de lo contrario, actualiza un registro existente. Sin embargo, las ETags se pueden usar para restringir más upserts para evitar creaciones o actualizaciones.
Evitar crear en upsert
Si está actualizando datos y existe alguna posibilidad de que el registro se haya eliminado intencionalmente, no querrá volver a crearlo. Para evitar este problema, agregue un encabezado If-Match a la solicitud con un valor de *.
Solicitud:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: *
{
"name": "Updated Sample Account ",
"creditonhold": true,
"address1_latitude": 47.639583,
"description": "This is the updated description of the sample account",
"revenue": 6000000,
"accountcategorycode": 2
}
Respuesta:
Si se encuentra el registro, obtendrá un respuesta normal con estado 204 No Content. Cuando no se encuentra el registro, obtendrá el siguiente respuesta con estado 404 Not Found.
HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error": {
"code": "",
"message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist"
}
}
Evitar actualizar en upsert
Si está insertando datos, existe la posibilidad de que ya exista un registro con el mismo valor en el sistema y no desee actualizarlo. id Para evitar este problema, agregue un encabezado If-None-Match a la solicitud con un valor de "*".
Solicitud:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: *
{
"name": "Updated Sample Account ",
"creditonhold": true,
"address1_latitude": 47.639583,
"description": "This is the updated description of the sample account",
"revenue": 6000000,
"accountcategorycode": 2
}
Respuesta:
Si no se encuentra el registro, obtendrá un respuesta normal con estado 204 No Content. Cuando se encuentra el registro, obtienes el siguiente respuesta con estado 412 Precondition Failed.
HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error":{
"code":"",
"message":"A record with matching key values already exists."
}
}
Aplicar simultaneidad optimista
Puede utilizar la concurrencia optimista para detectar si un registro se modificó desde que se recuperó por última vez. Si el registro que desea actualizar o eliminar ha cambiado en el servidor desde que lo recuperó, es posible que no desee completar la operación de actualización o eliminación. Al aplicar el patrón que se muestra aquí, puede detectar esta situación, recuperar la versión más reciente del registro y aplicar cualquier criterio necesario para reevaluar si debe intentar la operación nuevamente.
Aplicar simultaneidad optimista al eliminar
La siguiente solicitud de eliminación de una cuenta con accountid de 00000000-0000-0000-0000-000000000001 da error porque el valor de ETag enviado con el encabezado If-Match es diferente del valor actual. Si el valor coincide, se espera un estado 204 No Content .
Solicitud:
DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Respuesta:
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"error":{
"code":"","message":"The version of the existing record doesn't match the RowVersion property provided."
}
}
Aplicar simultaneidad optimista al actualizar
La siguiente solicitud de actualización de una cuenta con accountid de 00000000-0000-0000-0000-000000000001 da error porque el valor de ETag enviado con el encabezado If-Match es diferente del valor actual. Si el valor coincide, se espera un estado 204 No Content .
Solicitud:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{"name":"Updated Account Name"}
Respuesta:
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"error":{
"code":"","message":"The version of the existing record doesn't match the RowVersion property provided."
}
}
Consulte también
Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
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
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).