Sisipkan atau Gabungkan Entitas

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

Permintaan Insert Or Merge 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
MERGE 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
MERGE 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 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 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 Merge Entity mengirimkan entitas untuk dimasukkan sebagai kumpulan entitas OData, yang mungkin 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 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.

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 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 kata kerja MERGE dan harus dipanggil menggunakan versi 2011-08-18 atau yang lebih baru. Selain itu, ia tidak menggunakan header If-Match. Atribut ini membedakan operasi ini dari Update Entity operasi, meskipun isi permintaan sama untuk kedua operasi.

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

Saat 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 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 ke 0000001 untuk memastikan pengurutan yang tepat.

Untuk mengetik properti secara eksplisit, tentukan jenis 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 MERGE 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 Kesalahan
Kode Kesalahan Layanan Tabel