Kemas kini dan padamkan baris jadual dengan menggunakan API Web

Operasi yang mengubah suai data adalah bahagian teras API Web. Sebagai tambahan kepada operasi kemas kini dan pemadaman mudah, anda boleh melaksanakan operasi pada lajur jadual tunggal (atribut entiti) dan mengarang permintaan upsert yang sama ada mengemas kini atau menyelitkan data bergantung pada sama ada ia wujud.

Kemas kini asas

Operasi kemas kini menggunakan kata kerja HTTP PATCH . Hantar objek JSON yang mengandungi sifat yang anda mahu kemas kini kepada URI yang mewakili rekod. Jika kemas kini berjaya, respons mengembalikan status 204 No Content.

If-Match: * Pengepala memastikan anda tidak mencipta rekod baharu dengan melakukan operasi upsert secara tidak sengaja. Untuk maklumat lanjut, lihat Cegah cipta dalam upsert.

Penting

Apabila mengemas kini entiti, sertakan hanya sifat yang anda ubah dalam isi permintaan. Jika anda mengemas kini entiti dengan memasukkan semua sifat entiti yang anda ambil sebelum ini, operasi mengemas kini setiap sifat walaupun nilainya sama. Kemas kini ini boleh menyebabkan peristiwa sistem yang mencetuskan logik perniagaan yang menjangkakan bahawa nilai telah berubah. Ia boleh menyebabkan sifat kelihatan dikemas kini dalam data pengauditan apabila ia tidak benar-benar berubah.

Apabila anda mengemas kini statecode hartanah, sentiasa tetapkan .statuscode Nilai dan statecodestatuscode bergantung antara satu sama lain. Untuk nilai tertentu statecode , mungkin terdapat berbilang nilai yang sah statuscode . Walau bagaimanapun, setiap statecode lajur mempunyai satu nilai DefaultStatus yang dikonfigurasikan. Apabila anda mengemas kini statecode tanpa menentukan statuscode, sistem menetapkan nilai status lalai. Selain itu, jika anda mendayakan pengauditan pada jadual dan statuscode lajur, nilai yang diubah untuk statuscode lajur tidak ditangkap dalam data audit melainkan anda menentukannya dalam operasi kemas kini.

Nota

Takrifan untuk atribut termasuk RequiredLevel sifat. Apabila sifat ini ditetapkan kepada SystemRequired, anda tidak boleh mengesetkan atribut ini kepada nilai nol. Untuk maklumat lanjut, lihat Tahap keperluan atribut.

Contoh ini mengemas kini rekod akaun sedia ada dengan accountid nilai 00000000-0000-0000-0000000000001.

Permintaan:

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  
}  

Respons:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Nota

Untuk maklumat tentang mengaitkan dan menyahassociasi entiti pada kemas kini, lihat Menggunakan sifat navigasi bernilai tunggal.

Kemas kini dengan data dikembalikan

Untuk mendapatkan semula data daripada entiti yang anda kemas kini, karang permintaan anda PATCH supaya ia mengembalikan data daripada rekod yang dikemas kini dengan status 200 (OK). Untuk mendapatkan hasil ini, gunakan pengepala permintaan Prefer: return=representation .

Untuk mengawal sifat yang dikembalikan, tambahkan $select opsyen pertanyaan pada URL untuk set entiti. $expand Opsyen pertanyaan diabaikan jika digunakan.

Contoh ini mengemas kini entiti akaun dan mengembalikan data yang diminta dalam respons.

Permintaan:

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

Respons:

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

Kemas kini berbilang rekod dalam satu permintaan

Cara terpantas untuk mengemas kini berbilang rekod jenis yang sama dalam satu permintaan ialah menggunakan tindakan UpdateMultiples. Tidak semua jadual standard menyokong tindakan ini, tetapi semua jadual elastik menyokong tindakan ini.

Maklumat lanjut:

• Mesej Operasi Pukal
• Sampel: API Web Gunakan operasi pukal
• Gunakan UpdateMultiple dengan jadual elastik

Kemas kini satu nilai sifat

Untuk mengemas kini satu nilai sifat, gunakan PUT permintaan dan tambah nama sifat pada Uri entiti.

Contoh berikut mengemas kini name sifat baris sedia ada account dengan accountid nilai 00000000-0000-0000-0000-000000000001.

Permintaan:

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

Respons:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Padamkan satu nilai sifat

Untuk memadamkan nilai sifat tunggal, gunakan DELETE permintaan dengan nama sifat ditambahkan pada URI entiti.

Contoh berikut memadamkan nilai description sifat entiti akaun dengan accountid nilai 00000000-0000-0000-0000-000000000001.

Permintaan:

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  

Respons:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Nota

Anda tidak boleh menggunakan pendekatan ini dengan sifat navigasi bernilai tunggal untuk menyahkaitkan dua entiti. Untuk pendekatan alternatif, lihat Nyahassociasi dengan menggunakan sifat navigasi bernilai tunggal.

Upsert baris meja

Operasi upsert adalah serupa dengan kemas kini. Ia menggunakan PATCH permintaan dan menggunakan URI untuk merujuk rekod tertentu. Perbezaannya ialah jika rekod itu tidak wujud, ia dibuat. Jika ia sudah wujud, ia dikemas kini.

Upsert adalah berharga apabila menyegerakkan data antara sistem luaran. Sistem luaran mungkin tidak mengandungi rujukan kepada kunci utama jadual Dataverse, jadi anda boleh mengkonfigurasi kunci alternatif untuk jadual Dataverse dengan menggunakan nilai daripada sistem luaran yang mengenal pasti rekod secara unik pada kedua-dua sistem. Maklumat lanjut: Tentukan kekunci alternatif untuk baris rujukan

Anda boleh melihat sebarang kunci alternatif yang ditakrifkan untuk jadual dalam anotasi untuk jenis entiti dalam dokumen perkhidmatan $metadata. Maklumat lanjut: Kekunci Alternatif.

Dalam contoh berikut, terdapat jadual dengan nama sample_thing yang mempunyai kunci alternatif yang merujuk kepada dua lajur: sample_key1 dan sample_key2, yang kedua-duanya ditakrifkan untuk menyimpan nilai integer.

Permintaan:

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

Untuk kedua-dua operasi cipta atau kemas kini, anda mendapat respons yang sama. Perhatikan cara OData-EntityId pengepala respons menggunakan nilai kunci dan bukannya pengecam kunci utama GUID untuk rekod.

Respons:

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)

Oleh kerana respons adalah sama, anda tidak boleh mengetahui sama ada operasi mewakili operasi atau CreateUpdate atau.

Jika anda perlu tahu, anda boleh menggunakan pengepala permintaan Prefer: return=representation . Dengan menggunakan pengepala ini, anda mendapat 201 Created respons apabila rekod dicipta dan 200 OK respons apabila rekod dikemas kini. Pilihan ini menambah Retrieve operasi, yang memberi kesan kepada prestasi. Jika anda menggunakan pengepala permintaan Prefer: return=representation , pastikan anda $select menyertakan jumlah data yang minimum, sebaik-baiknya lajur kunci utama sahaja. Maklumat lanjut: Kemas kini dengan data yang dikembalikan dan Cipta dengan data yang dikembalikan.

Apabila menggunakan kunci alternatif, jangan sertakan nilai kunci alternatif dalam isi permintaan.

• Apabila upsert mewakili nilai Updatekekunci alternatif , nilai kekunci alternatif ini diabaikan. Anda tidak boleh mengemas kini nilai kunci alternatif semasa menggunakannya untuk mengenal pasti rekod.
• Apabila upsert mewakili Create, nilai utama dalam URL ditetapkan untuk rekod jika ia tidak terdapat dalam isi. Jadi tidak perlu memasukkannya ke dalam badan permintaan.

Maklumat lanjut: Gunakan Upsert untuk Mencipta atau Mengemas kini rekod

Nota

Biasanya apabila mencipta rekod baharu, anda membenarkan sistem menetapkan nilai GUID untuk kunci utama. Amalan ini adalah yang terbaik kerana sistem menjana kunci yang dioptimumkan untuk indeks dan pilihan ini meningkatkan prestasi. Tetapi jika anda perlu mencipta rekod dengan nilai kunci utama tertentu, seperti apabila nilai GUID utama dijana oleh sistem luaran, operasi menyediakan upsert cara untuk melakukan ini.

Cegah cipta atau kemas kini dengan upsert

Kadangkala, anda mahu melakukan tetapi upsert menghalang salah satu operasi yang berpotensi: sama ada cipta atau kemas kini. Anda boleh menghalang operasi ini dengan menggunakan If-Match pengepala atau If-None-Match . Untuk maklumat lanjut, lihat Hadkan operasi upsert.

Padam asas

Operasi pemadaman adalah mudah. Gunakan DELETE kata kerja dengan URI entiti yang anda mahu padamkan. Mesej contoh ini memadamkan entiti akaun dengan nilai kunci accountid utama sama dengan 00000000-0000-0000-0000-000000000001.

Permintaan:

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  

Respons:

Jika entiti wujud, anda mendapat respons biasa dengan status 204 untuk menunjukkan pemadaman telah berjaya. Jika entiti tidak ditemui, anda akan mendapat respons dengan status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0  

Semak rekod pendua

Untuk maklumat lanjut tentang cara menyemak rekod pendua semasa operasi kemas kini, lihat Mengesan pendua semasa operasi Kemas Kini menggunakan API Web.

Padamkan berbilang rekod dalam satu permintaan

Untuk memadamkan berbilang rekod jenis yang sama dalam satu permintaan, gunakan DeleteMultiple tindakan. Jadual standard tidak menyokong tindakan ini DeleteMultiple , tetapi semua jadual elastik melakukannya.

Nota

Untuk jadual standard, gunakan tindakan BulkDelete. Tindakan ini membolehkan pemadaman tak segerak rekod yang sepadan dengan pertanyaan. Untuk maklumat lanjut, lihat Padamkan data secara pukal.

Maklumat lanjut:

• Mesej Operasi Pukal
• Kod sampel jadual elastik
• Gunakan DeleteMultiple dengan jadual elastik

Kemas kini dan padamkan dokumen dalam partition storan

Jika anda mengemas kini atau memadamkan data jadual elastik yang disimpan dalam partition, tentukan kunci partition apabila anda mengakses data tersebut.

Maklumat lanjut: Memilih nilai PartitionId

Lihat juga

Sampel Operasi Asas API Web (C#)
Sampel Operasi Asas API Web (JavaScript bahagian pelanggan)
Melaksanakan operasi menggunakan API Web
Mengarang permintaan Http dan mengendalikan ralat
Pertanyaan Data menggunakan API Web
Cipta baris jadual menggunakan API Web
Dapatkan semula baris jadual menggunakan API Web
Kaitkan dan nyahassociasikan baris jadual menggunakan API Web
Gunakan fungsi API Web
Gunakan tindakan API Web
Laksanakan operasi kumpulan menggunakan API Web
Menyamar sebagai pengguna lain menggunakan API Web
Lakukan operasi bersyarat menggunakan API Web