Memperbarui dan menghapus baris tabel menggunakan API Web

Operasi untuk 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 akan 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. Respons dengan status 204 No Content dikembalikan jika pembaruan berhasil.

Header If-Match: * memastikan Anda tidak membuat rekaman baru dengan melakukan operasi upsert secara tidak sengaja. Informasi selengkapnya: Mencegah pembuatan dalam proses upsert.

Penting

Saat memperbarui entitas, hanya sertakan properti yang Anda ubah dalam isi permintaan. Dengan memperbarui properti entitas yang sebelumnya Anda ambil, dan dengan menyertakan JSON tersebut dalam permintaan Anda, hal ini akan memperbarui setiap properti walaupun nilainya tetap sama. Ini dapat menyebabkan peristiwa sistem yang dapat memicu logika bisnis yang mengharapkan bahwa nilai telah berubah. Ini dapat menyebabkan properti tampaknya telah diperbarui dalam mengaudit data ketika sebenarnya mereka belum benar-benar berubah.

Ketika Anda memperbarui properti statecode, penting untuk selalu mengatur statuscode yang diinginkan. statecode dan statuscode memiliki nilai dependen. Mungkin ada beberapa nilai statuscode yang valid untuk nilai statecode tertentu, tetapi setiap kolom statecode memiliki satu nilai DefaultStatus yang dikonfigurasi. Saat Anda memperbarui statecode tanpa menentukan statuscode, nilai status default akan diatur oleh sistem. Selain itu, saat audit diaktifkan pada tabel dan kolom statuscode, nilai perubahan pada kolom statuscode tidak akan dicatat dalam data audit kecuali ditentukan pada operasi pembaruan.

Nota

Definisi untuk atribut menyertakan RequiredLevel properti. Ketika ini diatur ke SystemRequired, Anda tidak dapat mengatur atribut ini ke nilai null. Informasi selengkapnya: 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

Lihat Menggunakan properti navigasi bernilai tunggal untuk informasi tentang mengaitkan dan memisahkan entitas saat pembaruan.

Perbarui dengan data yang dikembalikan

Untuk mengambil data dari entitas yang sedang Anda perbarui, Anda dapat menyusun PATCH permintaan sehingga data dari rekaman yang dibuat dikembalikan dengan status 200 (OK). Untuk mendapatkan hasil ini, Anda harus menggunakan header permintaan Prefer: return=representation.

Untuk mengontrol properti mana yang dikembalikan, tambahkan opsi kueri $select ke URL dari 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. Pada saat penulisan ini, 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

Saat Anda ingin memperbarui hanya satu nilai properti, gunakan permintaan PUT dengan nama properti yang ditambahkan ke Uri entitas.

Contoh berikut memperbarui name properti baris yang sudah ada account dengan accountid nilai 00000000-0000-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 properti tunggal, gunakan permintaan DELETE dan tambahkan nama properti ke Uri entitas.

Contoh berikut menghapus nilai description properti entitas akun dengan accountid nilai 00000000-0000-0000-0000-0000-0000000000001.

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

Ini tidak dapat digunakan 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 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 operasi buat atau perbarui, Anda mendapatkan respons 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 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, Anda tidak boleh menyertakan 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 akan membiarkan sistem menetapkan nilai GUID untuk kunci primer. Ini adalah praktik terbaik karena sistem menghasilkan kunci yang dioptimalkan untuk indeks dan 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 ada situasi di mana Anda ingin melakukan upsert, tetapi Anda ingin mencegah salah satu operasi potensial: buat atau perbarui. Anda dapat melakukan ini 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-0000000000001.

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

Cara tercepat untuk menghapus beberapa rekaman dengan jenis yang sama dalam satu permintaan adalah dengan menggunakan DeleteMultiple tindakan. Pada saat penulisan ini, tindakan DeleteMultiple adalah fitur pratinjau. Tabel standar tidak mendukung tindakan ini, tetapi semua tabel elastis melakukannya.

Nota

Untuk tabel standar, sebaiknya gunakan tindakan BulkDelete, yang memungkinkan penghapusan rekaman asinkron yang cocok dengan kueri. Informasi selengkapnya: 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, pastikan untuk menentukan kunci partisi saat 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