Ejemplo de operaciones condicionales de la API web

Artículo
08/24/2023

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:

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.

Sección de código	Temas conceptuales asociados
Sección 0: Crear registros de muestra	Crear una fila de tabla usando la API web
Sección 1: GET condicional	Recuperaciones condicionales
Sección 2: Simultaneidad optimista al eliminar y actualizar	Aplicar simultaneidad optimista Limitar operaciones de upsert
Sección 3: Eliminar registros de muestra	Eliminación básica Ejecute las operaciones por lotes mediante 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 encabezado If-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/json
```
Respuesta:
```
HTTP/1.1 304 NotModified
```
Salida 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.0

Salida 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/json

Respuesta:

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/json

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 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-Match y 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 GET bá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/json

Respuesta:

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).

Compartir a través de

Ejemplo de operaciones condicionales de la API web

Demostraciones

Sección 0: Crear registros de muestra

Sección 1: GET condicional

Sección 2: Simultaneidad optimista al eliminar y actualizar

Sección 3: Eliminar registros de muestra

Consulte también

Recursos adicionales