Ejemplo de operaciones condicionales de la API web
Esta colección de muestras demuestra cómo realizar operaciones que se basan condicionalmente en la versión de la fila de la tabla contenida en el servidor de Microsoft Dataverse y/o mantenido actualmente por el cliente. Para obtener más información, consulte realizar operaciones condicionales mediante la API web. Este ejemplo se implementa como proyecto independiente para los siguientes idiomas:
- Ejemplo de operaciones condicionales de la API web (C#)
- Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)
La API web de Dataverse sigue las convenciones del protocolo OData v4.0, que usa ETags para implementar el control de versiones del recurso. Las operaciones condicionales de la API web dependen de este mecanismo de versiones.
En este tema se explican la estructura y el contenido de los ejemplos en un nivel superior de lenguaje neutro. Detalla las solicitudes y las respuestas HTTP, y la salida del programa asociada, en el caso correspondiente. Revise los temas de ejemplo vinculados anteriores para obtener implementaciones específicas del idioma y detalles relacionados sobre cómo realizar las operaciones descritas en este tema.
Demostraciones
Este ejemplo se divide en tres secciones principales, enumeradas en la tabla siguiente. Cada sección contiene un conjunto de operaciones API Web relacionadas que se analizan con más detalle en la sección conceptual asociada del tema realizar operaciones condicionales mediante la API Web.
Las siguientes secciones contienen una breve explicación de las operaciones de la API web de Dataverse realizadas, junto con mensajes HTTP correspondientes y la salida asociada de la consola, que es la misma para cada implementación de idioma. Para razones de brevedad, se han omitido los encabezados HTTP menos pertinentes. Los URI de las filas de tabla variarán con la dirección de la organización base y el id. de la fila asignada por su servidor de Dataverse.
Sección 0: Crear registros de muestra
El ejemplo crea la siguiente fila de la tabla antes de que se ejecuten las secciones de código principal.
Solicitud:
POST [Organization Uri]/api/data/v9.2/accounts?$select=name,revenue,telephone1,description HTTP/1.1
Prefer: return=representation
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
{
"name": "Contoso Ltd",
"telephone1": "555-0000",
"revenue": 5000000,
"description": "Parent company of Contoso Pharmaceuticals, etc."
}
Respuesta:
HTTP/1.1 201 Created
Preference-Applied: return=representation
OData-Version: 4.0
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965013\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0000",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}
Salida de la consola:
Created and retrieved the initial account, shown below:
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965013\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0000",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}
Sección 1: GET condicional
Esta sección del programa demuestra cómo realizar recuperaciones condicionales para optimizar el ancho de banda de la red y el procesamiento del servidor mientras se mantiene el estado de fila más actual en el cliente. Más información:Recuperaciones condicionales.
Intenta recuperar la cuenta
Contoso Ltd.solo si no coincide con la versión actual, identificada por el valor ETag inicial que se devolvió cuando se creó la fila de la cuenta. Esta condición se representa por el encabezadoIf-None-Match.Solicitud:
GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1 If-None-Match: W/"72965013" OData-MaxVersion: 4.0 OData-Version: 4.0 Accept: application/jsonRespuesta:
HTTP/1.1 304 NotModifiedSalida de la consola:
Account record retrieved using ETag: W/"72965013" Expected outcome: Entity was not modified so nothing was returned.El valor de respuesta,
304 NotModified, indica que la fila de la tabla actual es la más actual, por lo que el servidor no devuelve la fila solicitada en el cuerpo de la respuesta.Actualice la cuenta modificando su propiedad de número de teléfono principal.
Solicitud:
PUT [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)/telephone1 HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json {"value": "555-0001"}Respuesta:
HTTP/1.1 204 NoContent OData-Version: 4.0Salida de la consola:
Modified account record retrieved using ETag: W/"72965013"Reintente la misma operación GET condicional, de nuevo con el valor de ETag original. Esta vez la operación devuelve los datos solicitados porque la versión en el servidor es diferente (y más reciente) que la versión identificada en la solicitud. Como en todas las recuperaciones de filas de la tabla, la respuesta incluye un encabezado ETag que identifica la versión actual.
Solicitud:
GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1 If-None-Match: W/"72965013" OData-MaxVersion: 4.0 OData-Version: 4.0 Accept: application/jsonRespuesta:
HTTP/1.1 200 OK ETag: W/"72965025" OData-Version: 4.0 { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity", "@odata.etag": "W/\"72965025\"", "name": "Contoso Ltd", "revenue": 5000000.0, "telephone1": "555-0001", "description": "Parent company of Contoso Pharmaceuticals, etc.", "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1" }Salida de la consola:
Modified account record retrieved using ETag: W/"72965013" Notice the updated ETag value and telephone number { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity", "@odata.etag": "W/\"72965025\"", "name": "Contoso Ltd", "revenue": 5000000.0, "telephone1": "555-0001", "description": "Parent company of Contoso Pharmaceuticals, etc.", "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1" }
Sección 2: Simultaneidad optimista al eliminar y actualizar
Esta sección del programa muestra cómo realizar operaciones de eliminación y actualización condicionales. El uso más común de tales operaciones es implementar un enfoque de simultaneidad optimista para el procesamiento de filas en un entorno multiusuario. Más información:Aplicar simultaneidad optimista
Intente eliminar la cuenta original si y solo si coincide con la versión original (valor de ETag). Esta condición se representa por el encabezado
If-Match. Esta operación falla porque la fila de la cuenta se actualizó en la sección anterior, por lo que su versión se actualizó en el servidor.Solicitud:
DELETE [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1 If-Match: W/"72965013" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonRespuesta:
HTTP/1.1 412 PreconditionFailed OData-Version: 4.0 { "error": { "code": "0x80060882", "message": "The version of the existing record doesn't match the RowVersion property provided." } }Salida de la consola:
Attempting to delete the account using the original ETag value Expected Error: The version of the existing record doesn't match the RowVersion property provided. Account not deleted using ETag 'W/"72965013"', status code: 'PreconditionFailed'.Intente actualizar la cuenta si y solo si coincide con el valor de ETag original. Una vez más esta condición está representada por el encabezado
If-Matchy la operación produce un error por la misma razón.Solicitud:
PATCH [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1 If-Match: W/"72965013" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "telephone1": "555-0002", "revenue": 6000000 }Respuesta:
HTTP/1.1 412 PreconditionFailed OData-Version: 4.0 { "error": { "code": "0x80060882", "message": "The version of the existing record doesn't match the RowVersion property provided." } }Salida de la consola:
Attempting to update the account using the original ETag value Expected Error: The version of the existing record doesn't match the RowVersion property provided. Account not updated using ETag 'W/"72965013"', status code: 'PreconditionFailed'.Vuelva a intentar una actualización, pero en su lugar utilice el valor ETag actual obtenido de la última recuperación de fila en la sección anterior.
Solicitud:
PATCH [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1 If-Match: W/"72965025" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "telephone1": "555-0003", "revenue": 6000000 }Respuesta:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)Salida de la consola:
Attempting to update the account using the current ETag value Account successfully updated using ETag: W/"72965025".Confirme que la actualización se realizado satisfactoriamente recuperando y generando el estado de cuenta actual. Esto usa una solicitud
GETbásica.Solicitud:
GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonRespuesta:
HTTP/1.1 200 OK ETag: W/"72965035" OData-Version: 4.0 { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity", "@odata.etag": "W/\"72965035\"", "name": "Contoso Ltd", "revenue": 6000000.0, "telephone1": "555-0003", "description": "Parent company of Contoso Pharmaceuticals, etc.", "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1" }Salida de la consola:
Below is the final state of the account { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity", "@odata.etag": "W/\"72965035\"", "name": "Contoso Ltd", "revenue": 6000000.0, "telephone1": "555-0003", "description": "Parent company of Contoso Pharmaceuticals, etc.", "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1" }
Sección 3: Eliminar registros de muestra
Esta sección simplemente elimina el registro creado en la Sección 0: Crear registros de muestra. Utiliza una solicitud $batch.
Solicitud:
POST [Organization Uri]/api/data/v9.2/$batch HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
--batch_98e0fdc2-a298-4f42-85a8-da0536140b78
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-Length: 115
DELETE /api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1
--batch_98e0fdc2-a298-4f42-85a8-da0536140b78--
Respuesta:
HTTP/1.1 200 OK
OData-Version: 4.0
--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb
Content-Type: application/http
Content-Transfer-Encoding: binary
HTTP/1.1 204 No Content
OData-Version: 4.0
--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb--
Salida de la consola:
Deleting created records.
Consulte también
Usar la API web de Dataverse
Realizar operaciones condicionales mediante la API web
Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)
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).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de