مشاركة عبر

مكتبة عميل Azure Cosmos DB ل JavaScript - الإصدار 4.2.0

  • مقالة

/TypeScript

أحدث شارة npm حالة البناء

Azure Cosmos DB هي خدمة قاعدة بيانات متعددة النماذج موزعة عالميا تدعم قواعد بيانات المستند والقيمة الرئيسية والعمود العريض والرسم البياني. هذه الحزمة مخصصة لتطبيقات JavaScript/TypeScript للتفاعل مع قواعد بيانات SQL API ومستندات JSON التي تحتوي عليها:

  • إنشاء قواعد بيانات Cosmos DB وتعديل إعداداتها
  • إنشاء حاويات وتعديلها لتخزين مجموعات من مستندات JSON
  • إنشاء العناصر (مستندات JSON) وقراءتها وتحديثها وحذفها في حاوياتك
  • الاستعلام عن المستندات في قاعدة البيانات باستخدام بناء جملة يشبه SQL

الارتباطات الرئيسية:

  • حزمة (npm)
  • الوثائق المرجعية لواجهة برمجة التطبيقات
  • وثائق Product

الشروع

المتطلبات المسبقه

اشتراك Azure وحساب Cosmos DB SQL API

يجب أن يكون لديكاشتراك Azure ، وحساب Cosmos DB (SQL API) لاستخدام هذه الحزمة.

إذا كنت بحاجة إلى حساب Cosmos DB SQL API، يمكنك استخدام Azure Cloud Shell لإنشاء حساب باستخدام أمر Azure CLI هذا:

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

أو يمكنك إنشاء حساب في مدخل Azure

NodeJS

يتم توزيع هذه الحزمة عبر npm الذي يأتي مثبتا مسبقا مع NodeJS باستخدام إصدار LTS.

CORS

تحتاج إلى إعداد قواعد مشاركة الموارد عبر المنشأ (CORS) لحساب Cosmos DB الخاص بك إذا كنت بحاجة إلى التطوير للمستعرضات. اتبع الإرشادات الموجودة في المستند المرتبط لإنشاء قواعد CORS جديدة لقاعدة بيانات Cosmos DB.

تثبيت هذه الحزمة

npm install @azure/cosmos

الحصول على بيانات اعتماد الحساب

ستحتاج إلى نقطة نهاية حساب Cosmos DB ومفتاح . يمكنك العثور على هذه في مدخل Azure أو استخدام القصاصة البرمجية Azure CLI أدناه. تم تنسيق القصاصة البرمجية ل Bash shell.

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

يبدأ التفاعل مع Cosmos DB بمثيل فئة CosmosClient

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);
});

للتبسيط، قمنا بإدراج keyendpoint مباشرة في التعليمات البرمجية ولكن من المحتمل أن ترغب في تحميلها من ملف غير موجود في التحكم بالمصادر باستخدام مشروع مثل dotenv أو التحميل من متغيرات البيئة

في بيئات الإنتاج، يجب تخزين أسرار مثل المفاتيح في Azure Key Vault

المفاهيم الرئيسية

بمجرد تهيئة CosmosClient، يمكنك التفاعل مع أنواع الموارد الأساسية في Cosmos DB:

  • قاعدة البيانات: يمكن أن يحتوي حساب Cosmos DB على قواعد بيانات متعددة. عند إنشاء قاعدة بيانات، يمكنك تحديد واجهة برمجة التطبيقات التي ترغب في استخدامها عند التفاعل مع مستنداتها: SQL أو MongoDB أو Gremlin أو Cassandra أو Azure Table. استخدم الكائن قاعدة بيانات لإدارة حاوياته.

  • Container: الحاوية هي مجموعة من مستندات JSON. يمكنك إنشاء (إدراج) وقراءة وتحديث وحذف العناصر في حاوية باستخدام أساليب على كائن حاوية .

  • العنصر: العنصر هو مستند JSON مخزن في حاوية. يجب أن يتضمن كل عنصر مفتاح id بقيمة تعرف العنصر بشكل فريد داخل الحاوية. إذا لم توفر id، فسيقوم SDK بإنشاء واحد تلقائيا.

لمزيد من المعلومات حول هذه الموارد، راجع العمل مع قواعد بيانات Azure Cosmos والحاويات والعناصر.

امثله

توفر الأقسام التالية العديد من القصاصات البرمجية التي تغطي بعض مهام Cosmos DB الأكثر شيوعا، بما في ذلك:

إنشاء قاعدة بيانات

بعد مصادقة CosmosClient، يمكنك العمل مع أي مورد في الحساب. تنشئ القصاصة البرمجية أدناه قاعدة بيانات واجهة برمجة تطبيقات NOSQL.

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

إنشاء حاوية

ينشئ هذا المثال حاوية بالإعدادات الافتراضية

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

استخدام مفاتيح الأقسام

يوضح هذا المثال أنواعا مختلفة من مفاتيح الأقسام المدعومة.

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

إذا كان مفتاح القسم يتكون من قيمة واحدة، يمكن توفيره إما كقيمة حرفية، أو كصفيف.

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

إذا كان مفتاح القسم يتكون من أكثر من قيمة واحدة، يجب توفيره كصفيف.

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();

إدراج عناصر

لإدراج عناصر في حاوية، مرر كائنا يحتوي على بياناتك إلى Items.upsert. تتطلب خدمة Azure Cosmos DB أن يكون لكل عنصر مفتاح id. إذا لم توفر واحدا، فسيقوم SDK بإنشاء id تلقائيا.

يدرج هذا المثال عدة عناصر في الحاوية

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);
}

قراءة عنصر

لقراءة عنصر واحد من حاوية، استخدم Item.read. هذه عملية أقل تكلفة من استخدام SQL للاستعلام عن طريق id.

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

CRUD على الحاوية مع مفتاح قسم هرمي

إنشاء حاوية بمفتاح قسم هرمي

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

إدراج عنصر بمفتاح قسم هرمي معرف على أنه - ["/name", "/address/zip"]

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

لقراءة عنصر واحد من حاوية بمفتاح قسم هرمي معرف على أنه - ["/name", "/address/zip"],

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

الاستعلام عن عنصر بمفتاح قسم هرمي مع تعريف مفتاح القسم الهرمي على أنه - ["/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} `);
}

حذف عنصر

لحذف العناصر من حاوية، استخدم Item.delete.

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

الاستعلام عن قاعدة البيانات

تدعم قاعدة بيانات Cosmos DB SQL API الاستعلام عن العناصر في حاوية باستخدام Items.query باستخدام بناء جملة يشبه SQL:

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 `);
}

تنفيذ الاستعلامات ذات المعلمات عن طريق تمرير كائن يحتوي على المعلمات وقيمها إلى Items.query:

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 `);
}

لمزيد من المعلومات حول الاستعلام عن قواعد بيانات Cosmos DB باستخدام واجهة برمجة تطبيقات SQL، راجع استعلام بيانات Azure Cosmos DB باستخدام استعلامات SQL.

تغيير نموذج سحب الموجز

يمكن جلب موجز التغيير لمفتاح قسم أو نطاق موجز أو حاوية بأكملها.

لمعالجة موجز التغيير، قم بإنشاء مثيل ChangeFeedPullModelIterator. عند إنشاء ChangeFeedPullModelIteratorفي البداية ، يجب تحديد قيمة changeFeedStartFrom مطلوبة داخل ChangeFeedIteratorOptions التي تتكون من موضع البداية لقراءة التغييرات والمورد (مفتاح قسم أو FeedRange) الذي سيتم جلب التغييرات له. يمكنك اختياريا استخدام maxItemCount في ChangeFeedIteratorOptions لتعيين الحد الأقصى لعدد العناصر المستلمة لكل صفحة.

ملاحظة: إذا لم يتم تحديد قيمة changeFeedStartFrom، جلب changefeed لحاوية بأكملها من الآن().

هناك أربعة مواضع بداية لموجز التغيير:

  • 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),
};

فيما يلي مثال على إحضار موجز التغيير لمفتاح القسم

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
}

نظرا لأن موجز التغيير هو بشكل فعال قائمة لا نهائية من العناصر التي تشمل جميع عمليات الكتابة والتحديثات المستقبلية، فإن قيمة hasMoreResults دائما ما تكون true. عندما تحاول قراءة موجز التغيير ولا تتوفر تغييرات جديدة، تتلقى استجابة بحالة NotModified.

يمكن العثور على إرشادات استخدام وأمثلة أكثر تفصيلا لموجز التغيير هنا.

معالجة الأخطاء

ينشئ SDK أنواعا مختلفة من الأخطاء التي يمكن أن تحدث أثناء العملية.

  1. يتم طرح ErrorResponse إذا كانت استجابة العملية ترجع رمز خطأ >=400.
  2. يتم طرح TimeoutError إذا تم استدعاء Abort داخليا بسبب المهلة.
  3. يتم طرح AbortError إذا تسبب أي مستخدم مرر إشارة في إحباط.
  4. يتم طرح RestError في حالة فشل استدعاء النظام الأساسي بسبب مشكلات في الشبكة.
  5. الأخطاء التي تم إنشاؤها بواسطة أي devDependencies. على سبيل المثال. يمكن أن تطرح حزمة @azure/identityCredentialUnavailableError.

فيما يلي مثال لمعالجة أخطاء النوع ErrorResponseTimeoutErrorAbortErrorRestError.

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.
  }
}

من المهم معالجة هذه الأخطاء بشكل صحيح للتأكد من أن التطبيق الخاص بك يمكن أن يتعافى بأمان من أي حالات فشل ومواصلة العمل كما هو متوقع. يمكن العثور على مزيد من التفاصيل حول بعض هذه الأخطاء والحلول الممكنة لها هنا.

استكشاف الاخطاء

عام

عند التفاعل مع أخطاء Cosmos DB التي تم إرجاعها بواسطة الخدمة تتوافق مع نفس رموز حالة HTTP التي تم إرجاعها لطلبات REST API:

رموز حالة HTTP ل Azure Cosmos DB

النزاعات

على سبيل المثال، إذا حاولت إنشاء عنصر باستخدام id قيد الاستخدام بالفعل في قاعدة بيانات Cosmos DB، إرجاع خطأ 409، مما يشير إلى التعارض. في القصاصة البرمجية التالية، تتم معالجة الخطأ بأمان عن طريق التقاط الاستثناء وعرض معلومات إضافية حول الخطأ.

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");
  }
}

تحويل البيانات

تم تصميم Azure SDKs لدعم بناء جملة ES5 JavaScript وإصدارات LTS من Node.js. إذا كنت بحاجة إلى دعم لأواقات تشغيل JavaScript السابقة مثل Internet Explorer أو العقدة 6، فستحتاج إلى تحويل التعليمات البرمجية ل SDK كجزء من عملية الإنشاء.

معالجة الأخطاء العابرة مع إعادة المحاولة

أثناء العمل مع Cosmos DB، قد تواجه حالات فشل عابرة ناتجة عن حدود معدل تفرضها الخدمة، أو مشاكل عابرة أخرى مثل انقطاع الشبكة. للحصول على معلومات حول معالجة هذه الأنواع من حالات الفشل، راجع نمط إعادة المحاولة في دليل أنماط تصميم السحابة، ونمط قاطع دائرة ذي الصلة.

تسجيل

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين متغير البيئة AZURE_LOG_LEVEL إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger. أثناء استخدام AZURE_LOG_LEVEL تأكد من تعيينه قبل تهيئة مكتبة التسجيل. من الناحية المثالية، قم بتمريره عبر سطر الأوامر، إذا كان استخدام مكتبات مثل dotenv تأكد من تهيئة هذه المكتبات قبل تسجيل المكتبة.

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

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

تشخيص

توفر ميزة تشخيص Cosmos رؤى محسنة حول جميع عمليات العميل. تتم إضافة كائن CosmosDiagnostics إلى استجابة جميع عمليات العميل. مثل

  • استجابة عملية البحث عن نقطة - item.read()، container.create()، database.delete()
  • استجابة عملية الاستعلام -queryIterator.fetchAll()،
  • العمليات المجمعة والدفعية -item.batch().
  • كائنات استجابة الخطأ/الاستثناء.

تتم إضافة كائن CosmosDiagnostics إلى استجابة جميع عمليات العميل. هناك 3 مستويات تشخيص Cosmos ومعلومات وتصحيح وتصحيح غير آمن. حيث يتم استخدام المعلومات فقط لأنظمة الإنتاج والتصحيح والتصحيح غير الآمن أثناء التطوير وتصحيح الأخطاء، لأنها تستهلك موارد أعلى بكثير. يمكن تعيين مستوى تشخيص Cosmos بطريقتين

  • برمجيا
  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });
  • استخدام متغيرات البيئة. (مستوى التشخيص الذي تم تعيينه بواسطة متغير البيئة له أولوية أعلى على تعيينه من خلال خيارات العميل.)
  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

يحتوي Cosmos Diagnostic على ثلاثة أعضاء

  • نوع ClientSideRequestStatistics: يحتوي على تفاصيل تشخيص مجمعة، بما في ذلك عمليات البحث عن بيانات التعريف وإعادة المحاولة ونقاط النهاية التي تم الاتصال بها وإحصائيات الطلب والاستجابة مثل حجم الحمولة والمدة. (يتم جمعها دائما، ويمكن استخدامها في أنظمة الإنتاج.)

  • DiagnosticNode: هي بنية تشبه الشجرة تلتقط معلومات تشخيصية مفصلة. على غرار تسجيل har موجود في المستعرضات. يتم تعطيل هذه الميزة بشكل افتراضي وهي مخصصة لتصحيح أخطاء البيئات غير الإنتاجية فقط. (يتم جمعها على مستوى التشخيص تتبع الأخطاء وتصحيح الأخطاء غير الآمنة)

  • ClientConfig: يلتقط المعلومات الأساسية المتعلقة بإعدادات تكوين العميل أثناء تهيئة العميل. (يتم جمعها على مستوى التشخيص تتبع الأخطاء وتصحيح الأخطاء غير الآمنة)

يرجى التأكد من عدم تعيين مستوى التشخيص أبدا إلى debug-unsafe في بيئة الإنتاج، لأنه هذا المستوى CosmosDiagnostics يلتقط حمولات الطلب والاستجابة وإذا اخترت تسجيله (يتم تسجيله افتراضيا بواسطة @azure/logger على مستوى verbose). قد يتم التقاط هذه الحمولات في متلقي السجل الخاص بك.

تشخيص الاستهلاك

  • نظرا لإضافة diagnostics إلى كافة كائنات الاستجابة. يمكنك الوصول برمجيا إلى 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
  }
  • يمكنك أيضا تسجيل diagnostics باستخدام @azure/logger، يتم تسجيل التشخيص دائما باستخدام @azure/logger على مستوى verbose. لذلك إذا قمت بتعيين مستوى التشخيص إلى debug أو debug-unsafe ومستوى @azure/logger إلى verbose، تسجيل diagnostics.

الخطوات التالية

المزيد من نماذج التعليمات البرمجية

تتوفر لك العديد من العينات في مستودع GitHub الخاص ب SDK. توفر هذه العينات مثالا للتعليمات البرمجية للسيناريوهات الإضافية التي تتم مواجهتها عادة أثناء العمل مع Cosmos DB:

  • عمليات قاعدة البيانات
  • عمليات الحاوية
  • عمليات العنصر
  • تكوين الفهرسة
  • قراءة موجز تغيير الحاوية
  • الإجراءات المخزنة
  • تغيير إعدادات معدل نقل قاعدة البيانات/الحاوية
  • عمليات الكتابة متعددة المناطق

القيود

حاليا الميزات أدناه غير مدعومة . للحصول على خيارات البدائل، تحقق من قسم الحلول البديلة أدناه.

قيود مستوى البيانات:

  • الاستعلامات باستخدام COUNT من استعلام فرعي DISTINCT
  • الوصول المباشر إلى وضع TCP
  • لا تدعم الاستعلامات المجمعة عبر الأقسام، مثل الفرز والعد والتميز، الرموز المميزة للمتابعة. استعلامات قابلة للبث، مثل SELECT * FROM WHERE ، دعم الرموز المميزة للمتابعة. راجع قسم "الحل البديل" لتنفيذ الاستعلامات غير القابلة للبث دون رمز مميز للمتابعة.
  • موجز التغيير: المعالج
  • موجز التغيير: قراءة قيم مفاتيح أقسام متعددة
  • تغيير دعم نموذج سحب الموجز لمفاتيح الأقسام الهرمية الجزئية #27059
  • ترتيب حسب عبر الأقسام للأنوع المختلطة

    • قيود وحدة التحكم:

    • الحصول على مقاييس CollectionSizeUsage و DatabaseUsage و DocumentUsage
    • إنشاء فهرس جغرافي مكاني
    • تحديث معدل نقل التحجيم التلقائي

    الحلول البديلة

    رمز المتابعة لاستعلامات الأقسام المتقاطعة

    يمكنك تحقيق استعلامات الأقسام المتقاطعة مع دعم الرمز المميز للمتابعة باستخدام نمط السيارة الجانبية. يمكن لهذا النمط أيضا تمكين التطبيقات من أن تتكون من مكونات وتقنيات غير متجانسة.

    تنفيذ استعلام غير قابل للتقسيم المتقاطع

    لتنفيذ استعلامات غير قابلة للبث دون استخدام الرموز المميزة للمتابعة، يمكنك إنشاء مكرر استعلام بمواصفات الاستعلام المطلوبة وخياراته. يوضح نموذج التعليمات البرمجية التالي كيفية استخدام مكرر استعلام لجلب جميع النتائج دون الحاجة إلى رمز مميز للمتابعة:

    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 querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

    يمكن أيضا استخدام هذا الأسلوب للاستعلامات القابلة للبث.

    عمليات وحدة التحكم

    عادة ما يمكنك استخدام مدخل Azure، واجهة برمجة تطبيقات REST لموفر موارد Azure Cosmos DB، Azure CLI أو PowerShell للقيود غير المدعومة لمستوى التحكم.

    وثائق إضافية

    للحصول على وثائق أكثر شمولا حول خدمة Cosmos DB، راجع وثائق Azure Cosmos DB على docs.microsoft.com.

    المساهمه

    إذا كنت ترغب في المساهمة في هذه المكتبة، فيرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

    مرات الظهور