Varlık Ekleme veya Değiştirme

Makale
06/27/2023

İşlem Insert Or Replace Entity var olan bir varlığın yerini alır veya tabloda yoksa yeni bir varlık ekler. Bu işlem bir varlığı ekleyebileceğinden veya güncelleştirebildiğinden , upsert işlemi olarak da bilinir.

İstek

İsteği aşağıdaki gibi oluşturabilirsiniz Insert Or Replace 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ığın bölüm anahtarı ve satır anahtarı adıyla

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

Öykünülmüş depolama hizmeti

Öykünülmüş depolama hizmetine yönelik bir 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ü
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Depolama öykünücüsündeki 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'ya istekleri 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'ya istekleri 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 formasyon 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 kibibayt (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 Replace Entity varlık kümesi olarak OData eklenecek varlığı gönderir. Bu varlık kümesi bir JSON veya Atom akışı 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 bir dizi yanıt üst bilgisi içerir.

Durum kodu

Başarılı bir işlem 204 (İçerik Yok) 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 istek sorunlarını 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`	İsteklerde ve karşılık gelen yanıtlarda sorun 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. İstekte `x-ms-client-request-id` üst bilgi 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 izni olan 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österilir.

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.

PUT 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)

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

PUT 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='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>

İ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 Replace Entity üst bilgisini kullanmaz If-Match . Bu işlemi 2011-08-18 veya sonraki bir sürümünü kullanarak çağırmanız gerekir. Bu öznitelikler bu işlemi Varlığı Güncelleştir işleminden ayırır.

Bir varlığı değiştirmek için işlemini kullanırsanız Insert Or Replace Entity , yeni varlık bunları tanımlamazsa, önceki varlıktan tüm özellikler kaldırılır. Değer içeren null özellikler de kaldırılır.

İşlemi çağırdığınızda Insert or Replace Entity ve RowKey sistem özellikleri için PartitionKey değerleri belirtmeniz gerekir. Bu özellikler birlikte birincil anahtarı oluşturur ve tabloda benzersiz olmalıdır.

PartitionKey Hem hem de RowKey değerleri dize değerleri olmalıdır. PartitionKey ve RowKey değerleri en çok 1024 karakter uzunluğunda 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 eş anlamlı olarak sıralanmış olmasıdır. Örneğin, doğru sıralamayı sağlamak için değerini 10000001değ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 veri türünü belirtin. Yazma özellikleri hakkında daha fazla bilgi için bkz. Varlıkları ekleme ve güncelleştirme.

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

Toplu upsert işlemleri 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ı