Compartir por

Actualizar e eliminar filas de táboa usando a API web

As operacións para modificar datos son unha parte fundamental da API web. Ademais de operacións simples de actualización e eliminación, pode realizar operacións en columnas dunha soa táboa (atributos de entidade) e compoñer solicitudes de upsert que actualizarán ou inserirán datos dependendo de se existen.

Actualización básica

As operacións de actualización usan o verbo HTTP PATCH . Pasa un obxecto JSON que conteña as propiedades que desexa actualizar ao URI que representa o rexistro. Devólvese unha resposta co estado de 204 No Content se a actualización é exitosa.

A If-Match: * cabeceira asegura que non se crea un novo rexistro realizando accidentalmente unha operación de upsert. Máis información: Evitar a creación en upsert.

Importante

Ao actualizar unha entidade, inclúa só as propiedades que está a cambiar no corpo da solicitude. Simplemente actualizando as propiedades dunha entidade que recuperaches previamente e incluíndo ese JSON na túa solicitude, actualizarase cada propiedade aínda que o valor sexa o mesmo. Isto pode causar eventos do sistema que poden desencadear a lóxica de negocio que espera que os valores cambiaron. Isto pode causar que as propiedades parecen actualizadas nos datos de auditoría cando en realidade non cambiaron.

Ao actualizar a statecode propiedade, é importante establecer sempre o desexado statuscode. statecode statuscode Teñen valores dependentes. Pode haber varios valores válidos statuscode para un valor dado statecode , pero cada statecode columna ten un único valor DefaultStatus configurado. Cando actualiza statecode sen especificar un statuscode, o valor de estado predeterminado será establecido polo sistema. Ademais, cando a auditoría está activada na táboa e na statuscode columna, o valor modificado para a statuscode columna non se capturará nos datos de auditoría a menos que se especifique na operación de actualización.

Nota

A definición de atributos inclúe unha RequiredLevel propiedade. Cando esta opción está imposta en SystemRequired, non se pode establecer estes atributos a un valor nulo. Máis información: Nivel de requisito de atributos

Este exemplo actualiza un rexistro de conta existente co accountid valor de 00000000-0000-0000-0000-0000000000001.

Solicitude:

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  
}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota

Consulte Uso de propiedades de navegación de valor único para obter información sobre a asociación e desvinculación de entidades na actualización.

Actualización cos datos devoltos

Para recuperar datos dunha entidade que está a actualizar, pode compoñer a súa PATCH solicitude para que os datos do rexistro creado sexan devoltos cun estado de 200 (OK). Para obter este resultado, debes usar a cabeceira da Prefer: return=representation solicitude.

Para controlar as propiedades que se devolven, engade a opción de $select consulta ao URL ao conxunto de entidades. A $expand opción de consulta ignorarase se se usa.

Este exemplo actualiza unha entidade de conta e devolve os datos solicitados na resposta.

Solicitude:

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"}

Resposta:

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 rexistros nunha soa solicitude

O xeito máis rápido de actualizar varios rexistros do mesmo tipo nunha soa solicitude é usar a acción UpdateMultiple. No momento de escribir este artigo, a acción UpdateMultiple. Non todas as táboas estándar soportan esta acción, pero todas as táboas elásticas si.

Máis información:

Actualizar o valor dunha única propiedade

Cando desexa actualizar só un valor de propiedade, use unha PUT solicitude co nome da propiedade engadido ao Uri da entidade.

O exemplo seguinte actualiza a propiedade name dunha fila existente account co accountid valor de 00000000-0000-0000-0000-000000000000001.

Solicitude:

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"}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Eliminar un único valor de propiedade

Para borrar o valor dunha soa propiedade, use unha DELETE solicitude co nome da propiedade engadido ao Uri da entidade.

O seguinte exemplo elimina o valor da propiedade description dunha entidade de conta co accountid valor de 00000000-0000-0000-0000-000000000001.

Solicitude:

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

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nota

Isto non se pode usar cunha propiedade de navegación dun só valor para desasociar dúas entidades. Para un enfoque alternativo, consulte Desasociar cunha propiedade de navegación dun só valor.

Levantar unha fila de táboa

Unha operación de actualización é semellante a unha actualización. Usa unha PATCH solicitude e usa un URI para facer referencia a un rexistro específico. A diferenza é que se o rexistro non existe, créase. Se xa existe, está actualizado.

Upsert é valioso á hora de sincronizar datos entre sistemas externos. O sistema externo pode non conter unha referencia á clave primaria da táboa de Dataverse, polo que pode configurar chaves alternativas para a táboa de Dataverse usando valores do sistema externo que identifiquen de forma única o rexistro en ambos os sistemas. Máis información: Definir chaves alternativas para referenciar filas

Pode ver as claves alternativas definidas para unha táboa nas anotacións do tipo de entidade no documento de servizo $metadata. Máis información: Chaves alternativas.

No seguinte exemplo, hai unha táboa co nome sample_thing que ten unha clave alternativa que se refire a dúas columnas: sample_key1 e sample_key2, que están definidas para almacenar valores enteiros.

Solicitude:

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 ambas as operacións de creación ou actualización obtén a mesma resposta. Observa como a cabeceira de OData-EntityId resposta usa os valores de clave en lugar do identificador de clave primaria GUID para o rexistro.

Resposta:

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 a resposta é a mesma, non podes saber se a operación representaba unha Create operación ou Update .

Se precisas saber, podes usar a cabeceira da Prefer: return=representation solicitude. Con esta cabeceira, obtén unha 201 Created resposta cando se crea un rexistro e unha 200 OK resposta cando se actualiza o rexistro. Esta opción engade unha Retrieve operación, que ten un impacto no rendemento. Se usa a cabeceira da Prefer: return=representation solicitude, asegúrese de que $select inclúe a cantidade mínima de datos, preferentemente só a columna de clave primaria. Máis información: Actualizar cos datos devoltos e Crear cos datos devoltos.

Ao usar chaves alternativas, non debe incluír os valores de clave alternativa no corpo da solicitude.

  • Cando un upsert representa un Update, estes valores de clave alternativos son ignorados. Non podes actualizar os valores de clave alternativos mentres os usas para identificar o rexistro.
  • Cando un upsert representa un Create, os valores clave do URL establécense para o rexistro se non están presentes no corpo. Polo tanto, non é necesario incluílos no corpo da solicitude.

Máis información: Usar Upsert para crear ou actualizar un rexistro

Nota

Normalmente, ao crear un novo rexistro, permitirase que o sistema asigne un valor GUID para a clave primaria. Esta é unha boa práctica porque o sistema xera claves optimizadas para o índice e isto mellora o rendemento. Pero se precisa crear un rexistro cun valor de clave primaria específico, como cando o valor GUID da clave é xerado por un sistema externo, a upsert operación proporciona un xeito de facelo.

Evitar a creación ou actualización con upsert

Ás veces hai situacións nas que se quere realizar un upsert, pero quere evitar unha das posibles operacións: crear ou actualizar. Podes facelo usando as If-Match cabeceiras OR If-None-Match . Para obter máis información, consulte Limitar as operacións de upsert.

Eliminación básica

A operación de borrado é sinxela. Use o verbo DELETE co URI da entidade que desexa eliminar. Esta mensaxe de exemplo elimina unha entidade de conta co valor da clave accountid primaria igual a 00000000-0000-0000-0000-000000000000001.

Solicitude:

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

Resposta:

Se a entidade existe, obtén unha resposta normal co estado 204 para indicar que a eliminación foi exitosa. Se non se atopa a entidade, obterás unha resposta co estado 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Comprobar se hai rexistros duplicados

Para obter máis información sobre como comprobar rexistros duplicados durante unha operación de actualización, consulte Detectar duplicados durante a operación de actualización usando a API web.

Eliminar varios rexistros nunha soa solicitude

O xeito máis rápido de eliminar varios rexistros do mesmo tipo nunha soa solicitude é usar a DeleteMultiple acción. No momento de escribir este artigo, a DeleteMultiple acción é unha característica de previsualización. As táboas estándar non admiten esta acción, pero todas as táboas elásticas si.

Nota

Para táboas estándar, recoméndase usar a acción Borrado en bloque, que permite a eliminación asíncrona de rexistros que coinciden cunha consulta. Máis información: Eliminar datos en masa

Máis información:

Actualizar e eliminar documentos en particións de almacenamento

Se está actualizando ou eliminando datos de táboas elásticas almacenados en particións, asegúrese de especificar a clave de partición ao acceder a eses datos.

Máis información: Escoller un valor PartitionId

Véxase tamén

Exemplo de operacións básicas da API web (C#)
Exemplo de operacións básicas da API web (JavaScript do lado do cliente)
Realizar operacións usando a API Web
Composición de solicitudes HTTP e xestionar erros
Consulta datos usando a API Web
Crear unha fila de táboa usando a API web
Recuperar unha fila de táboa usando a API web
Asociar e desasociar filas de táboa usando a API web
Usar funcións da API web
Use accións da API web
Executar operacións por lotes usando a API web
Suplantar a outro usuario usando a API web
Realizar operacións condicionais usando a API web

  • Last updated on