Sisipkan atau Gabungkan Entitas

Artikel
06/27/2023

Operasi memperbarui Insert Or Merge Entity 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

Anda dapat membuat Insert Or Merge Entity permintaan 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
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Layanan penyimpanan yang ditimulasikan

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

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

Table Storage di emulator Storage berbeda dari Azure Table Storage dalam beberapa cara. Untuk informasi selengkapnya, lihat Perbedaan antara emulator Storage dan layanan Azure Storage.

Parameter URI

Anda dapat menentukan parameter tambahan berikut pada URI permintaan.

Parameter	Deskripsi
`timeout`	Opsional. Parameter `timeout` dinyatakan dalam hitung detik. Untuk informasi selengkapnya, lihat Mengatur batas waktu untuk operasi Table Storage.

Header permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Meminta kop	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`	Wajib diisi. 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 Table Storage.
`Content-Length`	Wajib diisi. Panjang isi permintaan.
`x-ms-client-request-id`	Opsional. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 kibibyte (KiB) yang dicatat dalam log saat pengelogan dikonfigurasi. Kami sangat menyarankan Anda menggunakan header ini untuk menghubungkan aktivitas sisi klien dengan permintaan yang diterima server. Untuk informasi selengkapnya, lihat Memantau Azure Table Storage.

Isi permintaan

Operasi Insert Or Merge Entity mengirimkan entitas untuk dimasukkan sebagai OData set entitas. Kumpulan entitas ini dapat berupa payload Atom atau JSON. 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 (No Content). Untuk informasi tentang kode status, lihat Kode status dan kesalahan, dan kode kesalahan Table Storage.

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`	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 Table Storage 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 menunjukkan waktu di mana respons dimulai. Layanan menghasilkan nilai ini.
`x-ms-client-request-id`	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. Nilainya paling banyak 1.024 karakter ASCII yang terlihat. `x-ms-client-request-id` Jika header tidak ada dalam permintaan, header tidak akan ada dalam respons.

Isi Respons

Tidak ada.

Authorization

Pemilik akun dapat melakukan operasi ini. Selain itu, siapa pun dengan tanda tangan akses bersama yang memiliki izin untuk melakukan operasi ini dapat melakukannya.

Sampel permintaan dan respons

Contoh berikut menunjukkan contoh permintaan yang 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 yang menggunakan JSON.

MERGE 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 yang menggunakan Atom:

MERGE 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='myrowkey')</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 ini Insert Or Merge Entity menggunakan MERGE kata kerja. Anda harus memanggil operasi dengan menggunakan versi 2011-08-18 atau yang lebih baru. Selain itu, operasi ini tidak menggunakan If-Match header . Atribut ini membedakan operasi ini dari Update Entity operasi, meskipun isi permintaan sama untuk kedua operasi.

Jika Anda menggunakan Insert Or Merge Entity operasi untuk menggabungkan entitas, properti apa pun dari entitas sebelumnya akan dipertahankan, jika permintaan tidak menentukan atau menyertakannya. Properti dengan null nilai juga dipertahankan.

Saat Anda memanggil Insert or Merge 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 dapat berukuran hingga 64 KiB. Jika Anda menggunakan nilai bilangan bulat untuk nilai kunci, Anda harus mengonversi bilangan bulat menjadi string lebar tetap. Ini karena mereka diurutkan secara kanonis. Misalnya, konversikan nilai 1 ke untuk 0000001 memastikan pengurutan yang tepat.

Untuk mengetik properti secara eksplisit, tentukan jenis yang sesuai OData 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 HTTP MERGE permintaan dapat menyisipkan atau memperbarui 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
Status dan kode galat
Kode kesalahan Table Storage