Azure Cosmos DB'de kısmi belge güncelleştirmesi

Şunlara uygulanır: ✅ NoSQL

Yama API'si olarak da bilinen Azure Cosmos DB kısmi belge güncelleştirme özelliği, kapsayıcıdaki bir belgeyi değiştirmek için kullanışlı bir yol sağlar. Şu anda, bir belgeyi güncelleştirmek için istemcinin belgeyi okuması, İyimser Eşzamanlılık Denetimi denetimlerini yürütmesi (gerekirse), belgeyi yerel olarak güncelleştirmesi ve ardından belgenin tamamının API'yi değiştir çağrısı olarak kablo üzerinden göndermesi gerekir.

Kısmi belge güncelleştirme özelliği bu deneyimi önemli ölçüde geliştirir. İstemci, tam belge değiştirme işlemi yapmadan yalnızca belgedeki değiştirilmiş özellikleri/alanları gönderebilir. Bu özelliğin başlıca avantajları şunlardır:

Gelişmiş geliştirici üretkenliği: Kullanım kolaylığı ve belgeyi koşullu olarak güncelleştirme olanağı için kullanışlı bir API sağlar.
Performans iyileştirmeleri: İstemci tarafında ek CPU döngülerini önler, uçtan uca gecikme süresini ve ağ bant genişliğini azaltır.
Çok bölgeli yazma işlemleri: Aynı belge içindeki ayrık yollarda kısmi güncelleştirmelerle otomatik ve saydam çakışma çözümlemesini destekler.

Note

Kısmi belge güncelleştirme işlemi JSON Düzeltme Eki RFC'sini temel alır. Yollardaki özellik adlarının ~ ve / karakterlerini sırasıyla ~0 ve ~1 olarak kaçması gerekir.

Örnek bir hedef JSON belgesi:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

JSON Düzeltme Eki belgesi:

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

Sonuçta elde edilen JSON belgesi:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Desteklenen işlemler

Bu tabloda bu özellik tarafından desteklenen işlemler özetlenmektedir.

Note

hedef yol , JSON belgesi içindeki bir konuma başvurur.

İşlem türü	Description
Add	`Add` hedef yola bağlı olarak aşağıdakilerden birini gerçekleştirir: • Hedef yol varolmayan bir öğe belirtirse eklenir. • Hedef yol zaten var olan bir öğeyi belirtirse, değeri değiştirilir. • Hedef yol geçerli bir dizi diziniyse, belirtilen dizindeki diziye yeni bir öğe eklenir. Bu, var olan öğeleri yeni öğeden sonra değiştirir. • Belirtilen dizin dizinin uzunluğuna eşitse, diziye bir öğe ekler. Dizin belirtmek yerine karakterini de kullanabilirsiniz `-` . Ayrıca öğesinin diziye eklenmesiyle sonuçlanır. Not: Dizi uzunluğundan büyük bir dizin belirtilmesi hatayla sonuçlanır.
Set	`Set`, `Add`'den dizi veri türü hariç olmak üzere benzerdir. Hedef yol geçerli bir dizi diziniyse, bu dizindeki mevcut öğe güncelleştirilir.
Replace	`Replace`, `Set`'e, katı değiştirme semantiğine uygun olması dışında benzer. Hedef yol mevcut olmayan bir öğeyi veya diziyi belirtirse hatayla sonuçlanır.
Remove	`Remove` hedef yola bağlı olarak aşağıdakilerden birini gerçekleştirir: • Hedef yol varolmayan bir öğe belirtirse hatayla sonuçlanır. • Hedef yol zaten var olan bir öğeyi belirtiyorsa kaldırılır. • Hedef yol bir dizi diziniyse silinir ve belirtilen dizinin üzerindeki öğeler bir konum geri kaydırılır. Not: Dizi uzunluğuna eşit veya ondan büyük bir dizin belirtmek hataya neden olur.
Increment	Bu işleç, bir alanı belirtilen değere göre artırır. Hem pozitif hem de negatif değerleri kabul edebilir. Alan yoksa, alanı oluşturur ve belirtilen değere ayarlar.
Move	Bu işleç belirtilen bir konumdaki değeri kaldırır ve hedef konuma ekler. İşlem nesnesi, değeri taşımak için hedef belgedeki konuma başvuran bir JSON İşaretçisi değeri içeren bir dize olan "from" üyesini içermelidir. İşlemin başarılı olması için "kaynak" konumu MEVCUT OLMALIDIR. "Yol konumu var olmayan bir nesneyi gösteriyorsa, nesne oluşturur ve değeri 'from' konumundaki değere eşit olarak ayarlar." •"path" konumu daha önce var olan bir nesneyi gösterirse, "path" konumundaki değeri "kaynak" konumundaki değerle değiştirir •"path" özniteliği "from" JSON konumunun JSON alt öğesi olamaz.

Desteklenen modlar

Kısmi belge güncelleştirme özelliği aşağıdaki işlem modlarını destekler. Kod örnekleri için Başlarken belgesine bakın.

Tek belge düzeltme eki: Tek bir belgeye kimliğine ve bölüm anahtarına göre düzeltme eki ekleyebilirsiniz. Tek bir belgede birden çok düzeltme eki işlemi yürütmek mümkündür. En yüksek sınır 10 işlemdir.
Çok belgeli düzeltme eki: Aynı bölüm anahtarındaki birden çok belgeye bir işlemin parçası olarak düzeltme eki uygulanabilir. Bu çok belgeli işlem yalnızca tüm işlemlerin açıklandığı sırayla başarılı olması durumunda işlenir. Herhangi bir işlem başarısız olursa tüm işlem geri alınır.
Koşullu güncelleştirme: Daha önce bahsedilen modlar için, koşulda belirtilen önkoşul karşılanmamışsa işlemin başarısız olması için SQL benzeri bir filtre koşulu (örneğin, from c where c.taskNum = 3) eklemek de mümkündür.
Birden çok belgede bir veya daha fazla düzeltme eki işlemi yürütmek için desteklenen SDK'ların toplu API'lerini de kullanabilirsiniz.

Benzerlikler ve farklılıklar

Desteklenen modlar arasındaki benzerlikleri ve farkları karşılaştıralım.

Ekle ve Belirle

Set işlemi, tüm veri türleri için Add ile benzerdir, ancak Array hariçtir. Add Herhangi bir (geçerli) dizindeki bir işlem, belirtilen dizinde bir öğenin eklenmesine ve dizideki mevcut öğelerin mevcut öğeden sonra kaymasına neden olur. Bu davranış, belirtilen dizindeki mevcut öğeyi güncelleştiren işlemin aksinedir Set .

Ekle ve Değiştir

İşlem Add , henüz yoksa (veri türü dahil) Array bir özellik ekler. Replace özelliği yoksa işlem başarısız olur (veri türü için Array de geçerlidir).

Ayarla ve Değiştir

Set işlemi, henüz yoksa bir özellik ekler (Array varsa hariç). Replace özelliği yoksa işlem başarısız olur (veri türü için Array de geçerlidir).

Note

Replace , kullanıcının bazı özelliklerin her zaman mevcut olmasını beklediği ve bunu onaylamanıza/zorlamanıza izin verdiği iyi bir adaydır.

Kısmi belge güncelleştirmesi için REST API başvurusu

Azure Cosmos DB REST API'si veritabanlarını, belge koleksiyonlarını ve belgeleri oluşturmak, sorgulamak ve silmek için Azure Cosmos DB kaynaklarına programlı erişim sağlar. Bir koleksiyondaki JSON belgelerinde ekleme, değiştirme, silme, okuma, listeleme ve sorgu işlemlerini yürütmeye ek olarak, Kısmi belge güncelleştirme işlemi için HTTP yöntemini kullanabilirsiniz PATCH . Ayrıntılar için Azure Cosmos DB REST API Başvurusu'na bakın.

Örneğin, kısmi belge güncelleştirmesini kullanan bir set işlem için istek şöyle görünür.

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

Belge düzeyi ile yol düzeyi çakışma çözümleme karşılaştırması

Azure Cosmos DB hesabınız birden çok yazma bölgesiyle yapılandırılmışsa, çakışmalar ve çakışma çözümleme ilkeleri belge düzeyinde geçerlidir ve Son Yazma Kazançları (LWW) varsayılan çakışma çözümleme ilkesidir. Kısmi belge güncelleştirmeleri için, birden çok bölgedeki düzeltme eki işlemleri çakışmaları daha ayrıntılı bir yol düzeyinde algılar ve çözer.

Çakışma çözümü bir örnekle daha iyi anlaşılabilir.

Azure Cosmos DB'de aşağıdaki belgeniz olduğunu varsayalım:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Farklı istemciler, farklı bölgelerde eşzamanlı olarak Düzeltme Eki işlemleri gerçekleştirir:

Setplatine atfedilen öznitelik /level
Remove 67890 itibaren /phone

Belge içindeki uyumsuz olmayan yollara Düzeltme Eki istekleri yapıldığından, bu isteklerin çakışmaları otomatik ve şeffaf bir şekilde çözülür (belge düzeyinde Son Yazan Kazanır'ın aksine).

İstemci, çakışma çözümünden sonra aşağıdaki belgeyi görür:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Note

Bir belgenin aynı özelliğinin birden çok bölgede eş zamanlı olarak düzeltme eki uygulanması durumunda, normal çakışma çözümleme ilkeleri uygulanır.

Akışı değiştirme

Azure Cosmos DB'deki değişiklik akışı, tüm değişiklikler için bir kapsayıcıyı dinler ve değiştirilen belgelerin çıktısını alır. Değişiklik akışını kullanarak, hem kısmi hem de tam belge güncelleştirmeleri dahil olmak üzere belgelerde yapılan tüm güncelleştirmeleri görürsünüz. Değişiklik akışındaki öğeleri işlerken, güncelleştirme bir düzeltme eki işleminin sonucu olsa bile belgenin tamamı döndürülür.

Azure Cosmos DB'deki değişiklik akışı hakkında daha fazla bilgi için bkz . Azure Cosmos DB'de değişiklik akışı.

Sonraki Adımlar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-04

Aracılığıyla paylaş

Azure Cosmos DB'de kısmi belge güncelleştirmesi

Desteklenen işlemler

Desteklenen modlar

Benzerlikler ve farklılıklar

Ekle ve Belirle

Ekle ve Değiştir

Ayarla ve Değiştir

Kısmi belge güncelleştirmesi için REST API başvurusu

Belge düzeyi ile yol düzeyi çakışma çözümleme karşılaştırması

Akışı değiştirme

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar