Compartir a través de

Actualización y eliminación de filas de tabla mediante la API web

Las operaciones que modifican los datos son una parte fundamental de la API web. Además de las operaciones de actualización y eliminación simples, puede realizar operaciones en columnas de tabla única (atributos de entidad) y crear solicitudes upsert que actualicen o inserte datos en función de si existen.

Actualización básica

Las operaciones de actualización usan el verbo HTTP PATCH . Pase un objeto JSON que contenga las propiedades que desea actualizar al URI que representa el registro. Si la actualización se realiza correctamente, la respuesta devuelve un estado de 204 No Content.

El encabezado If-Match: * garantiza que no crea un nuevo registro al realizar accidentalmente una operación upsert. Para obtener más información, consulte Impedir la creación en upsert.

Importante

Al actualizar una entidad, únicamente incluya las propiedades que vaya a cambiar en el cuerpo de la solicitud. Si actualiza una entidad mediante la inclusión de todas las propiedades de una entidad que recuperó anteriormente, la operación actualiza cada propiedad incluso si el valor es el mismo. Esta actualización puede provocar eventos del sistema que desencadenan lógica de negocios que espera que los valores hayan cambiado. Puede hacer que las propiedades parezcan actualizarse en los datos de auditoría cuando realmente no cambiaron.

Al actualizar la propiedad statecode, establezca siempre el objeto deseado statuscode. Los statecode valores y statuscode dependen entre sí. Para un valor determinado statecode , puede haber varios valores válidos statuscode . Sin embargo, cada statecode columna tiene configurado un único valor DefaultStatus . Cuando se actualiza statecode sin especificar statuscode, el sistema establece el valor de estado predeterminado. Además, si habilita la auditoría en la tabla y la statuscode columna, el valor cambiado de la statuscode columna no se captura en los datos de auditoría a menos que lo especifique en la operación de actualización.

Nota:

La definición de los atributos incluye una RequiredLevel propiedad . Cuando esta propiedad se establece SystemRequireden , no se pueden establecer estos atributos en un valor NULL. Para obtener más información, consulte Nivel de requisito de atributo.

En este ejemplo se actualiza un registro de cuenta existente con el accountid valor 00000000-0000-0000-0000-000000000001.

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:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota:

Para obtener información sobre cómo asociar y desasociar entidades en la actualización, consulte Uso de propiedades de navegación con valores únicos.

Actualización con datos devueltos

Para recuperar datos de una entidad que va a actualizar, redacte la PATCH solicitud para que devuelva datos del registro actualizado con el estado 200 (Correcto). Para obtener este resultado, use el encabezado de solicitud Prefer: return=representation.

Para controlar qué propiedades se devuelven, anexe la $select opción de consulta a la dirección URL del conjunto de entidades. La $expand opción de consulta se omite si se usa.

En este ejemplo se actualiza una entidad de cuenta y se devuelven los datos solicitados en la respuesta.

Solicitud:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Respuesta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Actualizar varios registros en una sola solicitud

La forma más rápida de actualizar varios registros del mismo tipo en una sola solicitud es usar la acción UpdateMultiple. No todas las tablas estándar admiten esta acción, pero todas las tablas elásticas sí lo hacen.

Más información:

Actualización de un valor de propiedad único

Para actualizar un valor de propiedad único, use una PUT solicitud y agregue el nombre de propiedad al URI de la entidad.

En el siguiente ejemplo se actualiza la propiedad name de una fila account existente con el valor accountid de 00000000-0000-0000-0000-000000000001.

Solicitud:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Respuesta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Eliminación de un único valor de propiedad

Para eliminar el valor de una sola propiedad, use una DELETE solicitud con el nombre de propiedad anexado al URI de la entidad.

El siguiente ejemplo elimina el valor de la propiedad description de una entidad de cuenta existente con el valor accountid de 00000000-0000-0000-0000-000000000001.

Solicitud:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Respuesta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota:

No se puede usar este enfoque con una propiedad de navegación con un solo valor para desasociar dos entidades. Para obtener un enfoque alternativo, consulte Desasociar mediante una propiedad de navegación con un solo valor.

Upsert la fila de una tabla

Una operación upsert es similar a una actualización. Usa una PATCH solicitud y usa un URI para hacer referencia a un registro específico. La diferencia es que si el registro no existe, se crea. Si ya existe, se actualiza.

Upsert es útil al sincronizar datos entre sistemas externos. Es posible que el sistema externo no contenga una referencia a la clave principal de la tabla dataverse, por lo que puede configurar claves alternativas para la tabla dataverse mediante el uso de valores del sistema externo que identifican de forma única el registro en ambos sistemas. Más información: Definir claves alternativas para hacer referencia a filas

Puede ver las claves alternativas definidas para una tabla en las anotaciones del tipo de entidad en el documento de servicio de $metadata. Más información: Claves alternativas.

En el ejemplo siguiente, hay una tabla con el nombre sample_thing que tiene una clave alternativa que hace referencia a dos columnas: sample_key1 y sample_key2, que se definen para almacenar valores enteros.

Solicitud:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

En el caso de las operaciones de creación o actualización, obtendrá la misma respuesta. Observe cómo el encabezado de respuesta OData-EntityId utiliza los valores clave en lugar del identificador GUID de clave primaria para el registro.

Respuesta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Dado que la respuesta es la misma, no se puede saber si la operación representa una Create operación o Update .

Si necesita saberlo, puede usar el encabezado de solicitud Prefer: return=representation. Con este encabezado, obtendrá una 201 Created respuesta cuando se crea un registro y una 200 OK respuesta cuando se actualiza el registro. Esta opción agrega una Retrieve operación, que tiene un impacto en el rendimiento. Si usa el Prefer: return=representation encabezado de solicitud, asegúrese de que $select incluye la cantidad mínima de datos, preferiblemente solo la columna de clave principal. Más información: Actualizar con datos devueltos y Crear con datos devueltos.

Al usar claves alternativas, no incluya los valores de clave alternativos en el cuerpo de la solicitud.

  • Cuando un upsert representa un Update, se omiten estos valores de clave alternativos. No puede actualizar valores de clave alternativos mientras los usa para identificar el registro.
  • Cuando un upsert representa un Create, los valores de clave de la dirección URL se establecen para el registro si no están presentes en el cuerpo. Por lo tanto, no es necesario incluirlos en el cuerpo de la solicitud.

Más información: Usar Upsert para crear o actualizar un registro

Nota:

Normalmente, al crear un registro nuevo, se permite que el sistema asigne un valor GUID para la clave principal. Este procedimiento es mejor porque el sistema genera claves optimizadas para el índice y esta opción mejora el rendimiento. Pero si necesita crear un registro con un valor de clave principal específico, como cuando un sistema externo genera el valor de clave GUID, una upsert operación proporciona una manera de hacerlo.

Impedir la creación o actualización con upsert

A veces, desea realizar un acción upsert, pero evitar una de las operaciones posibles: crear o actualizar. Puede evitar estas operaciones mediante los encabezados If-Match o If-None-Match. Para obtener más información, consulte Limitar operaciones de upsert.

Eliminación básica

Una operación de eliminación es sencilla. Use el DELETE verbo con el URI de la entidad que desea eliminar. En este mensaje de ejemplo se elimina una entidad de cuenta con el valor de clave accountid principal igual a 00000000-0000-0000-0000-000000000001.

Solicitud:

DELETE [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

Respuesta:

Si la entidad existe, obtendrá una respuesta normal con el estado 204 para indicar que la eliminación se realizó correctamente. Si no se encuentra la entidad, obtendrá una respuesta con el estado 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Comprobar registros duplicados

Para obtener más información sobre cómo comprobar los registros duplicados durante una operación de actualización, consulte Detección de duplicados durante la operación de actualización mediante la API web.

Eliminación de varios registros en una sola solicitud

Para eliminar varios registros del mismo tipo en una sola solicitud, use la DeleteMultiple acción . Las tablas estándar no admiten esta DeleteMultiple acción, pero todas las tablas elásticas sí lo hacen.

Nota:

Para las tablas estándar, use la acción BulkDelete. Esta acción permite la eliminación asincrónica de registros que coinciden con una consulta. Para obtener más información, consulte Eliminar datos de forma masiva.

Más información:

Actualización y eliminación de documentos en particiones de almacenamiento

Si va a actualizar o eliminar datos de tabla elástica almacenados en particiones, especifique la clave de partición al acceder a esos datos.

Más información: Elección de un valor PartitionId

Consulte también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de operaciones básicas de la API web (JavaScript del lado del cliente)
Realización de operaciones mediante la API web
Redacción de solicitudes HTTP y control de errores
Consultar datos utilizando la API web
Crear una fila de tabla usando la API web
Recuperar una fila de tabla usando la API web
Asociar y anular la asociación de filas de tabla mediante la API web
Uso de funciones de API web
Usar acciones de la API web
Ejecución de operaciones por lotes mediante la API web
Suplantar a otro usuario mediante la API web
Realización de operaciones condicionales mediante la API web

  • Last updated on