Compartir a través de

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

Las operaciones para modificar 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 redactar solicitudes upsert que actualizarán o insertarán datos en función de si existe.

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. Se devuelve una respuesta con un estado de 204 No Content si la actualización se realiza correctamente.

El encabezado If-Match: * garantiza que no crea un nuevo registro al realizar accidentalmente una operación upsert. Más información: 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. Actualizando simplemente las propiedades de una entidad que recuperó anteriormente, e incluyendo ese JSON en su solicitud, se actualizará cada propiedad aunque el valor sea el mismo. Esto puede provocar eventos del sistema que pueden desencadenar lógica de negocios que espera que los valores hayan cambiado. Esto puede hacer que las propiedades parezcan haberse actualizado en los datos de auditoría cuando, de hecho, no han cambiado realmente.

Al actualizar la statecode propiedad, es importante establecer siempre el deseado statuscode. statecode y statuscode tienen valores dependientes. Puede haber varios valores statuscode válidos para un valor statecode dado, pero cada columna de statecode tiene un único valor DefaultStatus configurado. Cuando actualice statecode sin especificar un statuscode, el sistema establecerá el valor de estado predeterminado. Además, cuando la auditoría está habilitada en la tabla y la columna statuscode, el valor modificado para la columna statuscode no se capturará en los datos de auditoría a menos que se especifique en la operación de actualización.

Nota:

La definición de los atributos incluye una RequiredLevel propiedad . Cuando esto se establece en SystemRequired, no se pueden establecer estos atributos en un valor NULL. Más información: 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:

Consulte Uso de propiedades de navegación con un solo valor para obtener información sobre cómo asociar y desasociar entidades al actualizar.

Actualización con datos devueltos

Para recuperar datos de una entidad que actualiza, puede redactar su PATCH solicitud para que los datos del registro creado se devuelvan con un estado de 200 (Éxito). Para obtener este resultado, debe usar la cabecera de solicitud Prefer: return=representation.

Para controlar qué propiedades se devuelven, anexe la $select opción de consulta a la dirección URL al 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. En el momento de escribir este artículo, 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

Cuando quiera actualizar solo un valor de propiedad, use una PUT solicitud con el nombre de propiedad anexado al URI de la entidad.

En el ejemplo siguiente se actualiza la name propiedad de una fila existente account con el accountid valor 000000000-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.

En el siguiente ejemplo se elimina el valor de la propiedad description de una entidad de cuenta con el valor accountid 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 con una propiedad de navegación de valor único para desasociar dos entidades. Para un enfoque alternativo, consulte Desasociar con una propiedad de navegación de 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 de Dataverse mediante 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"
}

Para las operaciones de creación o actualización se obtiene 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 debe incluir 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 nuevo registro, se permite que el sistema asigne un valor GUID para la clave principal. Este es un procedimiento recomendado porque el sistema genera claves optimizadas para el índice y esto 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 hay situaciones en las que desea realizar un upsert, pero quiere evitar una de las posibles operaciones: crear o actualizar. Puede hacerlo 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. Este mensaje de ejemplo 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

La forma más rápida de eliminar varios registros del mismo tipo en una sola solicitud es usar la DeleteMultiple acción. En el momento de redactar este documento, la DeleteMultiple acción es una característica en versión preliminar. Las tablas estándar no admiten esta acción, pero todas las tablas elásticas sí lo hacen.

Nota:

Para las tablas estándar, se recomienda usar la acción BulkDelete, que permite la eliminación asincrónica de registros que coinciden con una consulta. Más información: Eliminar datos de forma masiva

Más información:

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

Si está actualizando o eliminando datos de tabla elástica almacenados en particiones, asegúrese de especificar la clave de partición cuando acceda 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