JavaScript için Azure Cosmos DB istemci kitaplığı - sürüm 4.0.0

Makale
09/13/2023

/TypeScript

Azure Cosmos DB, belge, anahtar-değer, geniş sütun ve graf veritabanlarını destekleyen, global olarak dağıtılmış çok modelli bir veritabanı hizmetidir. Bu paket, JavaScript/TypeScript uygulamalarının SQL API veritabanları ve içerdikleri JSON belgeleriyle etkileşim kurmasına yöneliktir:

Cosmos DB veritabanları oluşturma ve ayarlarını değiştirme
JSON belge koleksiyonlarını depolamak için kapsayıcı oluşturma ve değiştirme
Kapsayıcılarınızdaki öğeleri (JSON belgeleri) oluşturma, okuma, güncelleştirme ve silme
SQL benzeri söz dizimini kullanarak veritabanınızdaki belgeleri sorgulama

Önemli bağlantılar:

Başlarken

Önkoşullar

Azure Aboneliği ve Cosmos DB SQL API Hesabı

Bu paketi kullanmak için bir Azure Aboneliğiniz ve cosmos DB hesabınız (SQL API) olmalıdır.

Cosmos DB SQL API hesabına ihtiyacınız varsa azure Cloud Shell kullanarak şu Azure CLI komutuyla bir hesap oluşturabilirsiniz:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

Ya da Azure Portal'da hesap oluşturabilirsiniz

NodeJS

Bu paket NodeJS ile önceden yüklenmiş olarak gelen npm aracılığıyla dağıtılır. Node v10 veya üzerini kullanıyor olmanız gerekir.

CORS

Tarayıcılar için geliştirmeniz gerekiyorsa Cosmos DB hesabınız için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) kuralları ayarlamanız gerekir. Cosmos DB'niz için yeni CORS kuralları oluşturmak için bağlantılı belgedeki yönergeleri izleyin.

Bu paketi yükle

npm install @azure/cosmos

Hesap Kimlik Bilgilerini Alma

Cosmos DB Hesap Uç Noktanız ve Anahtarınız gerekir. Bunları Azure Portal'da bulabilir veya aşağıdaki Azure CLI kod parçacığını kullanabilirsiniz. Kod parçacığı Bash kabuğu için biçimlendirilir.

az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv

Örneğini oluşturma `CosmosClient`

Cosmos DB ile etkileşim , CosmosClient sınıfının bir örneğiyle başlar

const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

async function main() {
  // The rest of the README samples are designed to be pasted into this function body
}

main().catch((error) => {
  console.error(error);
});

Kolaylık olması için ve endpoint öğesini doğrudan koda dahil key ettik ancak dotenv gibi bir proje kullanarak veya ortam değişkenlerinden yükleme gibi bir proje kullanarak bunları kaynak denetiminde olmayan bir dosyadan yüklemek isteyebilirsiniz

Üretim ortamlarında anahtarlar gibi gizli diziler Azure Key Vault

Önemli kavramlar

CosmosClient'ı başlatdıktan sonra, Cosmos DB'deki birincil kaynak türleriyle etkileşim kurabilirsiniz:

Veritabanı: Cosmos DB hesabı birden çok veritabanı içerebilir. Bir veritabanı oluşturduğunuzda, belgeleriyle etkileşim kurarken kullanmak istediğiniz API'yi belirtirsiniz: SQL, MongoDB, Gremlin, Cassandra veya Azure Tablosu. Kapsayıcılarını yönetmek için Veritabanı nesnesini kullanın.
Kapsayıcı: Kapsayıcı, JSON belgelerinden oluşan bir koleksiyondur. Kapsayıcı nesnesindeki yöntemleri kullanarak kapsayıcıdaki öğeleri oluşturur (ekler), okur, güncelleştirir ve silersiniz.
Öğe: Öğe, kapsayıcıda depolanan bir JSON belgesidir. Her Öğe, kapsayıcı içindeki öğeyi benzersiz olarak tanımlayan bir değere sahip bir anahtar içermelidir id . sağlamazsanız idSDK otomatik olarak bir tane oluşturur.

Bu kaynaklar hakkında daha fazla bilgi için bkz. Azure Cosmos veritabanları, kapsayıcıları ve öğeleriyle çalışma.

Örnekler

Aşağıdaki bölümlerde, en yaygın Cosmos DB görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Veritabanı oluşturma
Kapsayıcı oluşturma
Bölüm Anahtarlarını Kullanma
Öğe ekleme
Belgeleri sorgulama
Öğe okuma
Öğeyi silme
Hiyerarşik bölüm anahtarıyla Kapsayıcıda CRUD

Veritabanı oluşturma

CosmosClient'ınızın kimliğini doğruladıktan sonra hesaptaki herhangi bir kaynakla çalışabilirsiniz. Aşağıdaki kod parçacığı bir NOSQL API veritabanı oluşturur.

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);

Kapsayıcı oluşturma

Bu örnek, varsayılan ayarlarla bir kapsayıcı oluşturur

const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);

Bölüm Anahtarlarını Kullanma

Bu örnekte desteklenen çeşitli bölüm Anahtarları türleri gösterilmektedir.

await container.item("id", "1").read();        // string type
await container.item("id", 2).read();          // number type
await container.item("id", true).read();       // boolean type
await container.item("id", {}).read();         // None type
await container.item("id", undefined).read();  // None type
await container.item("id", null).read();       // null type

Bölüm Anahtarı tek bir değerden oluşuyorsa, değişmez değer veya dizi olarak sağlanabilir.

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

Bölüm Anahtarı birden fazla değerden oluşuyorsa, bir dizi olarak sağlanmalıdır.

await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();

Öğe ekleme

Kapsayıcıya öğe eklemek için verilerinizi içeren bir nesneyi Items.upsert dosyasına geçirin. Azure Cosmos DB hizmeti her öğenin bir id anahtarı olmasını gerektirir. Sağlamazsanız SDK otomatik olarak bir id oluşturur.

Bu örnek kapsayıcıya birkaç öğe ekler

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
  await container.items.create(city);
}

Öğe okuma

Kapsayıcıdan tek bir öğeyi okumak için Item.read kullanın. Bu, sql idkullanarak tarafından sorgulandığından daha ucuz bir işlemdir.

await container.item("1", "1").read();

Hiyerarşik bölüm anahtarıyla Kapsayıcıda CRUD

Hiyerarşik bölüm anahtarıyla Kapsayıcı oluşturma

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

Hiyerarşik bölüm anahtarı olarak tanımlanan bir öğe ekleme - ["/name", "/address/zip"]

const item = {
  id: 1,
  name: 'foo',
  address: {
    zip: 100
  },
  active: true
}
await container.items.create(item);

Hiyerarşik bölüm anahtarı olarak tanımlanan bir kapsayıcıdan tek bir öğeyi okumak için - ["/name", "/address/zip"],

await container.item("1", ["foo", 100]).read();

Hiyerarşik bölüm anahtarı ile öğeyi sorgulama ve hiyerarşik bölüm anahtarı - ["/name", "/address/zip"],

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
          partitionKey: ["foo", 100],
        })
  .fetchAll();
for (const item of resources) {
  console.log(`${item.name}, ${item.address.zip} `);
}

Öğeyi silme

Kapsayıcıdaki öğeleri silmek için Item.delete kullanın.

// Delete the first item returned by the query above
await container.item("1").delete();

Veritabanını sorgulama

Cosmos DB SQL API veritabanı, SQL benzeri söz dizimini kullanarak Items.query ile kapsayıcıdaki öğelerin sorgulanması destekler:

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

Parametreleri ve değerlerini içeren bir nesneyi Items.query'ye geçirerek parametreli sorgular gerçekleştirin:

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }]
  })
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

SQL API'sini kullanarak Cosmos DB veritabanlarını sorgulama hakkında daha fazla bilgi için bkz. SQL sorguları ile Azure Cosmos DB verilerini sorgulama.

Değişiklik Akışı Çekme Modeli

Değişiklik akışı bir bölüm anahtarı, akış aralığı veya kapsayıcının tamamı için getirilebilir.

Değişiklik akışını işlemek için bir örneği ChangeFeedPullModelIteratoroluşturun. başlangıçta oluşturduğunuzdaChangeFeedPullModelIterator, içinde ChangeFeedIteratorOptions hem değişiklikleri okumak için başlangıç konumunu hem de değişikliklerin getirileceği kaynağı (bölüm anahtarı veya FeedRange) içeren gerekli changeFeedStartFrom bir değer belirtmeniz gerekir. sayfa başına alınan en fazla öğe sayısını ayarlamak için isteğe bağlı olarak içinde ChangeFeedIteratorOptions kullanabilirsinizmaxItemCount.

Not: Hiçbir değer belirtilmezse changeFeedStartFrom , Now() içinden kapsayıcının tamamı için değişiklik akışı getirilir.

Değişiklik akışı için dört başlangıç konumu vardır:

Beginning

// Signals the iterator to read changefeed from the beginning of time.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning();
}
const iterator = container.getChangeFeedIterator(options);

Time

// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11") // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time);
}

Now

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now();
}

Continuation

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken);
}

Aşağıda bölüm anahtarı için değişiklik akışını getirme örneği verilmiştir

const partitionKey = "some-partition-Key-value";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
  const response = await iterator.readNext();
  // process this response
}

Değişiklik akışı, gelecekteki tüm yazma ve güncelleştirmeleri kapsayan sonsuz bir öğe listesi olduğundan, değeri hasMoreResults her zaman trueolur. Değişiklik akışını okumaya çalıştığınızda ve kullanılabilir yeni bir değişiklik olmadığında, durum bilgisi olan NotModified bir yanıt alırsınız.

Daha ayrıntılı kullanım yönergeleri ve değişiklik akışı örnekleri burada bulunabilir.

Hata İşleme

SDK, bir işlem sırasında oluşabilecek çeşitli hata türleri oluşturur.

ErrorResponse bir işlemin yanıtı =400 hata kodu >döndürürse oluşturulur.
TimeoutError zaman aşımı nedeniyle Abort dahili olarak çağrılırsa oluşturulur.
AbortError , herhangi bir kullanıcı başarılı sinyalinin iptale neden olması durumunda oluşturulur.
RestError ağ sorunlarından dolayı temel alınan sistem çağrısının başarısız olması durumunda oluşturulur.
Herhangi bir devDependencies tarafından oluşturulan hatalar. Örneğin, @azure/identity paket atabilir CredentialUnavailableError.

Aşağıda, , , TimeoutErrorAbortErrorve tür ErrorResponsehatalarını işlemeye yönelik bir örnek verilmiştirRestError.

try {
  // some code
} catch (err) {
  if (err instanceof ErrorResponse) {
    // some specific error handling.
  } else if (err instanceof RestError) {
    // some specific error handling.
  }
  // handle other type of errors in similar way.
  else {
    // for any other error.
  }
}

Uygulamanızın hatalardan düzgün bir şekilde kurtulabileceğinden ve beklendiği gibi çalışmaya devam ettiğinden emin olmak için bu hataları düzgün bir şekilde işlemek önemlidir. Bu hatalardan bazıları ve olası çözümleri hakkında daha fazla ayrıntıya buradan ulaşabilirsiniz.

Sorun giderme

Genel

Hizmet tarafından döndürülen Cosmos DB hatalarıyla etkileşim kurarken REST API istekleri için döndürülen http durum kodlarıyla aynı olur:

Azure Cosmos DB için HTTP Durum Kodları

Çakışmalar

Örneğin, Cosmos DB veritabanınızda zaten kullanımda olan bir id öğeyi kullanarak bir öğe oluşturmaya çalışırsanız, çakışmayı belirten bir 409 hata döndürülür. Aşağıdaki kod parçacığında hata, özel durum yakalanarak ve hata hakkında ek bilgiler görüntülenerek düzgün bir şekilde işlenir.

try {
  await containers.items.create({ id: "existing-item-id" });
} catch (error) {
  if (error.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Dönüştürme

Azure SDK'ları ES5 JavaScript söz dizimini ve Node.jsLTS sürümlerini destekleyecek şekilde tasarlanmıştır. Internet Explorer veya Node 6 gibi önceki JavaScript çalışma zamanları için desteğe ihtiyacınız varsa, derleme işleminizin bir parçası olarak SDK kodunu dönüştürmeniz gerekir.

Yeniden denemelerle geçici hataları işleme

Cosmos DB ile çalışırken hizmet tarafından uygulanan hız sınırları veya ağ kesintileri gibi diğer geçici sorunlardan kaynaklanan geçici hatalarla karşılaşabilirsiniz. Bu tür hataları işleme hakkında bilgi için Bulut Tasarım Desenleri kılavuzundaki yeniden deneme düzeni ve ilgili Devre Kesici düzeni bölümüne bakın.

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir. kullanırken AZURE_LOG_LEVEL , günlük kitaplığı başlatılmadan önce ayarladığınızdan emin olun. Bu tür kitaplıkların günlük kitaplığından önce başlatıldığından emin olmak gibi dotenv kitaplıklar kullanıyorsanız, bunu komut satırından geçirmek idealdir.

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Tanılama

Cosmos Tanılama özelliği, tüm istemci işlemlerinizle ilgili gelişmiş içgörüler sağlar. Tüm istemci işlemlerinin yanıtına bir CosmosDiagnostics nesnesi eklenir. Gibi

Nokta arama işlemi reponse - item.read(), container.create(), database.delete()
Sorgu işlemi reponse -queryIterator.fetchAll(),
Toplu ve Toplu İşlemler -item.batch().
Hata/Özel durum yanıtı nesneleri.

Tüm istemci işlemlerinin yanıtına bir CosmosDiagnostics nesnesi eklenir. 3 Cosmos Tanılama düzeyi, bilgi, hata ayıklama ve hata ayıklama güvenli değildir. Yalnızca üretim sistemleri için bilgiler, önemli ölçüde daha yüksek kaynaklar kullandıklarından, geliştirme ve hata ayıklama sırasında hata ayıklama ve hata ayıklama güvenli olmayan bilgilerin kullanılması amaçlanır. Cosmos Tanılama düzeyi 2 şekilde ayarlanabilir

Programatically

  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });

Ortam değişkenlerini kullanma. (Ortam değişkeni tarafından ayarlanan tanılama düzeyi, istemci seçenekleri aracılığıyla ayarlamaya göre daha yüksek önceliğe sahiptir.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic'in üç üyesi vardır

ClientSideRequestStatistics Türü: Meta veri aramaları, yeniden denemeler, bağlantı kurulan uç noktalar ve yük boyutu ve süresi gibi istek ve yanıt istatistikleri dahil olmak üzere tanılama ayrıntılarını toplar. (her zaman toplanır, üretim sistemlerinde kullanılabilir.)
DiagnosticNode: Ayrıntılı tanılama bilgilerini yakalayan ağaç benzeri bir yapıdır. Tarayıcılarda mevcut kaydına har benzer. Bu özellik varsayılan olarak devre dışıdır ve yalnızca üretim dışı ortamlarda hata ayıklamaya yöneliktir. (tanılama düzeyinde toplanan hata ayıklama ve güvenli olmayan hata ayıklama)
ClientConfig: İstemci başlatma sırasında istemcinin yapılandırma ayarlarıyla ilgili temel bilgileri yakalar. (tanılama düzeyinde toplanan hata ayıklama ve güvenli olmayan hata ayıklama)

Bu düzey CosmosDiagnostics istek ve yanıt yüklerini yakaladığından ve günlüğe debug-unsafe kaydetmeyi seçerseniz (varsayılan olarak düzey tarafından @azure/loggerverbose günlüğe kaydedilir) üretim ortamında tanılama düzeyini hiçbir zaman olarak ayarlamadığınızdan emin olun. Bu yükler günlük havuzlarınızda yakalanabilir.

TanılamaYı Kullanma

Çünkü diagnostics tüm Yanıt nesnelerine eklenir. Program aracılığıyla aşağıdaki gibi erişebilirsiniz CosmosDiagnostic .

  // For point look up operations
  const { container, diagnostics: containerCreateDiagnostic } =
    await database.containers.createIfNotExists({
      id: containerId,
      partitionKey: {
        paths: ["/key1"],
      },
  });

  // For Batch operations
   const operations: OperationInput[] = [
    {
      operationType: BulkOperationType.Create,
      resourceBody: { id: 'A', key: "A", school: "high" },
    },
  ];
  const response = await container.items.batch(operations, "A"); 
  
  // For query operations
  const queryIterator = container.items.query("select * from c");
  const { resources, diagnostics } = await queryIterator.fetchAll();

  // While error handling
  try {
    // Some operation that might fail
  } catch (err) {
    const diagnostics = err.diagnostics
  }

kullanarak da oturum açabilirsiniz diagnostics@azure/logger. Tanılama her zaman düzeyinde verbose kullanılarak @azure/logger günlüğe kaydedilir. Bu nedenle, Tanılama düzeyini debug veya debug-unsafe ve @azure/logger düzeyini olarak ayarlarsanız günlüğe verbosediagnostics kaydedilir.

Sonraki adımlar

Daha fazla örnek kod

SDK'nın GitHub deposunda kullanabileceğiniz çeşitli örnekler vardır. Bu örnekler Cosmos DB ile çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

Veritabanı İşlemleri
Kapsayıcı İşlemleri
Öğe İşlemleri
Dizin Oluşturmayı Yapılandırma
Kapsayıcı Değişiklik Akışını okuma
Saklı Yordamlar
Veritabanı/Kapsayıcı aktarım hızı ayarlarını değiştirme
Çok Bölgeli Yazma İşlemleri

Sınırlamalar

Şu anda aşağıdaki özellikler desteklenmiyor. Alternatif seçenekler için aşağıdaki Geçici çözümler bölümüne bakın.

Veri Düzlemi Sınırlamaları:

DISTINCT alt sorgusundan COUNT içeren sorgular
Doğrudan TCP Modu erişimi
Sıralama, sayma ve ayrı gibi bölümler arası sorguları toplama, devamlılık belirteçlerini desteklemez. SELECT * FROM gibi akışla aktarılabilir sorgular WHERE , devamlılık belirteçlerini destekler. Devamlılık belirteci olmadan akışla aktarılamayan sorguları yürütmek için "Geçici Çözüm" bölümüne bakın.
Değişiklik Akışı: İşlemci
Değişiklik Akışı: Birden çok bölüm anahtarı değerini okuma
Değişiklik Akışı çekme modeli tüm sürümler ve silme modu #27058
Kısmi hiyerarşik bölüm anahtarları için Değişiklik Akışı çekme modeli desteği #27059
Karma türler için bölümler arası ORDER BY

Denetim Düzlemi Sınırlamaları:

CollectionSizeUsage, DatabaseUsage ve DocumentUsage ölçümlerini alma
Jeo-uzamsal dizin oluşturma
Otomatik Ölçeklendirme aktarım hızını güncelleştirme

Geçici Çözümler

Bölümler arası sorgular için devamlılık belirteci

Yan araç desenini kullanarak devamlılık belirteci desteği ile çapraz bölüm sorguları elde edebilirsiniz. Bu düzen aynı zamanda uygulamaların heterojen bileşenlerden ve teknolojilerden oluşmasına da olanak tanır.

Seri olmayan bölümler arası sorgu yürütme

Devamlılık belirteçleri kullanmadan akışla aktarılamayan sorgular yürütmek için, gerekli sorgu belirtimi ve seçenekleriyle bir sorgu yineleyicisi oluşturabilirsiniz. Aşağıdaki örnek kod, devamlılık belirtecine gerek kalmadan tüm sonuçları getirmek için sorgu yineleyicisinin nasıl kullanılacağını gösterir:

const querySpec = {
  query: "SELECT * FROM c WHERE c.status = @status",
  parameters: [{ name: "@status", value: "active" }],
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

Bu yaklaşım akışla aktarılabilir sorgular için de kullanılabilir.

Kontrol Düzlemi işlemleri

Genellikle, desteklenmeyen sınırlamalar için Azure Portal, Azure Cosmos DB Kaynak Sağlayıcısı REST API'sini, Azure CLI'yı veya PowerShell'i kullanabilirsiniz.

Diğer belgeler

Cosmos DB hizmetiyle ilgili daha kapsamlı belgeler için docs.microsoft.com ile ilgili Azure Cosmos DB belgelerine bakın.

Yararlı bağlantılar

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

İzlenimler