Dijeli putem

Ažuriranje i brisanje redaka tablice pomoću web-API-ja

Operacije za izmjenu podataka temeljni su dio web-API-ja. Osim jednostavnih operacija ažuriranja i brisanja, možete izvoditi operacije na stupcima pojedinačne tablice (atributi entiteta) i sastavljati zahtjeve za nadogradnju koji će ažurirati ili umetnuti podatke ovisno o tome postoje li.

Osnovno ažuriranje

Operacije ažuriranja koriste HTTP PATCH glagol. Proslijedite JSON objekt koji sadrži svojstva koja želite ažurirati na URI koji predstavlja zapis. Odgovor sa statusom 204 No Content vraća se ako je ažuriranje uspješno.

Zaglavlje If-Match: * osigurava da ne stvorite novi zapis slučajnim izvođenjem operacije upsert. Dodatne informacije: Sprječavanje stvaranja u upsertu.

Važno

Prilikom ažuriranja entiteta uključite samo svojstva koja mijenjate u tijelo zahtjeva. Jednostavnim ažuriranjem svojstava entiteta koji ste prethodno dohvatili i uključivanjem tog JSON-a u zahtjev ažurirat ćete svako svojstvo iako je vrijednost ista. To može uzrokovati sistemske događaje koji mogu pokrenuti poslovnu logiku koja očekuje da su se vrijednosti promijenile. To može uzrokovati da se čini da su svojstva ažurirana u podacima nadzora, a zapravo se nisu promijenila.

Kada ažurirate statecode svojstvo, važno je uvijek postaviti željeni statuscode. statecode i statuscode imaju ovisne vrijednosti. Za zadanu statecode vrijednost može postojati više valjanih statuscode vrijednosti, ali svaki statecode stupac ima konfiguriranu jednu vrijednost DefaultStatus. Kada ažurirate statecode bez navođenja , sustav će postaviti zadanu vrijednost statusa statuscode. Također, kada je nadzor omogućen u tablici i stupcu statuscode , promijenjena vrijednost stupca statuscode neće biti zabilježena u podacima nadzora osim ako nije navedena u operaciji ažuriranja.

Napomena

Definicija atributa uključuje svojstvo RequiredLevel . Kada je ovo postavljeno na SystemRequired, ne možete postaviti ove atribute na vrijednost null. Dodatne informacije: Razina zahtjeva atributa

U ovom se primjeru accountid ažurira postojeći zapis računa s vrijednošću 000000000-0000-0000-0000-00000000001.

Zahtjev:

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  
}

Odgovor:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Napomena

Pogledajte Korištenje navigacijskih svojstava s jednom vrijednošću za informacije o povezivanju i razdvajanju entiteta prilikom ažuriranja.

Ažuriranje s vraćenim podacima

Da biste dohvatili podatke iz entiteta koji ažurirate, možete sastaviti PATCH zahtjev tako da se podaci iz stvorenog zapisa vrate sa statusom 200 (U redu). Da biste dobili ovaj rezultat, morate koristiti zaglavlje Prefer: return=representation zahtjeva.

Da biste kontrolirali koja se svojstva vraćaju, dodajte mogućnost upita $select URL-u skupa entiteta. Mogućnost $expand upita se zanemaruje ako se koristi.

Ovaj primjer ažurira entitet računa i vraća tražene podatke u odgovoru.

Zahtjev:

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

Odgovor:

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

Ažuriranje više zapisa u jednom zahtjevu

Najbrži način ažuriranja više zapisa iste vrste u jednom zahtjevu jest korištenje akcije UpdateMultiple. U vrijeme pisanja ovog teksta, akcija UpdateMulti. Ne podržavaju sve standardne tablice ovu akciju, ali sve elastične tablice podržavaju.

Dodatne informacije:

Ažuriranje vrijednosti jednog svojstva

Kada želite ažurirati samo jednu vrijednost svojstva, upotrijebite PUT zahtjev s nazivom svojstva dodanim URI-ju entiteta.

Sljedeći primjer ažurira name svojstvo postojećeg account retka s vrijednošću accountid 000000000-0000-0000-0000-00000000001.

Zahtjev:

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

Odgovor:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Brisanje vrijednosti jednog svojstva

Da biste izbrisali vrijednost jednog svojstva, upotrijebite DELETE zahtjev s nazivom svojstva dodanim Uri-ju entiteta.

Sljedeći primjer briše vrijednost description svojstva entiteta računa s vrijednošću accountid 00000000-0000-0000-0000-00000-000000000001.

Zahtjev:

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

Odgovor:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Napomena

To se ne može koristiti s navigacijskim svojstvom s jednom vrijednošću za prekid povezivanja dvaju entiteta. Za alternativni pristup pogledajte Prekid veze sa svojstvom navigacije s jednom vrijednošću .

Povećanje retka tablice

Operacija upsert slična je ažuriranju. Koristi PATCH zahtjev i koristi URI za referenciranje određenog zapisa. Razlika je u tome što ako zapis ne postoji, on se stvara. Ako već postoji, ažurira se.

Upsert je vrijedan pri sinkronizaciji podataka između vanjskih sustava. Vanjski sustav možda neće sadržavati referencu na primarni ključ tablice Dataverse, tako da možete konfigurirati zamjenske ključeve za tablicu Dataverse koristeći vrijednosti iz vanjskog sustava koje jedinstveno identificiraju zapis na oba sustava. Dodatne informacije: Definiranje zamjenskih ključeva za referenciranje redaka

Sve zamjenske ključeve koji su definirani za tablicu možete vidjeti u napomenama za vrstu entiteta u dokumentu usluge $metadata. Dodatne informacije: Zamjenski ključevi.

U sljedećem primjeru postoji tablica s nazivom sample_thing koja ima zamjenski ključ koji se odnosi na dva stupca: sample_key1 i sample_key2, koji su definirani za pohranu cjelobrojnih vrijednosti.

Zahtjev:

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

Za obje operacije stvaranja ili ažuriranja dobivate isti odgovor. Primijetite kako zaglavlje odgovora OData-EntityId koristi vrijednosti ključa, a ne identifikator primarnog ključa GUID-a za zapis.

Odgovor:

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)

Budući da je odgovor isti, ne možete znati je li operacija predstavljala operaciju Create ili Update .

Ako trebate znati, možete koristiti zaglavlje zahtjeva Prefer: return=representation . Pomoću ovog zaglavlja 201 Created dobivate odgovor kada se zapis stvori i 200 OK odgovor kada se zapis ažurira. Ova opcija dodaje operaciju Retrieve koja utječe na performanse. Ako koristite zaglavlje Prefer: return=representation zahtjeva, provjerite uključuje li minimalnu $select količinu podataka, po mogućnosti samo stupac primarnog ključa. Dodatne informacije: Ažuriranje s vraćenim podacima i Stvaranje s vraćenim podacima.

Kada koristite zamjenske ključeve, ne biste trebali uključiti vrijednosti zamjenskog ključa u tijelo zahtjeva.

  • Kada upsert predstavlja Update, te se vrijednosti zamjenskog ključa zanemaruju. Ne možete ažurirati vrijednosti zamjenskog ključa dok ih koristite za identifikaciju zapisa.
  • Kada upsert predstavlja Create, ključne vrijednosti u URL-u postavljaju se za zapis ako nisu prisutne u tijelu. Dakle, nema potrebe da ih uključite u tijelo zahtjeva.

Dodatne informacije: Korištenje Upserta za stvaranje ili ažuriranje zapisa

Napomena

Obično ćete prilikom stvaranja novog zapisa dopustiti sustavu da dodijeli GUID vrijednost za primarni ključ. To je najbolja praksa jer sustav generira ključeve koji su optimizirani za indeks i to poboljšava performanse. No ako trebate stvoriti zapis s određenom vrijednošću primarnog ključa, primjerice kada je vrijednost GUID-a ključa generirana od strane vanjskog sustava, upsert operacija pruža način da to učinite.

Sprječavanje stvaranja ili ažuriranja pomoću upserta

Ponekad postoje situacije u kojima želite izvesti upsert, ali želite spriječiti jednu od potencijalnih operacija: stvaranje ili ažuriranje. To možete učiniti pomoću If-Match zaglavlja or If-None-Match . Dodatne informacije potražite u odjeljku Ograničavanje operacija upsert.

Osnovno brisanje

Operacija brisanja je jednostavna. Koristite DELETE glagol s URI-jem entiteta koji želite izbrisati. Ova primjerna poruka briše entitet računa s vrijednošću primarnog ključa accountid jednakom 000000000-0000-0000-0000-0000000000001.

Zahtjev:

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

Odgovor:

Ako entitet postoji, dobit ćete uobičajeni odgovor sa statusom 204 koji označava da je brisanje bilo uspješno. Ako entitet nije pronađen, dobit ćete odgovor sa statusom 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Provjera dupliciranih zapisa

Dodatne informacije o tome kako provjeriti ima li dupliciranih zapisa tijekom operacije ažuriranja potražite u odjeljku Otkrivanje duplikata tijekom operacije ažuriranja pomoću web-API-ja.

Brisanje više zapisa u jednom zahtjevu

Najbrži način brisanja više zapisa iste vrste u jednom zahtjevu je korištenje akcije DeleteMultiple . U vrijeme pisanja ovog teksta, DeleteMultiple akcija je značajka pregleda. Standardne tablice ne podržavaju ovu akciju, ali sve elastične tablice podržavaju.

Napomena

Za standardne tablice preporučujemo korištenje akcije BulkDelete koja omogućuje asinkrono brisanje zapisa koji odgovaraju upitu. Dodatne informacije: Skupno brisanje podataka

Dodatne informacije:

Ažuriranje i brisanje dokumenata u particijama za pohranu

Ako ažurirate ili brišete podatke elastične tablice pohranjene u particijama, obavezno navedite ključ particije kada pristupate tim podacima.

Dodatne informacije: Odabir vrijednosti PartitionId

Vidi također

Uzorak osnovnih operacija web-API-ja (C#)
Uzorak osnovnih operacija web-API-ja (JavaScript na strani klijenta)
Izvođenje operacija pomoću web-API-ja
Sastavljanje HTTP zahtjeva i rukovanje pogreškama
Upitanje podataka pomoću web-API-ja
Stvaranje retka tablice pomoću web-API-ja
Dohvaćanje retka tablice pomoću web-API-ja
Pridruživanje i prekid povezivanja redaka tablice pomoću web-API-ja
Korištenje funkcija web-API-ja
Korištenje radnji web-API-ja
Izvršavanje skupnih operacija pomoću web-API-ja
Lažno predstavljanje drugog korisnika pomoću web-API-ja
Izvođenje uvjetnih operacija pomoću web-API-ja

  • Last updated on