Partajați prin

Actualizează și șterge rândurile tabelelor folosind Web API-ul

Operațiunile care modifică datele sunt o parte esențială a Web API-ului. Pe lângă operațiunile simple de actualizare și ștergere, poți efectua operații pe coloane individuale de tabel (atribute de entitate) și poți compune cereri upsert care fie actualizează, fie inserează date, în funcție de existența acestora.

Actualizare de bază

Operațiunile de actualizare utilizează verbul HTTP PATCH . Transmiteți un obiect JSON care conține proprietățile pe care doriți să le actualizați la URI-ul care reprezintă înregistrarea. Dacă actualizarea are succes, răspunsul returnează starea de 204 No Content.

If-Match: * Antetul vă asigură că nu creați o înregistrare nouă prin efectuarea accidentală a unei operațiuni de upsert. Pentru mai multe informații, vezi Prevenirea creării în upsert.

Important

Când actualizați o entitate, includeți numai proprietățile pe care le modificați în corpul solicitării. Dacă actualizezi o entitate incluzând toate proprietățile unei entități pe care le-ai recuperat anterior, operațiunea actualizează fiecare proprietate chiar dacă valoarea este aceeași. Această actualizare poate provoca evenimente de sistem care declanșează logica de business ce se așteaptă ca valorile să se fi schimbat. Poate face ca proprietățile să pară actualizate în datele de audit atunci când de fapt nu s-au schimbat.

Când actualizezi proprietatea statecode , setează întotdeauna valoarea dorită statuscode. Valorile statecode și statuscode depind una de cealaltă. Pentru o anumită statecode valoare, pot exista mai multe valori valide statuscode . Totuși, fiecare statecode coloană are configurată o singură valoare DefaultStatus . Când actualizezi statecode fără a specifica un statuscode, sistemul setează valoarea de stare implicită. De asemenea, dacă activezi auditarea în tabel și coloană statuscode , valoarea modificată pentru coloană statuscode nu este capturată în datele de audit decât dacă o specifici în operațiunea de actualizare.

Notă

Definiția pentru atribute include o RequiredLevel proprietate. Când această proprietate este setată la SystemRequired, nu poți seta aceste atribute la o valoare nulă. Pentru mai multe informații, vezi Nivelul cerinței de atribut.

Acest exemplu actualizează o înregistrare de cont existentă cu valoarea accountid 00000000-0000-0000-0000-00000000000001.

Cerere:

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  
}

Răspuns:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Notă

Pentru informații despre asocierea și disocierea entităților la actualizare, vezi Folosirea proprietăților de navigare cu valoare unică.

Actualizați cu datele returnate

Pentru a recupera date de la o entitate pe care o actualizezi, compune cererea PATCH astfel încât să returneze date din înregistrarea actualizată cu un status de 200 (OK). Pentru a obține acest rezultat, folosiți Prefer: return=representation antetul request.

Pentru a controla ce proprietăți sunt returnate, adaugă $select opțiunea de interogare la URL-ul setului de entități. Opțiunea $expand de interogare este ignorată dacă este utilizată.

Acest exemplu actualizează o entitate de cont și returnează datele solicitate în răspuns.

Cerere:

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

Răspuns:

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

Actualizarea mai multor înregistrări într-o singură solicitare

Cel mai rapid mod de a actualiza mai multe înregistrări de același tip într-o singură solicitare este să utilizați acțiunea UpdateMultiple. Nu toate tabelele standard acceptă această acțiune, dar toate tabelele elastice o fac.

Informații suplimentare:

Actualizarea unei singure valori de proprietate

Pentru a actualiza o singură valoare a proprietății, folosește o PUT cerere și adaugă numele proprietății la Uri-ul entității.

Exemplul următor actualizează proprietatea name unui rând existent account cu accountid valoarea .00000000-0000-0000-0000-000000000001

Cerere:

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

Răspuns:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Ștergerea unei singure valori de proprietate

Pentru a șterge valoarea unei singure proprietăți, folosiți o DELETE cerere cu numele proprietății adăugat la URI-ul entității.

Exemplul următor șterge valoarea proprietății description unei entități de cont cu accountid valoarea .00000000-0000-0000-0000-000000000001

Cerere:

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

Răspuns:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Notă

Nu poți folosi această abordare cu o proprietate de navigare cu o singură valoare pentru a disocia două entități. Pentru o abordare alternativă, vezi Disocierea folosind o proprietate de navigare cu o singură valoare.

Upsert un rând de tabel

O operație de upsert este similară cu o actualizare. Folosește o PATCH solicitare și folosește un URI pentru a face referire la o anumită înregistrare. Diferența este că, dacă înregistrarea nu există, este creată. Dacă există deja, este actualizat.

Upsert este valoros atunci când sincronizați datele între sisteme externe. Sistemul extern s-ar putea să nu conțină o referință la cheia primară a tabelului Dataverse, așa că poți configura chei alternative pentru tabelul Dataverse folosind valori din sistemul extern care identifică în mod unic înregistrarea pe ambele sisteme. Informații suplimentare: Definirea cheilor alternative pentru a face referire la rânduri

Puteți vedea toate cheile alternative definite pentru un tabel în adnotările pentru tipul de entitate din documentul de serviciu $metadata. Informații suplimentare: Taste alternative.

În exemplul următor, există un tabel cu numele sample_thing care are o cheie alternativă care se referă la două coloane: sample_key1 și sample_key2, care sunt ambele definite pentru a stoca valori întregi.

Cerere:

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

Atât pentru operațiunile de creare, cât și pentru cele de actualizare, primești același răspuns. Observați modul în care antetul răspunsului OData-EntityId utilizează valorile cheii mai degrabă decât identificatorul cheie primară GUID pentru înregistrare.

Răspuns:

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)

Deoarece răspunsul este același, nu puteți ști dacă operațiunea a reprezentat o Create operațiune or Update .

Dacă trebuie să știți, puteți utiliza Prefer: return=representation antetul solicitării. Folosind acest antet, primești un 201 Created răspuns când este creată o înregistrare și un 200 OK răspuns când înregistrarea este actualizată. Această opțiune adaugă o Retrieve operațiune, care are un impact asupra performanței. Dacă utilizați Prefer: return=representation antetul solicitării, asigurați-vă că includeți $select cantitatea minimă de date, de preferință numai coloana cheie primară. Informații suplimentare: Actualizați cu datele returnate și Creați cu datele returnate.

Când folosești chei alternative, nu include valorile cheie alternative în corpul cererii.

  • Când un upsert reprezintă un Update, aceste valori cheie alternative sunt ignorate. Nu puteți actualiza valorile cheie alternative în timp ce le utilizați pentru a identifica înregistrarea.
  • Când un upsert reprezintă un Create, valorile cheie din URL sunt setate pentru înregistrare dacă nu sunt prezente în corp. Deci nu este nevoie să le includeți în corpul cererii.

Informații suplimentare: Utilizarea Upsert pentru a crea sau actualiza o înregistrare

Notă

De obicei, când creezi o înregistrare nouă, lași sistemul să atribuie o valoare GUID pentru cheia primară. Această practică este cea mai bună deoarece sistemul generează chei optimizate pentru indice, iar această alegere îmbunătățește performanța. Dar dacă trebuie să creați o înregistrare cu o anumită valoare a cheii primare, cum ar fi atunci când valoarea GUID cheie este generată de un sistem extern, operațiunea upsert oferă o modalitate de a face acest lucru.

Împiedicați crearea sau actualizarea cu upsert

Uneori, vrei să faci un upsert dar să previi una dintre operațiunile potențiale: fie creezi, fie actualizezi. Poți preveni aceste operațiuni folosind anteturile If-Match or If-None-Match . Pentru mai multe informații, consultați Limitarea operațiunilor de upsert.

Ștergere de bază

O operațiune de ștergere este simplă. Utilizați verbul DELETE cu URI-ul entității pe care doriți să o ștergeți. Acest mesaj exemplu șterge o entitate de cont cu valoarea cheie accountid primară egală cu 00000000-0000-0000-0000-000000000001.

Cerere:

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

Răspuns:

Dacă entitatea există, primiți un răspuns normal cu starea 204 pentru a indica faptul că ștergerea a reușit. Dacă entitatea nu este găsită, primiți un răspuns cu starea 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Verificați dacă există înregistrări duplicate

Pentru mai multe informații despre cum să verificați înregistrările duplicate în timpul unei operațiuni de actualizare, consultați Detectarea duplicatelor în timpul operațiunii de actualizare utilizând API-ul Web.

Ștergeți mai multe înregistrări într-o singură solicitare

Pentru a șterge mai multe înregistrări de același tip într-o singură cerere, folosește acțiunea DeleteMultiple . Mesele standard nu suportă această DeleteMultiple acțiune, dar toate mesele elastice da.

Notă

Pentru tabele standard, folosește acțiunea BulkDelete. Această acțiune permite ștergerea asincronă a înregistrărilor care corespund unei interogări. Pentru mai multe informații, vezi Șterge datele în masă.

Informații suplimentare:

Actualizarea și ștergerea documentelor din partițiile de stocare

Dacă actualizezi sau ștergi datele elastice din tabele stocate în partiții, specifică cheia de partiție când accesezi acele date.

Informații suplimentare: Alegerea unei valori PartitionId

Consultați și

Exemplu de operațiuni de bază API web (C#)
Exemplu de operațiuni de bază API web (JavaScript pe partea clientului)
Efectuarea operațiunilor utilizând API-ul web
Compuneți solicitări HTTP și gestionați erorile
Interogarea datelor utilizând API-ul web
Crearea unui rând de tabel utilizând API-ul web
Preluarea unui rând de tabel utilizând API-ul web
Asocierea și disocierea rândurilor de tabel utilizând API-ul web
Utilizarea funcțiilor API web
Utilizați acțiunile Web API
Executarea operațiunilor batch utilizând API-ul web
Uzurparea identității unui alt utilizator utilizând API-ul web
Efectuați operațiuni condiționate utilizând API-ul web

  • Last updated on