Actualitza i elimina files de taula utilitzant l'API web

Les operacions que modifiquen dades són una part fonamental de l'API web. A més d'operacions senzilles d'actualització i eliminació, pots realitzar operacions sobre columnes d'una sola taula (atributs d'entitat) i compondre sol· licituds upsert que actualitzen o insereixen dades segons si existeixen.

Actualització bàsica

Les operacions d'actualització utilitzen el verb HTTP PATCH . Passeu un objecte JSON que contingui les propietats que voleu actualitzar a l'URI que representa el registre. Si l'actualització té èxit, la resposta retorna un estat de 204 No Content.

La If-Match: * capçalera garanteix que no creeu un registre nou realitzant accidentalment una operació upsert. Per a més informació, vegeu Prevenir crear a upsert.

Important

Quan actualitzeu una entitat, incloeu només les propietats que esteu canviant al cos de la sol·licitud. Si actualitzes una entitat incloent totes les propietats d'una entitat que has recuperat prèviament, l'operació actualitza cada propietat encara que el valor sigui el mateix. Aquesta actualització pot provocar esdeveniments del sistema que activen la lògica de negoci que espera que els valors hagin canviat. Pot fer que les propietats semblin actualitzades a les dades d'auditoria quan en realitat no han canviat.

Quan actualitzis la statecode propietat, sempre configura el .statuscode Els statecode valors i statuscode depenen els uns dels altres. Per a un valor donat statecode , poden haver-hi múltiples valors vàlids statuscode . Tanmateix, cada statecode columna té un únic valor DefaultStatus configurat. Quan actualitzes statecode sense especificar un statuscode, el sistema estableix el valor d'estat per defecte. A més, si actives l'auditoria a la taula i a la statuscode columna, el valor canviat de la statuscode columna no es captura a les dades d'auditoria tret que l'especifiquis a l'operació d'actualització.

Nota

La definició d'atributs inclou una RequiredLevel propietat. Quan aquesta propietat s'estableix en SystemRequired, no pots posar aquests atributs a un valor nul. Per a més informació, vegeu Nivell de requisit d'atribut.

En aquest exemple s'actualitza un registre de compte existent amb el accountid valor 00000000-0000-0000-000000000000001.

Demanar:

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

Per a informació sobre com associar i desassociar entitats en l'actualització, vegeu Ús de propietats de navegació d'un sol valor.

Actualitza amb les dades retornades

Per recuperar dades d'una entitat que estàs actualitzant, redacta la teva PATCH sol·licitud perquè retorni dades del registre actualitzat amb un estat de 200 (d'acord). Per obtenir aquest resultat, utilitza la Prefer: return=representation capçalera de la sol·licitud.

Per controlar quines propietats es retornen, afegeix l'opció $select de consulta a la URL del conjunt d'entitats. L'opció $expand de consulta s'ignora si s'utilitza.

Aquest exemple actualitza una entitat de compte i retorna les dades sol·licitades a la resposta.

Demanar:

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

Actualitzar diversos registres en una sola sol·licitud

La manera més ràpida d'actualitzar diversos registres del mateix tipus en una sola sol·licitud és utilitzar l'acció UpdateMultiple. No totes les taules estàndard admeten aquesta acció, però totes les taules elàstiques sí.

Més informació:

Actualitzar un valor de propietat única

Per actualitzar el valor d'una propietat única, utilitza una PUT sol·licitud i afegeix el nom de la propietat a l'Uri de l'entitat.

L'exemple següent actualitza la name propietat d'una fila existent account amb el accountid valor de 00000000-0000-0000-0000-000000000001.

Demanar:

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

Suprimir un sol valor de propietat

Per eliminar el valor d'una sola propietat, utilitza una DELETE sol·licitud amb el nom de la propietat afegit a l'URI de l'entitat.

L'exemple següent elimina el valor de la description propietat d'una entitat del compte amb accountid el valor de 00000000-0000-0000-0000-000000000001.

Demanar:

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

No es pot utilitzar aquest enfocament amb una propietat de navegació d'un sol valor per desassociar dues entitats. Per a un enfocament alternatiu, vegeu Dissociar utilitzant una propietat de navegació d'un sol valor.

Upsert una fila de taula

Una operació d'upsert és similar a una actualització. Utilitza una PATCH sol·licitud i utilitza un URI per fer referència a un registre específic. La diferència és que si el registre no existeix, es crea. Si ja existeix, s'actualitza.

Upsert és valuós a l'hora de sincronitzar dades entre sistemes externs. El sistema extern pot no contenir una referència a la clau primària de la taula Dataverse, així que pots configurar claus alternatives per a la taula Dataverse utilitzant valors del sistema extern que identifiquen de manera única el registre en ambdós sistemes. Més informació: Definir claus alternatives per fer referència a les files

Podeu veure les claus alternatives definides per a una taula a les anotacions del tipus d'entitat del document de servei $metadata. Més informació: Claus alternatives.

A l'exemple següent, hi ha una taula amb el nom sample_thing que té una clau alternativa que fa referència a dues columnes: sample_key1 i sample_key2, que estan definides per emmagatzemar valors enters.

Demanar:

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

Tant per a operacions de creació com d'actualització, obtens la mateixa resposta. Observeu com la capçalera de resposta OData-EntityId utilitza els valors de clau en lloc de l'identificador de clau primària GUID per al registre.

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)

Com que la resposta és la mateixa, no podeu saber si l'operació representava una Create operació o Update .

Si necessites saber-ho, pots utilitzar la capçalera de sol Prefer: return=representation ·licitud. Utilitzant aquesta capçalera, obtens una 201 Created resposta quan es crea un registre i una 200 OK resposta quan s'actualitza el registre. Aquesta opció afegeix una Retrieve operació, que té un impacte en el rendiment. Si utilitzeu la capçalera de sol Prefer: return=representation ·licitud, assegureu-vos que inclogui $select la quantitat mínima de dades, preferiblement només la columna de clau principal. Més informació: Actualitza amb les dades retornades i Crea amb les dades retornades.

Quan utilitzis claus alternatives, no incloguis els valors alternatius de la clau al cos de la sol·licitud.

Quan un upsert representa un Update, aquests valors de clau alternatius s'ignoren. No podeu actualitzar els valors de clau alternatius mentre els utilitzeu per identificar el registre.
Quan un upsert representa un Create, els valors clau de l'URL es defineixen per al registre si no són presents al cos. Per tant, no cal incloure'ls al cos de la sol·licitud.

Més informació: Utilitzar l'Upsert per crear o actualitzar un registre

Nota

Normalment, quan es crea un nou registre, deixes que el sistema assigni un valor GUID per a la clau primària. Aquesta pràctica és la millor perquè el sistema genera claus optimitzades per a l'índex i aquesta elecció millora el rendiment. Però si necessiteu crear un registre amb un valor de clau primària específic, com ara quan el valor del GUID de clau és generat per un sistema extern, l'operació upsert proporciona una manera de fer-ho.

Evitar la creació o l'actualització amb upsert

De vegades, vols fer un upsert però evitar una de les possibles operacions: crear o actualitzar. Pots evitar aquestes operacions utilitzant les If-Match capçaleres o If-None-Match . Per obtenir més informació, vegeu Limitar les operacions d'upsert.

Supressió bàsica

Una operació de supressió és senzilla. Utilitzeu el DELETE verb amb l'URI de l'entitat que voleu suprimir. Aquest missatge d'exemple elimina una entitat de compte amb el valor de la clau accountid primària igual a 00000000-0000-0000-0000-000000000001.

Demanar:

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:

Si l'entitat existeix, obtindreu una resposta normal amb l'estat 204 per indicar que la supressió s'ha realitzat correctament. Si no es troba l'entitat, obtindreu una resposta amb l'estat 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Comprovar si hi ha registres duplicats

Per obtenir més informació sobre com comprovar si hi ha registres duplicats durant una operació d'actualització, vegeu Detectar duplicats durant l'operació d'actualització mitjançant l'API web.

Suprimir diversos registres en una sola sol·licitud

Per eliminar múltiples registres del mateix tipus en una sola sol·licitud, utilitza l'acció DeleteMultiple . Les taules estàndard no suporten aquesta DeleteMultiple acció, però totes les taules elàstiques sí.

Nota

Per a taules estàndard, utilitza l'acció BulkDelete. Aquesta acció permet l'eliminació asíncrona dels registres que coincideixen amb una consulta. Per a més informació, vegeu Eliminar dades en bloc.

Més informació:

Actualitzar i suprimir documents en particions d'emmagatzematge

Si actualitzes o esborres dades de taules elàstiques emmagatzemades a les particions, especifica la clau de partició quan accedeixis a aquestes dades.

Més informació: Triar un valor PartitionId

Vegeu també

Exemple d'operacions bàsiques de l'API web (C#)
Exemple d'operacions bàsiques de l'API web (JavaScript del client)
Realitzar operacions mitjançant l'API web
Redacció de sol·licituds HTTP i gestió d'errors
Consulta de dades mitjançant l'API web
Crear una fila de taula mitjançant l'API web
Recuperar una fila de taula mitjançant l'API web
Associar i desassociar files de taula mitjançant l'API web
Utilitzar funcions de l'API web
Utilitzar accions de l'API web
Executar operacions per lots mitjançant l'API web
Suplantar la identitat d'un altre usuari mitjançant l'API web
Realitzar operacions condicionals mitjançant l'API web

Retroalimentació

Ha estat útil aquesta pàgina?

Last updated on 2026-01-10

Comparteix via

Actualitza i elimina files de taula utilitzant l'API web

Actualització bàsica

Actualitza amb les dades retornades

Actualitzar diversos registres en una sola sol·licitud

Actualitzar un valor de propietat única

Suprimir un sol valor de propietat

Upsert una fila de taula

Evitar la creació o l'actualització amb upsert

Supressió bàsica

Comprovar si hi ha registres duplicats

Suprimir diversos registres en una sola sol·licitud

Actualitzar i suprimir documents en particions d'emmagatzematge

Vegeu també

Retroalimentació

Recursos addicionals