Kongsi melalui

Kemas kini dan padamkan baris jadual menggunakan API Web

Operasi untuk mengubah suai data ialah 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 akan 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. Respons dengan status dikembalikan 204 No Content jika kemas kini berjaya.

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

Penting

Apabila mengemas kini entiti, sertakan hanya sifat yang anda ubah dalam isi permintaan. Hanya mengemas kini sifat entiti yang anda ambil sebelum ini, dan memasukkan JSON itu dalam permintaan anda, akan mengemas kini setiap sifat walaupun nilainya sama. Ini boleh menyebabkan peristiwa sistem yang boleh mencetuskan logik perniagaan yang menjangkakan bahawa nilai telah berubah. Ini boleh menyebabkan sifat kelihatan telah dikemas kini dalam data pengauditan sedangkan sebenarnya ia tidak benar-benar berubah.

Apabila anda mengemas kini statecode harta tanah, adalah penting untuk sentiasa menetapkan yang dikehendaki statuscode. statecode dan statuscode mempunyai nilai bergantung. Mungkin terdapat berbilang nilai yang sah statuscode untuk nilai tertentu statecode , tetapi setiap statecode lajur mempunyai satu nilai DefaultStatus yang dikonfigurasikan. Apabila anda mengemas kini statecode tanpa menentukan statuscode, nilai status lalai akan ditetapkan oleh sistem. Selain itu, apabila pengauditan didayakan pada jadual dan statuscode lajur, nilai yang diubah untuk statuscode lajur tidak akan ditangkap dalam data audit melainkan ia ditentukan dalam operasi kemas kini.

Nota

Takrifan untuk atribut termasuk RequiredLevel sifat. Apabila ini ditetapkan kepada SystemRequired, anda tidak boleh mengesetkan atribut ini kepada nilai nol. Maklumat lanjut: 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

Lihat Menggunakan sifat navigasi bernilai tunggal untuk mendapatkan maklumat tentang mengaitkan dan menyahassociasi entiti pada kemas kini.

Kemas kini dengan data dikembalikan

Untuk mendapatkan semula data daripada entiti yang anda kemas kini, anda boleh mengarang permintaan anda PATCH supaya data daripada rekod yang dicipta dikembalikan dengan status 200 (OK). Untuk mendapatkan hasil ini, anda mesti menggunakan pengepala permintaan Prefer: return=representation .

Untuk mengawal sifat yang dikembalikan, tambahkan $select opsyen pertanyaan pada URL pada 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. Pada masa penulisan ini, tindakan UpdateMultiple. Tidak semua jadual standard menyokong tindakan ini, tetapi semua jadual elastik menyokong tindakan ini.

Maklumat lanjut:

Kemas kini satu nilai sifat

Apabila anda mahu mengemas kini hanya satu nilai sifat, gunakan PUT permintaan dengan nama sifat ditambahkan pada Uri entiti.

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

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 000000000-0000-0000-0000-00000000000001.

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

Ini tidak boleh digunakan dengan sifat navigasi bernilai tunggal untuk menyahkaitkan dua entiti. Untuk pendekatan alternatif, lihat Nyahassociasikan dengan 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 kekunci alternatif untuk jadual Dataverse 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 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, anda tidak sepatutnya memasukkan 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 akan membenarkan sistem menetapkan nilai GUID untuk kunci utama. Ini adalah amalan terbaik kerana sistem menjana kunci yang dioptimumkan untuk indeks dan 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 terdapat situasi di mana anda ingin melakukan upsert, tetapi anda ingin menghalang salah satu operasi yang berpotensi: sama ada buat atau kemas kini. Anda boleh melakukan ini 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-000000000000001.

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

Cara terpantas untuk memadamkan berbilang rekod jenis yang sama dalam satu permintaan ialah menggunakan tindakan tersebut DeleteMultiple . Pada masa penulisan ini, tindakan itu DeleteMultiple ialah ciri pratonton. Jadual standard tidak menyokong tindakan ini, tetapi semua jadual elastik menyokong tindakan ini.

Nota

Untuk jadual standard, kami mengesyorkan menggunakan tindakan BulkDelete, yang mendayakan pemadaman tak segerak rekod yang sepadan dengan pertanyaan. Maklumat lanjut: Padamkan data secara pukal

Maklumat lanjut:

Kemas kini dan padamkan dokumen dalam partition storan

Jika anda mengemas kini atau memadamkan data jadual elastik yang disimpan dalam partition, pastikan anda menentukan kunci partition apabila 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

  • Last updated on