Actualizar y eliminar filas de tablas usando la API web

  • Artículo

Las operaciones para modificar datos son una parte básica de la API web. Además de una simple actualización y eliminación de operaciones, puede realizar operaciones en columnas de una sola tabla (atributos de entidad) y componer solicitudes upsert que actualizarán o insertarán datos dependiendo 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 desee actualizar a la URL que representa al registro. Se devolverá una respuesta con un estado de 204 No Content si la actualización es correcta.

El encabezado If-Match: * garantiza que no crea un nuevo registro al realizar accidentalmente una operación upsert. Más información: Evitar realizar operaciones de creación en upsert.

Importante

Al actualizar una entidad, incluya únicamente las propiedades que está modificando 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 la lógica de negocios que espera que los valores hayan cambiado. Esto puede hacer que parezca que las propiedades se han actualizado en auditoría de datos cuando de hecho no han cambiado realmente.

Cuando actualice la propiedad statecode, es importante establecer siempre el statuscode deseado. 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 atributos incluye una propiedad RequiredLevel. Cuando esta opción se establece en SystemRequired, no puede establecer estos atributos a un valor nulo. Más información: Nivel de requisito de atributo

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

Solicitud:

PATCH [Organization URI]/api/data/v9.0/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 de un solo valor para obtener información sobre cómo asociar y desasociar entidades en la actualización.

Actualizar con datos devueltos

Para recuperar datos de una entidad que está actualizando puede crear la solicitud PATCH de forma que los datos del registro creado sean devueltos con un estado de 200 (OK). Para obtener este resultado, debe usar el encabezado de solicitud Prefer: return=representation.

Para controlar qué propiedades se devuelven, anexe la opción de consulta $select a la dirección URL del conjunto de entidades. Se ignorará la opción de consulta $expand si se utiliza.

Este ejemplo actualiza una entidad de cuenta y devuelve los datos solicitados en la respuesta.

Solicitud:

PATCH [Organization URI]/api/data/v9.0/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.0/$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 múltiples registros en una sola solicitud

La forma más rápida de actualizar varios registros del mismo tipo en una sola solicitud es utilizar 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í.

Más información:

Actualizar un solo valor de propiedad

Cuando desee actualizar únicamente un solo valor de propiedad, utilice una solicitud PUT con el nombre de propiedad anexado a la Uri de la entidad.

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

Solicitud:

PUT [Organization URI]/api/data/v9.0/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

Eliminar un solo valor de propiedad

Para eliminar el valor de una sola propiedad, utilice una solicitud DELETE con el nombre de propiedad anexado a la 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.0/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

Esto no se puede usar con una propiedad de navegación de un solo valor para anular la asociación de 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 solicitud PATCH y usa una URI para hacer referencia a un registro específico. La diferencia es que si el registro no existe, se creará. Si ya existe, se actualiza.

Upsert es valioso al sincronizar datos entre sistemas externos. El sistema externo no puede contener una referencia a la clave principal de la tabla Dataverse, por lo que puede configurar claves alternativas para la tabla Dataverse utilizando valores del sistema externo que identifiquen 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 para el tipo de entidad en el documento $Metadata Service. Más información: Claves alternativas.

En el siguiente ejemplo, hay una tabla con el nombre sample_thing que tiene un clave alternativa que hace referencia a dos columnas: sample_key1 y sample_key2, ambas definidas 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"
}

Tanto para las operaciones de creación como para las de actualización, obtiene la misma respuesta. El encabezado de respuesta OData-EntityId usa los valores clave, y no el identificador de clave principal GUID 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)

Debido a que la respuesta es la misma, no puede saber si la operación representó una operación Create o Update.

Si necesita saberlo, puede usar el encabezado de solicitud Prefer: return=representation. Con este encabezado, obtiene una respuesta 201 Created cuando se crea un registro y una respuesta 200 OK cuando se actualiza el registro. Esta opción agrega una operación Retrieve, que tiene un impacto en el rendimiento. Si usa el encabezado de solicitud Prefer: return=representation, asegúrese de que su $select incluya 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.

Cuando utilice claves alternativas, no debe incluir los valores clave alternativa en el cuerpo de la solicitud.

  • Cuando un upsert representa un Update, estos valores clave alternativa se ignoran. No puede actualizar los valores de clave alternativa mientras los usa para identificar el registro.
  • Cuando un upsert representa a Create, los valores clave en la 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: Uso de Upsert para crear o actualizar un registro

Nota

Normalmente, al crear un nuevo registro, usted deja que el sistema asigne un valor GUID para la clave principal. Este es un método recomendado porque el sistema genera claves que están 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 GUID de clave, la operación upsert proporciona una manera de hacer esto.

Impedir crear o actualizar con upsert

A veces, hay situaciones donde desea realizar upsert, pero desea evitar una de las operaciones potenciales: crear o actualizar. Puede hacerlo mediante 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. Utilice el verbo DELETE con el URI de la entidad que desea borrar. Este mensaje de ejemplo elimina una entidad de cuenta con el valor de clave principal accountid igual a 00000000-0000-0000-0000-000000000001.

Solicitud:

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

Respuesta:

Si existe la entidad, recibirá una respuesta con estado 204 para indicar que la eliminación fue correcta. Si no se encuentra la entidad, recibirá una respuesta con estado 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Comprobar registros duplicados

Consulte Detectar duplicados durante la operación de actualizaicón mediante la API web para obtener más información sobre cómo buscar registros duplicados durante la operación de actualización.

Eliminar múltiples registros en una sola solicitud

La forma más rápida de eliminar varios registros del mismo tipo en una sola solicitud es utilizar la acción DeleteMultiple. En el momento de escribir este artículo, la acción DeleteMultiple es una función de vista previa. Las tablas estándar no admiten esta acción, pero todas las tablas elásticas sí.

Nota

Para las tablas estándar, recomendamos usar la acción BulkDelete, que permite la eliminación asíncrona de registros que coinciden con una consulta. Más información: Eliminar datos en masa

Más información:

Actualizar y eliminar 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: Elegir un valor de 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)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar 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
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
Realizar operaciones condicionales mediante 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).