مشاركة عبر

التطوير محليا باستخدام محاكي Azure Cosmos DB

  • مقالة

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

المتطلبات الأساسية

  • .NET 6 أو أحدث، Node.js v20 أو أحدث، أو Python 3.7 أو أحدث
    • تأكد من أن جميع الملفات التنفيذية المطلوبة متوفرة في .PATH
  • محاكي Windows
    • الإصدار 64 بت من Windows Server 2016 أو 2019 أو Windows 10 أو Windows 11.
    • الحد الأدنى لمتطلبات الأجهزة:
      • ذاكرة وصول عشوائية 2 غيغابايت
      • مساحة القرص الثابت المتوفرة 10 جيجابايت
  • محاكي Docker

تثبيت المحاكي

هناك تباينات متعددة للمحاكي ولكل تباين عملية تثبيت بدون احتكاك نسبيا.

للبدء، احصل على Linux-variant لصورة الحاوية من Microsoft Container Registry (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator اسحب صورة حاوية Linux من سجل الحاوية إلى مضيف Docker المحلي.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. تحقق للتأكد من توفر صورة المحاكي على مضيف Docker المحلي.

    docker images

للبدء، احصل على Linux-variant لصورة الحاوية من Microsoft Container Registry (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator اسحب صورة حاوية Linux باستخدام العلامة mongodb من سجل الحاوية إلى مضيف Docker المحلي.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. تحقق للتأكد من توفر صورة المحاكي على مضيف Docker المحلي.

    docker images

لا يدعم متغير حاوية Docker (Linux أو Windows) للمحاكي واجهة برمجة التطبيقات ل Apache Cassandra أو API ل Apache Gremlin أو واجهة برمجة التطبيقات للجدول.

بدء تشغيل المحاكي

بمجرد التنزيل، ابدأ تشغيل المحاكي مع تمكين واجهة برمجة التطبيقات المحددة.

لا يدعم متغير حاوية Docker للمحاكي واجهة برمجة التطبيقات ل Apache Cassandra.

لا يدعم متغير حاوية Docker للمحاكي واجهة برمجة التطبيقات ل Apache Gremlin.

لا يدعم متغير حاوية Docker للمحاكي واجهة برمجة التطبيقات للجدول.

  1. تشغيل حاوية جديدة باستخدام صورة الحاوية والتكوين التالي:

    ‏‏الوصف
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(اختياري) حدد عدد الأقسام التي يجب استخدامها.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(اختياري) تمكين استمرارية البيانات بين تشغيل المحاكي.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(اختياري) تجاوز عنوان IP الافتراضي للمحاكي.

    بالنسبة لأنظمة Linux، استخدم:

    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

    بالنسبة لأنظمة Windows، استخدم:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250-10255:10250-10255"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. انتقل إلى https://localhost:8081/_explorer/index.html للوصول إلى مستكشف البيانات.

  1. تشغيل حاوية جديدة باستخدام صورة الحاوية والتكوين التالي:

    ‏‏الوصف
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT حدد إصدار نقطة نهاية MongoDB لاستخدامها. تتضمن نقاط النهاية المدعومة: 3.2أو 3.6أو .4.0
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(اختياري) حدد عدد الأقسام التي يجب استخدامها.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(اختياري) تمكين استمرارية البيانات بين تشغيل المحاكي.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(اختياري) تجاوز عنوان IP الافتراضي للمحاكي.

    بالنسبة لأنظمة Linux، استخدم:

    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

    بالنسبة لأنظمة Windows، استخدم:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250:10250"
    "--env", "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. انتقل إلى https://localhost:8081/_explorer/index.html للوصول إلى مستكشف البيانات.

استيراد شهادة TLS/SSL الخاصة بالمحاكي

قم باستيراد شهادة TLS/SSL الخاصة بالمحاكي لاستخدام المحاكي مع SDK المطور المفضل لديك دون تعطيل TLS/SSL على العميل.

لا يدعم متغير حاوية Docker (Linux أو Windows) للمحاكي واجهة برمجة التطبيقات ل Apache Cassandra أو API ل Apache Gremlin أو واجهة برمجة التطبيقات للجدول.

تتوفر شهادة المحاكي في المسار _explorer/emulator.pem على الحاوية قيد التشغيل. استخدم curl لتنزيل الشهادة من الحاوية قيد التشغيل إلى جهازك المحلي.

  1. احصل على الشهادة من الحاوية قيد التشغيل.

    بالنسبة لأنظمة Linux، استخدم:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    بالنسبة لأنظمة Windows، استخدم:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

  2. أعد إنشاء حزمة الشهادة باستخدام الأمر المناسب لنظام التشغيل الخاص بك.

    بالنسبة لأنظمة Linux المستندة إلى Debian (على سبيل المثال، Ubuntu)، استخدم:

    sudo update-ca-certificates

    بالنسبة لأنظمة Linux المستندة إلى Red Hat (على سبيل المثال، CentOS، Fedora)، استخدم:

    sudo update-ca-trust

    بالنسبة لأنظمة Windows، استخدم:

    certutil -f -addstore "Root" ~/emulatorcert.crt

    للحصول على إرشادات أكثر تفصيلا، راجع الوثائق الخاصة بنظام التشغيل الخاص بك.

تتوفر شهادة المحاكي في المسار /_explorer/emulator.pem على الحاوية قيد التشغيل.

  1. قم بتنزيل الشهادة من الحاوية قيد التشغيل إلى جهازك المحلي.

    بالنسبة لأنظمة Linux، استخدم:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    بالنسبة لأنظمة Windows، استخدم:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

    إشعار

    قد تحتاج إلى تغيير المضيف (أو عنوان IP) ورقم المنفذ إذا كنت قد قمت بتعديل هذه القيم مسبقا.

  2. قم بتثبيت الشهادة وفقا للعملية المستخدمة عادة لنظام التشغيل الخاص بك. على سبيل المثال، في Linux، يمكنك نسخ الشهادة /usr/local/share/ca-certificates/ إلى المسار.

    بالنسبة لأنظمة Linux، استخدم:

    cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

    بالنسبة لأنظمة Windows، استخدم:

    $parameters = @{
    FilePath = 'emulatorcert.crt'
    CertStoreLocation = 'Cert:\CurrentUser\Root'
}
Import-Certificate @parameters

  3. بالنسبة لأنظمة linux، أعد إنشاء حزمة الشهادة باستخدام الأمر المناسب لتوزيع Linux الخاص بك.

    بالنسبة لأنظمة Linux المستندة إلى Debian (على سبيل المثال، Ubuntu)، استخدم:

    sudo update-ca-certificates

    بالنسبة لأنظمة Linux المستندة إلى Red Hat (على سبيل المثال، CentOS، Fedora)، استخدم:

    sudo update-ca-trust

    للحصول على إرشادات أكثر تفصيلا، راجع الوثائق الخاصة بنظام التشغيل الخاص بك.

الاتصال بالمحاكي من SDK

يتضمن كل SDK فئة عميل تستخدم عادة لتوصيل SDK بحساب Azure Cosmos DB الخاص بك. باستخدام بيانات اعتماد المحاكي، يمكنك توصيل SDK بمثيل المحاكي بدلا من ذلك.

استخدم واجهة برمجة تطبيقات Azure Cosmos DB ل NoSQL .NET SDK للاتصال بالمحاكي من تطبيق .NET.

  1. ابدأ في مجلد فارغ.

  2. إنشاء تطبيق وحدة تحكم .NET جديد

    dotnet new console

  3. أضف الحزمة Microsoft.Azure.Cosmos من NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. افتح ملف Program.cs.

  5. احذف أي محتوى موجود داخل الملف.

  6. إضافة كتلة استخدام لمساحة Microsoft.Azure.Cosmos الاسم.

    using Microsoft.Azure.Cosmos;

  7. إنشاء مثيل CosmosClient جديد لاستخدام بيانات اعتماد المحاكي.

    using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

  8. إنشاء قاعدة بيانات وحاوية جديدة باستخدام CreateDatabaseIfNotExistsAsync و CreateContainerIfNotExistsAsync.

    Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);

  9. إنشاء عنصر جديد في الحاوية باستخدام UpsertItemAsync.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

await container.UpsertItemAsync(item);

  10. تشغيل تطبيق .NET.

    dotnet run

    تحذير

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

    CosmosClientOptions options = new ()
{
    HttpClientFactory = () => new HttpClient(new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    }),
    ConnectionMode = ConnectionMode.Gateway,
};

using CosmosClient client = new(
  ...,
  ...,
  clientOptions: options
);

تلميح

راجع دليل مطور .NET لمزيد من العمليات التي يمكنك تنفيذها باستخدام .NET SDK.

استخدم برنامج تشغيل MongoDB .NET للاتصال بالمحاكي من تطبيق .NET.

  1. ابدأ في مجلد فارغ.

  2. إنشاء تطبيق وحدة تحكم .NET جديد

    dotnet new console

  3. أضف الحزمة MongoDB.Driver من NuGet.

    dotnet add package MongoDB.Driver

  4. افتح ملف Program.cs.

  5. احذف أي محتوى موجود داخل الملف.

  6. إضافة كتلة استخدام لمساحة MongoDB.Driver الاسم.

    using MongoDB.Driver;

  7. إنشاء مثيل MongoClient جديد لاستخدام بيانات اعتماد المحاكي.

    var client = new MongoClient(
    "mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);

  8. احصل على قاعدة البيانات والحاوية باستخدام GetDatabase و GetCollection<>.

    var database = client.GetDatabase("cosmicworks");

var collection = database.GetCollection<dynamic>("products");

  9. إنشاء عنصر جديد في XXX باستخدام InsertOneAsync.

    var item = new
{
    name = "Kiama classic surfboard"
};

await collection.InsertOneAsync(item);

  10. تشغيل تطبيق .NET.

    dotnet run

استخدم برنامج تشغيل Apache Cassandra .NET للاتصال بالمحاكي من تطبيق .NET.

  1. ابدأ في مجلد فارغ.

  2. إنشاء تطبيق وحدة تحكم .NET جديد

    dotnet new console

  3. أضف الحزمة CassandraCSharpDriver من NuGet.

    dotnet add package CassandraCSharpDriver

  4. افتح ملف Program.cs.

  5. احذف أي محتوى موجود داخل الملف.

  6. إضافة كتلة استخدام لمساحة Cassandra الاسم.

    using Cassandra;

  7. إنشاء مثيل Cluster جديد لاستخدام بيانات اعتماد المحاكي. إنشاء جلسة عمل جديدة باستخدام Connect.

    var options = new SSLOptions(
    sslProtocol: System.Security.Authentication.SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, policyErrors) => policyErrors == System.Net.Security.SslPolicyErrors.None);

using var cluster = Cluster.Builder()
    .WithCredentials(
        username: "localhost",
        password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    )
    .WithPort(
        port: 10350
    )
    .AddContactPoint(
        address: "localhost"
    )
    .WithSSL(
        sslOptions: options
    )
    .Build();

using var session = cluster.Connect();

  8. إنشاء قاعدة بيانات وحاوية جديدة باستخدام PrepareAsync و ExecuteAsync.

    var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());

var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());

  9. إنشاء عنصر جديد في الجدول باستخدام ExecuteAsync. استخدم Bind لتعيين خصائص للعنصر.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");

var createItemStatement = createItem.Bind(item.id, item.name);

await session.ExecuteAsync(createItemStatement);

  10. تشغيل تطبيق .NET.

    dotnet run

هام

قبل البدء، تتطلب واجهة برمجة التطبيقات ل Apache Gremlin إنشاء مواردك في المحاكي. إنشاء قاعدة بيانات باسم db1 وحاوية باسم coll1. إعدادات معدل النقل غير ذات صلة لهذا الدليل ويمكن تعيينها منخفضة كما تريد.

استخدم برنامج تشغيل Apache Gremlin .NET للاتصال بالمحاكي من تطبيق .NET.

  1. ابدأ في مجلد فارغ.

  2. إنشاء تطبيق وحدة تحكم .NET جديد

    dotnet new console

  3. أضف الحزمة Gremlin.Net من NuGet.

    dotnet add package Gremlin.Net

  4. افتح ملف Program.cs.

  5. احذف أي محتوى موجود داخل الملف.

  6. إضافة كتلة استخدام لمساحة Gremlin.Net.Driver الاسم.

    using Gremlin.Net.Driver;

  7. إنشاء مثيل جديد لبيانات GremlinServer اعتماد المحاكي واستخدامها GremlinClient .

    var server = new GremlinServer(
    hostname: "localhost",
    port: 65400,
    username: "/dbs/db1/colls/coll1",
    password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

  8. قم بتنظيف الرسم البياني باستخدام SubmitAsync.

    await client.SubmitAsync(
    requestScript: "g.V().drop()"
);

  9. استخدم SubmitAsync مرة أخرى لإضافة عنصر جديد إلى الرسم البياني باستخدام المعلمات المحددة.

    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', prop_id).property('name', prop_name)",
    bindings: new Dictionary<string, object>
    {
        { "prop_id", "68719518371" },
        { "prop_name", "Kiama classic surfboard" }
    }
);

  10. تشغيل تطبيق .NET.

    dotnet run

استخدم Azure Tables SDK ل .NET للاتصال بالمحاكي من تطبيق .NET.

  1. ابدأ في مجلد فارغ.

  2. إنشاء تطبيق وحدة تحكم .NET جديد

    dotnet new console

  3. أضف الحزمة Azure.Data.Tables من NuGet.

    dotnet add package Azure.Data.Tables

  4. افتح ملف Program.cs.

  5. احذف أي محتوى موجود داخل الملف.

  6. إضافة كتلة استخدام لمساحة Azure.Data.Tables الاسم.

    using Azure.Data.Tables;

  7. إنشاء مثيل TableServiceClient جديد لاستخدام بيانات اعتماد المحاكي.

    var serviceClient = new TableServiceClient(
    connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);

  8. استخدم GetTableClient لإنشاء مثيل جديد لاسم TableClient الجدول. ثم تأكد من وجود الجدول باستخدام CreateIfNotExistsAsync.

    var client = serviceClient.GetTableClient(
    tableName: "cosmicworksproducts"
);

await client.CreateIfNotExistsAsync();

  9. إنشاء نوع جديد record للعناصر.

    public record Product : Azure.Data.Tables.ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; init; }

    public Azure.ETag ETag { get; set; }

    public DateTimeOffset? Timestamp { get; set; }
}

  10. إنشاء عنصر جديد في الجدول باستخدام UpsertEntityAsync ووضع Replace .

    var item = new Product
{
    RowKey = "68719518371",
    PartitionKey = "Surfboards",
    Name = "Kiama classic surfboard",
    Timestamp = DateTimeOffset.Now
};

await client.UpsertEntityAsync(
    entity: item,
    mode: TableUpdateMode.Replace
);

  11. تشغيل تطبيق .NET.

    dotnet run

استخدام المحاكي في سير عمل GitHub Actions CI

لتشغيل حمل عمل تكامل مستمر يتحقق تلقائيا من صحة التطبيق الخاص بك، استخدم محاكي Azure Cosmos DB مع مجموعة اختبار من إطار العمل الذي تختاره. يتم تثبيت محاكي Azure Cosmos DB مسبقا في windows-latest متغير المشغلات المستضافة في GitHub Action.

قم بتشغيل مجموعة اختبار باستخدام برنامج تشغيل الاختبار المضمن ل .NET وإطار عمل اختبار مثل MSTest أو NUnit أو XUnit.

  1. تحقق من أن مجموعة اختبار الوحدة للتطبيق الخاص بك تعمل كما هو متوقع.

    dotnet test

  2. إنشاء سير عمل جديد في مستودع GitHub الخاص بك في ملف يسمى .github/workflows/ci.yml.

  3. أضف وظيفة إلى سير العمل لبدء تشغيل محاكي Azure Cosmos DB باستخدام PowerShell وتشغيل مجموعة اختبار الوحدة الخاصة بك.

    name: Continuous Integration
on:
  push:
    branches:
      - main
jobs:
  unit_tests:
    name: Run .NET unit tests
    runs-on: windows-latest
    steps:
      - name: Checkout (GitHub)
        uses: actions/checkout@v3
      - name: Start Azure Cosmos DB emulator
        run: |
          Write-Host "Launching Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - name: Run .NET tests
        run: dotnet test

    إشعار

    ابدأ تشغيل المحاكي من سطر الأوامر باستخدام وسيطات مختلفة أو أوامر PowerShell. لمزيد من المعلومات، راجع وسيطات سطر أوامر المحاكي.

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

مراجعة ملاحظات إصدار المحاكي