Varlık Ekleme veya Birleştirme

Makale
05/04/2024

İşlem Insert Or Merge Entity var olan bir varlığı güncelleştirir veya tabloda yoksa yeni bir varlık ekler. Bu işlem bir varlığı ekleyebileceğinden veya güncelleştirebileceğinden, upsert işlemi olarak da bilinir.

İstek

İsteği aşağıdaki gibi oluşturabilirsiniz Insert Or Merge Entity . HTTPS önerilir. Aşağıdaki değerleri kendi değerlerinizle değiştirin:

myaccount depolama hesabınızın adıyla
mytable tablonuzun adıyla
myPartitionKey ve myRowKey güncelleştirilecek varlık için bölüm anahtarının ve satır anahtarının adıyla

Yöntem	İstek URI'si	HTTP sürümü
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Öykünülmüş depolama hizmeti

Öykünülen depolama hizmetine yönelik istekte bulunurken öykünücü konak adını ve Azure Tablo Depolama bağlantı noktasını 127.0.0.1:10002 olarak ve ardından öykünülen depolama hesabı adını belirtin.

Yöntem	İstek URI'si	HTTP sürümü
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Depolama öykünücüsü içindeki Tablo Depolama, Azure Tablo Depolama'dan çeşitli yollarla farklıdır. Daha fazla bilgi için bkz . Depolama öykünücüsü ile Azure Depolama hizmetleri arasındaki farklar.

URI parametreleri

İstek URI'sinde aşağıdaki ek parametreyi belirtebilirsiniz.

Parametre	Açıklama
`timeout`	İsteğe bağlı. `timeout` parametresi saniye cinsinden ifade edilir. Daha fazla bilgi için bkz . Tablo Depolama işlemleri için zaman aşımlarını ayarlama.

İstek üst bilgileri

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.

İstek üst bilgisi	Açıklama
`Authorization`	Gereklidir. Yetkilendirme düzenini, hesap adını ve imzayı belirtir. Daha fazla bilgi için bkz. Azure Depolama isteklerini yetkilendirme.
`Date` veya `x-ms-date`	Gereklidir. İstek için Eşgüdümlü Evrensel Saat (UTC) biçimini belirtir. Daha fazla bilgi için bkz. Azure Depolama isteklerini yetkilendirme.
`x-ms-version`	Gereklidir. 2011-08-18 veya üzeri olarak ayarlanmalıdır. Bu istek için kullanılacak işlemin sürümünü belirtir. Daha fazla bilgi için bkz. Azure Depolama hizmetleri için sürüm oluşturma.
`Content-Type`	Gereklidir. Yükün içerik türünü belirtir. Olası değerler ve `application/json`değerleridir`application/atom+xml`. Geçerli içerik türleri hakkında daha fazla oluşum için bkz. Tablo Depolama işlemleri için Yük biçimi.
`Content-Length`	Gereklidir. İstek gövdesinin uzunluğu.
`x-ms-client-request-id`	İsteğe bağlı. Günlüğe kaydetme yapılandırıldığında günlüklere kaydedilen 1 kibibaytlık (KiB) karakter sınırıyla istemci tarafından oluşturulan, opak bir değer sağlar. İstemci tarafı etkinlikleriyle sunucunun aldığı istekler arasında bağıntı sağlamak için bu üst bilgiyi kullanmanızı kesinlikle öneririz. Daha fazla bilgi için bkz. Azure Tablo Depolama'yı izleme.

İstek gövdesi

İşlem, Insert Or Merge Entity varlık kümesi olarak OData eklenecek varlığı gönderir. Bu varlık kümesi bir Atom veya JSON yükü olabilir. Daha fazla bilgi için bkz. Varlık ekleme ve güncelleştirme.

Not

JSON önerilen yük biçimidir ve sürüm 2015-12-11 ve üzeri için desteklenen tek biçimdir.

Yanıt

Yanıt bir HTTP durum kodu ve yanıt üst bilgileri kümesi içerir.

Durum kodu

Başarılı bir işlem 204 (No Content durum kodunu döndürür. Durum kodları hakkında bilgi için bkz . Durum ve hata kodları ve Tablo Depolama hata kodları.

Yanıt üst bilgileri

Yanıt aşağıdaki üst bilgileri içerir. Yanıt ek, standart HTTP üst bilgileri de içerebilir. Tüm standart üst bilgiler HTTP/1.1 protokol belirtimine uygundur.

Yanıt üst bilgisi	Description
`ETag`	`ETag` Varlığın için.
`x-ms-request-id`	Yapılan isteği benzersiz olarak tanımlar ve istekle ilgili sorunları gidermek için kullanılabilir. Daha fazla bilgi için bkz. API işlemleriyle ilgili sorunları giderme.
`x-ms-version`	İsteği çalıştırmak için kullanılan Tablo Depolama sürümünü gösterir. Bu üst bilgi, 2009-09-19 ve sonraki sürümlerde yapılan istekler için döndürülür.
`Date`	Yanıtın başlatıldığı saati gösteren utc tarih/saat değeri. Hizmet bu değeri oluşturur.
`x-ms-client-request-id`	İsteklerin ve karşılık gelen yanıtların sorunlarını gidermek için kullanılabilir. Bu üst bilginin değeri, istekte varsa üst bilginin değerine `x-ms-client-request-id` eşittir. Değer en fazla 1.024 görünür ASCII karakterdir. `x-ms-client-request-id` Üst bilgi istekte yoksa yanıtta bulunmaz.

Yanıt gövdesi

Yok.

Yetkilendirme

Hesap sahibi bu işlemi gerçekleştirebilir. Ayrıca, bu işlemi gerçekleştirme iznine sahip paylaşılan erişim imzasına sahip herkes bunu yapabilir.

Örnek istek ve yanıt

Aşağıdaki örneklerde JSON ve Atom akışlarını kullanan örnek istekler gösterilmektedir.

Not

JSON önerilen yük biçimidir ve sürüm 2015-12-11 ve üzeri için desteklenen tek biçimdir.

JSON (sürüm 2013-08-15 ve üzeri)

Aşağıda JSON kullanan örnek bir istek ve yanıt verilmiştir.

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

İstek aşağıdaki üst bilgilerle gönderilir:

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

İstek aşağıdaki JSON gövdesiyle gönderilir:

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

İstek gönderildikten sonra aşağıdaki yanıt döndürülür:

  
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

Atom akışı (2015-12-11 öncesi sürümler)

Atom kullanan örnek bir istek ve yanıt aşağıda verilmiştir:

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

İstek aşağıdaki üst bilgilerle gönderilir:

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

İstek aşağıdaki XML gövdesiyle gönderilir:

<?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>

İstek gönderildikten sonra aşağıdaki yanıt döndürülür:

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

Açıklamalar

İşlem Insert Or Merge Entity fiilini MERGE kullanır. 2011-08-18 veya sonraki bir sürümünü kullanarak işlemi çağırmanız gerekir. Ayrıca, bu işlem üst bilgiyi kullanmaz If-Match . Bu öznitelikler bu işlemi işlemden Update Entity ayırır, ancak istek gövdesi her iki işlem için de aynıdır.

bir varlığı birleştirmek için işlemini kullanırsanız Insert Or Merge Entity , isteğin tanımlamadığı veya içermediği bir önceki varlığa ait tüm özellikler korunur. Değeri olan null özellikler de korunur.

işlemini çağırdığınızda Insert or Merge Entity ve RowKey sistem özellikleri için PartitionKey değerler belirtmeniz gerekir. Bu özellikler birlikte birincil anahtarı oluşturur ve tablo içinde benzersiz olmalıdır.

PartitionKey Hem hem de RowKey değerleri dize değerleri olmalıdır. PartitionKey ve RowKey değerlerinin boyutu en çok 1024 karakter olabilir. Anahtar değeri için bir tamsayı değeri kullanıyorsanız, tamsayıyı sabit genişlikli bir dizeye dönüştürmeniz gerekir. Bunun nedeni, bunların anonim olarak sıralanmış olmasıdır. Örneğin, doğru sıralamayı sağlamak için 0000001 değerini 1 değerine dönüştürün.

Bir özelliği açıkça yazmak için, Atom akışındaki özellik tanımı içinde özniteliğini ayarlayarak m:type uygun OData türü belirtin. Yazma özellikleri hakkında daha fazla bilgi için bkz. Varlık ekleme ve güncelleştirme.

Bir isteği yetkilendirilebilen ve gönderebilen HTTP MERGE tüm uygulamalar varlık ekleyebilir veya güncelleştirebilir.

Toplu upsert işlemlerini gerçekleştirme hakkında bilgi için bkz. Varlık grubu işlemleri gerçekleştirme.

Ayrıca bkz.

Azure Depolama'ya yönelik istekleri yetkilendirme
OData veri hizmeti sürüm üst bilgilerini ayarlama
Varlıkları ekleme ve güncelleştirme
Durum ve hata kodları
Tablo Depolama hata kodları