Memperbarui dan menghapus baris tabel dengan menggunakan API Web

Operasi yang memodifikasi data adalah bagian inti dari API Web. Selain operasi pembaruan dan penghapusan sederhana, Anda dapat melakukan operasi pada kolom tabel tunggal (atribut entitas) dan menyusun permintaan upsert yang memperbarui atau menyisipkan data tergantung pada apakah ada.

Pembaruan dasar

Operasi pembaruan menggunakan kata kerja HTTP PATCH . Teruskan objek JSON yang berisi properti yang ingin Anda perbarui ke URI yang mewakili rekaman. Jika pembaruan berhasil, respons mengembalikan status 204 No Content.

Header If-Match: * memastikan Anda tidak membuat rekaman baru dengan melakukan operasi upsert secara tidak sengaja. Untuk informasi selengkapnya, lihat Mencegah pembuatan dalam upsert.

Penting

Saat memperbarui entitas, hanya sertakan properti yang Anda ubah dalam isi permintaan. Jika Anda memperbarui entitas dengan menyertakan semua properti entitas yang sebelumnya Anda ambil, operasi memperbarui setiap properti meskipun nilainya sama. Pembaruan ini dapat menyebabkan peristiwa sistem yang memicu logika bisnis yang mengharapkan bahwa nilai telah berubah. Ini dapat menyebabkan properti tampak diperbarui dalam mengaudit data ketika mereka tidak benar-benar berubah.

Saat Anda memperbarui properti statecode, selalu atur statuscode yang diinginkan. Nilai statecode dan statuscode bergantung satu sama lain. Untuk suatu nilai statecode, mungkin ada beberapa nilai statuscode yang valid. Namun, setiap statecode kolom memiliki satu nilai DefaultStatus yang dikonfigurasi. Saat Anda memperbarui statecode tanpa menentukan statuscode, sistem mengatur nilai status default. Selain itu, jika Anda mengaktifkan audit pada tabel dan kolom statuscode, nilai yang diubah untuk kolom statuscode tidak diambil dalam data audit kecuali Anda menentukannya dalam operasi pembaruan.

Nota

Definisi untuk atribut menyertakan RequiredLevel properti. Saat properti ini diatur ke SystemRequired, Anda tidak dapat mengatur atribut ini ke nilai null. Untuk informasi selengkapnya, lihat Tingkat persyaratan atribut.

Contoh ini memperbarui catatan akun yang ada dengan accountid nilai 00000000-0000-0000-0000-0000000000001.

Minta:

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  
}  

Jawaban:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Nota

Untuk informasi tentang mengaitkan dan memisahkan entitas saat pembaruan, lihat Menggunakan properti navigasi bernilai tunggal.

Perbarui dengan data yang dikembalikan

Untuk mengambil data dari entitas yang sedang Anda perbarui, buat permintaan Anda PATCH sehingga mengembalikan data dari rekaman yang diperbarui dengan status 200 (OK). Untuk mendapatkan hasil ini, gunakan Prefer: return=representation header permintaan.

Untuk mengontrol properti mana yang dikembalikan, tambahkan $select opsi kueri ke URL untuk kumpulan entitas. Opsi $expand kueri diabaikan jika digunakan.

Contoh ini memperbarui entitas akun dan mengembalikan data yang diminta dalam respons.

Minta:

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

Jawaban:

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

Memperbarui beberapa rekaman dalam satu permintaan

Cara tercepat untuk memperbarui beberapa rekaman dengan jenis yang sama dalam satu permintaan adalah dengan menggunakan tindakan UpdateMultiple. Tidak semua tabel standar mendukung tindakan ini, tetapi semua tabel elastis melakukannya.

Informasi selengkapnya:

• Pesan Operasi Massal
• Sampel: API Web Menggunakan operasi massal
• Menggunakan UpdateMultiple dengan tabel elastis

Memperbarui satu nilai properti

Untuk memperbarui satu nilai properti, gunakan PUT request dan tambahkan nama properti ke URI entitas.

Contoh berikut memperbarui properti name dari baris account yang sudah ada dengan nilai accountid dari 00000000-0000-0000-0000-000000000001.

Minta:

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

Jawaban:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Menghapus satu nilai properti

Untuk menghapus nilai satu properti, gunakan DELETE permintaan dengan nama properti yang ditambahkan ke URI entitas.

Contoh berikutnya akan menghapus nilai description properti dari entitas akun dengan accountid nilai dari 00000000-0000-0000-0000-000000000001.

Minta:

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  

Jawaban:

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

Nota

Anda tidak dapat menggunakan pendekatan ini dengan properti navigasi bernilai tunggal untuk memisahkan dua entitas. Untuk pendekatan alternatif, lihat Disasosiakan dengan properti navigasi bernilai tunggal.

Melakukan upsert baris tabel

Operasi upsert mirip dengan pembaruan. Ini menggunakan PATCH permintaan dan menggunakan URI untuk mereferensikan rekaman tertentu. Perbedaannya adalah bahwa jika tidak ada, rekaman akan dibuat. Jika sudah ada, itu diperbarui.

Upsert sangat berharga saat menyinkronkan data antara sistem eksternal. Sistem eksternal mungkin tidak berisi referensi ke kunci utama tabel Dataverse, sehingga Anda dapat mengonfigurasi kunci alternatif untuk tabel Dataverse dengan menggunakan nilai dari sistem eksternal yang secara unik mengidentifikasi rekaman pada kedua sistem. Informasi selengkapnya: Menentukan kunci alternatif untuk mereferensikan baris

Anda dapat melihat kunci alternatif apa pun yang ditentukan untuk tabel dalam anotasi untuk jenis entitas dalam dokumen layanan $metadata. Informasi selengkapnya: Kunci Alternatif.

Dalam contoh berikut, ada tabel dengan nama sample_thing yang memiliki kunci alternatif yang mengacu pada dua kolom: sample_key1 dan sample_key2, yang keduanya didefinisikan untuk menyimpan nilai bilangan bulat.

Minta:

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 operasi buat atau perbarui, Anda mendapatkan respon yang sama. Perhatikan bagaimana header respons OData-EntityId menggunakan nilai kunci daripada pengidentifikasi kunci primer GUID untuk rekaman.

Jawaban:

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)

Karena responsnya sama, Anda tidak dapat mengetahui apakah operasi tersebut mewakili operasi Create atau Update.

Jika Anda perlu mengetahuinya, Anda dapat menggunakan header permintaan Prefer: return=representation. Dengan menggunakan header ini, Anda mendapatkan 201 Created respons saat rekaman dibuat dan 200 OK respons saat rekaman diperbarui. Opsi ini menambahkan Retrieve operasi, yang berdampak pada performa. Jika Anda menggunakan Prefer: return=representation header permintaan, pastikan bahwa $select menyertakan jumlah data minimal, sebaiknya hanya kolom kunci utama. Informasi selengkapnya: Perbarui dengan data yang dikembalikan dan Buat dengan data yang dikembalikan.

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

• Ketika upsert mewakili Update, nilai kunci alternatif ini diabaikan. Anda tidak dapat memperbarui nilai kunci alternatif saat menggunakannya untuk mengidentifikasi rekaman.
• Saat upsert mewakili Create, nilai-nilai kunci di dalam URL diatur untuk rekaman jika tidak ada di dalam badan. Jadi tidak perlu menyertakannya dalam isi permintaan.

Informasi selengkapnya: Menggunakan Upsert untuk Membuat atau Memperbarui rekaman

Nota

Biasanya saat membuat rekaman baru, Anda membiarkan sistem menetapkan nilai GUID untuk kunci primer. Praktik ini terbaik karena sistem menghasilkan kunci yang dioptimalkan untuk indeks dan pilihan ini meningkatkan performa. Tetapi jika Anda perlu membuat rekaman dengan nilai kunci utama tertentu, seperti ketika nilai GUID kunci dihasilkan oleh sistem eksternal, operasi upsert menyediakan cara untuk melakukannya.

Mencegah pembuatan atau pembaruan dengan upsert

Terkadang, Anda ingin melakukan upsert, tetapi mencegah salah satu operasi potensial: membuat atau memperbarui. Anda dapat mencegah operasi ini dengan menggunakan If-Match header atau If-None-Match . Untuk informasi selengkapnya, lihat Membatasi operasi upsert.

Penghapusan sederhana

Operasi penghapusan mudah. Gunakan kata kerja DELETE dengan URI entitas yang ingin Anda hapus. Contoh pesan ini menghapus entitas akun dengan nilai kunci accountid utama yang sama dengan 00000000-0000-0000-0000-000000000001.

Minta:

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  

Jawaban:

Jika entitas ada, Anda mendapatkan respons normal dengan status 204 untuk menunjukkan bahwa penghapusan berhasil. Jika entitas tidak ditemukan, Anda mendapatkan respons dengan status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0  

Memeriksa rekaman duplikat

Untuk informasi selengkapnya tentang cara memeriksa rekaman duplikat selama operasi pembaruan, lihat Mendeteksi duplikat selama operasi Pembaruan menggunakan API Web.

Menghapus beberapa rekaman dalam satu permintaan

Untuk menghapus beberapa rekaman dengan jenis yang sama dalam satu permintaan, gunakan DeleteMultiple tindakan . Tabel standar tidak mendukung tindakan ini DeleteMultiple , tetapi semua tabel elastis melakukannya.

Nota

Untuk tabel standar, gunakan tindakan BulkDelete. Tindakan ini memungkinkan penghapusan rekaman asinkron yang cocok dengan kueri. Untuk informasi selengkapnya, lihat Menghapus data secara massal.

Informasi selengkapnya:

• Pesan Operasi Massal
• Kode sampel tabel elastis
• Menggunakan DeleteMultiple dengan tabel elastis

Memperbarui dan menghapus dokumen dalam partisi penyimpanan

Jika Anda memperbarui atau menghapus data tabel elastis yang disimpan dalam partisi, tentukan kunci partisi saat Anda mengakses data tersebut.

Informasi selengkapnya: Memilih nilai PartitionId

Lihat juga

Sampel Operasi Dasar API Web (C#)
Sampel Operasi Dasar API Web (JavaScript sisi klien)
Lakukan operasi menggunakan API Web
Buat permintaan Http dan tangani kesalahan
Data kueri menggunakan API Web
Membuat baris tabel menggunakan API Web
Mengambil baris tabel menggunakan API Web
Mengaitkan dan memisahkan baris tabel menggunakan API Web
Menggunakan fungsi API Web
Gunakan tindakan Web API
Menjalankan operasi batch menggunakan API Web
Meniru pengguna lain menggunakan API Web
Melakukan operasi bersyarah menggunakan API Web