Aracılığıyla paylaş

Azure Cosmos DB client library for JavaScript - version 4.9.0

/TypeScript

Derleme Durumuen son npm rozetini

Azure Cosmos DB, belge, anahtar-değer, geniş sütun ve graf veritabanlarını destekleyen genel 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ğive bir Cosmos DB hesabı (SQL API) olmalıdır.

Cosmos DB SQL API hesabına ihtiyacınız varsa, şu Azure CLI komutuyla bir hesap oluşturmak için Azure Cloud Shell kullanabilirsiniz:

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

İsterseniz azure portal bir hesap oluşturabilirsiniz

DüğümJS

Bu paket, bir LTS sürümü kullanılarak NodeJS önceden yüklenmiş olarak gelen npm aracılığıyla dağıtılır.

Kaynaklar Arası Paylaşım (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ç Noktası ve Anahtargerekir. Bunları Azure Portal bulabilir veya aşağıdaki Azure CLI 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

CosmosClient örneği oluşturma

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

import { CosmosClient } from "@azure/cosmos";

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

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

Üretim ortamlarında anahtarlar gibi gizli diziler Azure Key Vault'ta depolanmalıdır

Temel kavramlar

bir CosmosClientbaşlatıldıktan sonra, Cosmos DB'deki birincil kaynak türleriyle etkileşim kurabilirsiniz:

  • Veritabanı: Cosmos DB hesabı birden çok veritabanı içerebilir. Veritabanı oluştururken, 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.

  • Container: Kapsayıcı, JSON belgelerinin koleksiyonudur. Container 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 id anahtarı içermelidir. idsağlamazsanız SDK 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

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

import { CosmosClient } from "@azure/cosmos";

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

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

Kapsayıcı oluşturma

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

import { CosmosClient } from "@azure/cosmos";

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

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

Bölüm Anahtarlarını Kullanma

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

import { CosmosClient } from "@azure/cosmos";

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

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

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

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, sabit değer veya dizi olarak sağlanabilir.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

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

import { CosmosClient } from "@azure/cosmos";

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

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

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

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.upsertgeçirin. Azure Cosmos DB hizmetinde her öğenin bir id anahtarı olması gerekir. Sağlamazsanız SDK otomatik olarak bir id oluşturur.

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

import { CosmosClient } from "@azure/cosmos";

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

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

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

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.readkullanın. Bu, idtarafından sorgulamak için SQL kullanmaktan daha ucuz bir işlemdir.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

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

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

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

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

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

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"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

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

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

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
    partitionKey: ["foo", 100],
  })
  .fetchAll();

Öğe silme

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

import { CosmosClient } from "@azure/cosmos";

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

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

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

// 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ını destekler:

import { CosmosClient } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();

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

import { CosmosClient } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }],
  })
  .fetchAll();

SQL API'sini kullanarak Cosmos DB veritabanlarını sorgulama hakkında daha fazla bilgi için bkz. Azure Cosmos DB verilerini SQL sorguları ile 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 ChangeFeedPullModelIteratorörneği oluşturun. başlangıçta ChangeFeedPullModelIteratoroluşturduğunuzda, changeFeedStartFrom içinde 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 bir ChangeFeedIteratorOptions değeri belirtmeniz gerekir. sayfa başına alınan en fazla öğe sayısını ayarlamak için isteğe bağlı olarak maxItemCountChangeFeedIteratorOptions kullanabilirsiniz.

Not: changeFeedStartFrom değeri belirtilmezse, şimdi() 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
import { ChangeFeedStartFrom } from "@azure/cosmos";

const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};
  • Time
import { ChangeFeedStartFrom } from "@azure/cosmos";

const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};
  • Now
import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now(),
};
  • Continuation
import { ChangeFeedStartFrom } from "@azure/cosmos";

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token received 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

import {
  CosmosClient,
  PartitionKeyDefinitionVersion,
  PartitionKeyKind,
  ChangeFeedStartFrom,
} from "@azure/cosmos";

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

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

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

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, hasMoreResults değeri her zaman true. Değişiklik akışını okumaya çalıştığınızda ve kullanılabilir yeni bir değişiklik olmadığında, NotModified durumuyla bir yanıt alırsınız.

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

Hariç tutulan konumları kullanma

İstek excludedLocations düzeyindeki seçenek, kullanıcının isteği sunmanın dışında tutulması gereken bir veya daha fazla Azure bölgesi belirtmesine olanak tanır. Bu, kullanıcının uyumluluk, gecikme süresi veya kullanılabilirlik sorunları nedeniyle belirli bölgelerden kaçınmak istediği senaryolar için kullanışlıdır. Ayarlandığında, Cosmos DB isteği diğer kullanılabilir bölgelere yönlendirerek veri yerleşimi ve yük devretme davranışı üzerindeki denetimi geliştirir.

excludedLocations yalnızca true olarak ayarlandığında enableEndPointDiscovery uygulanır.

Bu örnekte, Hariç Tutulan Konumları destekleyen çeşitli API'ler gösterilmektedir.

import { CosmosClient, ChangeFeedStartFrom } from "@azure/cosmos";

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

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

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

const city = { id: "1", name: "Olympia", state: "WA" };
await container.items.upsert(city, { excludedLocations: ["Test Region"] });

const iterator = container.items.getChangeFeedIterator({
  excludedLocations: ["Test Region"],
  maxItemCount: 1,
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
});

const response = await iterator.readNext();

Hata İşleme

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

  1. bir işlemin yanıtı =400 ErrorResponsehata kodu döndürürse > oluşturulur.
  2. Zaman aşımı nedeniyle Abort dahili olarak çağrılırsa TimeoutError oluşturulur.
  3. AbortError, durdurma işlemine herhangi bir kullanıcı sinyali geçtiyse oluşturulur.
  4. RestError, ağ sorunları nedeniyle temel alınan sistem çağrısının başarısız olması durumunda oluşturulur.
  5. Herhangi bir devDependencies tarafından oluşturulan hatalar. Örneğin, @azure/identity paket CredentialUnavailableErroratabilir.

Aşağıda, ErrorResponse, TimeoutError, AbortErrorve RestErrortür hatalarını işlemeye yönelik bir örnek verilmiştir.

import { ErrorResponse, RestError } from "@azure/cosmos";

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 herhangi bir hatadan düzgün bir şekilde kurtarılabilmesi ve beklendiği gibi çalışmaya devam etmesini sağlamak için bu hataların düzgün bir şekilde işlenmesi önemlidir. Bu hatalardan bazıları ve olası çözümleri hakkında daha fazla bilgiburada bulunabilir.

Sorun giderme

Genel

Hizmet tarafından döndürülen Cosmos DB hatalarıyla etkileşime geçtiğiniz zaman REST API istekleri için döndürülen HTTP durum kodlarıyla aynıdır:

Azure Cosmos DB için HTTP Durum Kodlarını

Çakışma

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

import { CosmosClient, ErrorResponse, RestError } from "@azure/cosmos";

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

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

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

try {
  await container.items.create({ id: "existing-item-id" });
} catch (error) {
  const err = error as ErrorResponse | RestError;
  if (err.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Çeviri

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 zorlanan hız sınırlarının neden olduğu geçici hatalarla veya ağ kesintileri gibi diğer geçici sorunlarla karşılaşabilirsiniz. Bu tür hataları işleme hakkında bilgi için, Bulut Tasarım Desenleri kılavuzunda Yeniden deneme deseni ve ilgili Devre Kesici desenikonusuna bakın.

Günlük tutmak

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, günlük setLogLevel@azure/logger çağrılarak çalışma zamanında etkinleştirilebilir. AZURE_LOG_LEVEL kullanırken, günlük kitaplığı başlatılmadan önce ayarladığınızdan emin olun. dotenv gibi kitaplıklar kullanıyorsanız, kitaplığı günlüğe kaydetmeden önce bu tür kitaplıkların başlatıldığından emin olun.

import { setLogLevel } from "@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. Burada yalnızca bilgiler üretim sistemleri için, hata ayıklama ve hata ayıklama güvensiz ise önemli ölçüde daha yüksek kaynaklar kullandığından geliştirme ve hata ayıklama sırasında kullanılmalıdır. Cosmos Tanılama düzeyi 2 şekilde ayarlanabilir

  • Programlı olarak
import { CosmosClient, CosmosDbDiagnosticLevel } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
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 Tanılama'nın üç ü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 bulunan har kaydına 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 hata ayıklama-güvenli olmayan)

  • 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 hata ayıklama-güvenli olmayan)

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

TanılamaYı Kullanma

  • diagnostics tüm Yanıt nesnelerine eklendiğinden. CosmosDiagnostic program aracılığıyla aşağıdaki gibi erişebilirsiniz.
import {
  CosmosClient,
  CosmosDbDiagnosticLevel,
  OperationInput,
  BulkOperationType,
} from "@azure/cosmos";

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

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
// For point look up operations

const { container, diagnostics: containerCreateDiagnostic } =
  await database.containers.createIfNotExists({
    id: "<container-id>",
    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;
}
  • diagnostics @azure/loggerkullanarak da günlüğe kaydedebilirsiniz. Tanılama her zaman @azure/logger düzeyde verbose kullanılarak günlüğe kaydedilir. Dolayısıyla Tanılama düzeyini debug veya debug-unsafe ve @azure/logger düzeyini verboseolarak ayarlarsanız diagnostics günlüğe kaydedilir.

Sonraki adımlar

Daha fazla örnek kod

SDK'nın GitHub deposunda kullanabileceğiniz çeşitli örnekler. 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ırlama

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

  • İstemci tarafı şifreleme şu anda tarayıcı ortamında desteklenmemektedir.

Veri Düzlemi Sınırlamaları:

  • DISTINCT alt sorgusundan COUNT içeren sorgular
  • Doğrudan TCP Modu erişimi
  • Sıralama, sayma ve farklı gibi bölümler arası sorguları toplama, devamlılık belirteçlerini desteklemez. SELECT * FROM gibi akışla aktarılabilir sorgular WHERE <koşulu>, devam belirteçlerini destekler. Devam 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
  • 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 araba desenikullanarak devamlılık belirteci desteğiyle çapraz bölümleme sorguları elde edebilirsiniz. Bu desen, uygulamaların heterojen bileşenlerden ve teknolojilerden oluşmasını da sağlayabilir.

    Akışa alınamayan 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:

    import { CosmosClient } from "@azure/cosmos";

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

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

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

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const queryIterator = container.items.query(querySpec, queryOptions);
while (queryIterator.hasMoreResults()) {
  const { resources: result } = await queryIterator.fetchNext();
  // process results
}

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

    Denetim Düzlemi işlemleri

    Genellikle Azure PortalAzure Cosmos DB Kaynak Sağlayıcısı REST API, Azure CLI veya powershell denetim düzlemi desteklenmeyen sınırlamalar için kullanabilirsiniz.

    Ek belgeler

    Cosmos DB hizmetiyle ilgili daha kapsamlı belgeler için learn.microsoft.com'daki Azure Cosmos DB belgelerine bakın.

    Katkıda

    Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

  • Last updated on