Sisipkan atau Ganti Entitas

Artikel
07/26/2022
5 menit untuk membaca

Operasi Insert Or Replace Entity menggantikan entitas yang ada atau menyisipkan entitas baru jika tidak ada dalam tabel. Karena operasi ini dapat menyisipkan atau memperbarui entitas, operasi ini juga dikenal sebagai operasi upsert .

Minta

Permintaan Insert Or Replace Entity dapat dibuat sebagai berikut. HTTPS disarankan. Ganti nilai berikut dengan nilai Anda sendiri:

myaccount dengan nama akun penyimpanan Anda
mytable dengan nama tabel Anda
myPartitionKey dan myRowKey dengan nama kunci partisi dan kunci baris untuk entitas yang akan diperbarui

Metode	Meminta URI	Versi HTTP
`PUT`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Layanan Storage Emulasi

Saat membuat permintaan terhadap layanan penyimpanan yang ditimulasi, tentukan nama host emulator dan port layanan Table sebagai 127.0.0.1:10002, diikuti dengan nama akun penyimpanan yang ditimulasi.

Metode	Meminta URI	Versi HTTP
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Layanan Table di emulator penyimpanan berbeda dari layanan Windows ® Azure™ Table dalam beberapa cara. Untuk informasi selengkapnya, lihat Perbedaan Antara Emulator Storage dan Layanan Azure Storage.

Parameter URI

Parameter tambahan berikut dapat ditentukan pada URI permintaan.

Parameter	Deskripsi
`timeout`	Opsional. Parameter batas waktu dinyatakan dalam hitung detik. Untuk informasi selengkapnya, lihat Mengatur Batas Waktu untuk Operasi Layanan Tabel.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Header permintaan	Deskripsi
`Authorization`	Wajib diisi. Menentukan skema otorisasi, nama akun, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
`Date` atau `x-ms-date`	Wajib diisi. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
`x-ms-version`	Diperlukan, harus diatur ke 2011-08-18 atau yang lebih baru. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage.
`Content-Type`	Wajib diisi. Menentukan jenis konten payload. Nilai yang mungkin adalah `application/atom+xml` dan `application/json`. Untuk formasi selengkapnya tentang jenis konten yang valid, lihat Format Payload untuk Operasi Layanan Tabel.
`Content-Length`	Wajib diisi. Panjang isi permintaan.
`x-ms-client-request-id`	Opsional. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 KiB yang dicatat dalam log analitik saat pengelogan analitik penyimpanan diaktifkan. Menggunakan header ini sangat direkomendasikan untuk mengkorelasi aktivitas sisi klien dengan permintaan yang diterima oleh server. Untuk informasi selengkapnya, lihat Tentang Storage Analytics Logging dan Azure Logging: Menggunakan Log untuk Melacak Permintaan Storage.

Isi Permintaan

Operasi Insert Or Replace Entity mengirimkan entitas untuk dimasukkan sebagai kumpulan entitas OData, yang mungkin berupa JSON atau umpan Atom. Untuk informasi selengkapnya, lihat Menyisipkan dan Memperbarui Entitas.

Catatan

JSON adalah format payload yang direkomendasikan, dan merupakan satu-satunya format yang didukung untuk versi 2015-12-11 dan yang lebih baru.

Respons

Respons mencakup kode status HTTP dan sekumpulan header respons.

Kode Status

Operasi yang berhasil mengembalikan kode status 204 (Tanpa Konten).

Untuk informasi tentang kode status, lihat Kode Status dan Kesalahan dan Kode Kesalahan Layanan Tabel.

Header Respons

Respons mencakup header berikut. Respons juga dapat mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.

Header respons	Deskripsi
ETag	ETag untuk entitas.
`x-ms-request-id`	Header ini secara unik mengidentifikasi permintaan yang dibuat dan dapat digunakan untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Pemecahan Masalah Operasi API.
`x-ms-version`	Menunjukkan versi layanan Tabel yang digunakan untuk menjalankan permintaan. Header ini dikembalikan untuk permintaan yang dibuat terhadap versi 2009-09-19 dan yang lebih baru.
`Date`	Nilai tanggal/waktu UTC yang dihasilkan oleh layanan yang menunjukkan waktu dimulainya respons.
`x-ms-client-request-id`	Header ini dapat digunakan untuk memecahkan masalah permintaan dan respons yang sesuai. Nilai header ini sama dengan nilai `x-ms-client-request-id` header jika ada dalam permintaan dan nilainya paling banyak 1024 karakter ASCII yang terlihat. `x-ms-client-request-id` Jika header tidak ada dalam permintaan, header ini tidak akan ada dalam respons.

Isi Respons

Tidak ada.

Authorization

Operasi ini dapat dilakukan oleh pemilik akun dan oleh siapa pun dengan tanda tangan akses bersama yang memiliki izin untuk melakukan operasi ini.

Permintaan dan Respons Sampel

Contoh di bawah ini menunjukkan permintaan sampel menggunakan umpan JSON dan Atom.

Catatan

JSON adalah format payload yang direkomendasikan, dan merupakan satu-satunya format yang didukung untuk versi 2015-12-11 dan yang lebih baru.

JSON (versi 2013-08-15 dan yang lebih baru)

Berikut ini adalah contoh permintaan dan respons menggunakan JSON.

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

Permintaan dikirim dengan header berikut:

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Permintaan dikirim dengan isi JSON berikut:

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

Setelah permintaan dikirim, respons berikut dikembalikan:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Umpan Atom (versi sebelum 2015-12-11)

Berikut ini adalah contoh permintaan dan respons menggunakan Atom.

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

Permintaan dikirim dengan header berikut:

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

Permintaan dikirim dengan isi XML berikut:

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

Setelah permintaan dikirim, respons berikut dikembalikan:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Keterangan

Operasi Insert Or Replace Entity tidak menggunakan header If-Match dan harus dipanggil menggunakan versi 2011-08-18 atau yang lebih baru. Atribut ini membedakan operasi ini dari operasi Perbarui Entitas .

Insert Or Replace Entity Jika operasi digunakan untuk mengganti entitas, properti apa pun dari entitas sebelumnya akan dihapus jika entitas baru tidak menentukannya. Properti dengan nilai null juga akan dihapus.

Saat memanggil Insert or Replace Entity operasi, Anda harus menentukan nilai untuk PartitionKey properti sistem dan RowKey . Bersama-sama, properti ini membentuk kunci primer dan harus unik dalam tabel.

PartitionKey Nilai dan RowKey harus berupa nilai string; setiap nilai kunci mungkin berukuran hingga 64 KiB. Jika Anda menggunakan nilai bilangan bulat untuk nilai kunci, Anda harus mengonversi bilangan bulat menjadi string lebar tetap, karena diurutkan secara kanonis. Misalnya, Anda harus mengonversi nilai 1 menjadi 0000001 untuk memastikan pengurutan yang tepat.

Untuk mengetik properti secara eksplisit, tentukan jenis data OData yang sesuai dengan mengatur m:type atribut dalam definisi properti di umpan Atom. Untuk informasi selengkapnya tentang mengetik properti, lihat Menyisipkan dan Memperbarui Entitas.

Aplikasi apa pun yang dapat mengotorisasi dan mengirim permintaan HTTP PUT dapat menyisipkan atau mengganti entitas.

Untuk informasi tentang melakukan operasi upsert batch, lihat Melakukan Transaksi Grup Entitas.

Lihat juga

Mengotorisasi permintaan ke Azure Storage
Mengatur Header Versi Layanan Data OData
Menyisipkan dan Memperbarui Entitas
Kode Status dan Kesalahan
Kode Kesalahan Layanan Tabel