المحاكي المستند إلى Linux - vNext (معاينة)

الجيل التالي من محاكي Azure Cosmos DB يستند بالكامل إلى Linux ويتوفر كحاوية Docker. وهو يدعم التشغيل على مجموعة واسعة من المعالجات وأنظمة التشغيل.

هام

يدعم هذا الإصدار من المحاكي واجهة برمجة التطبيقات ل NoSQL فقط في وضع البوابة، مع مجموعة فرعية محددة من الميزات. لمزيد من المعلومات، راجع دعم الميزات.

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

• Docker

التثبيت

احصل على صورة حاوية Docker باستخدام docker pull. يتم نشر صورة الحاوية إلى Microsoft Artifact Registry ك mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

قيد التشغيل

لتشغيل الحاوية، استخدم docker run. بعد ذلك، استخدم docker ps للتحقق من تشغيل الحاوية.

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

إشعار

يتكون المحاكي من مكونين:

• مستكشف البيانات - استكشاف البيانات في المحاكي بشكل تفاعلي. بشكل افتراضي، يتم تشغيل هذا على المنفذ 1234
• محاكي Azure Cosmos DB - إصدار محلي من خدمة قاعدة بيانات Azure Cosmos DB. بشكل افتراضي، يتم تشغيل هذا على المنفذ 8081.

عادة ما تتوفر نقطة نهاية بوابة المحاكي على المنفذ 8081 في العنوان http://localhost:8081. للانتقال إلى مستكشف البيانات، استخدم العنوان http://localhost:1234 في مستعرض الويب. قد يستغرق الأمر بضع ثوان حتى يتوفر مستكشف البيانات. عادة ما تكون نقطة نهاية البوابة متاحة على الفور.

هام

لا تدعم .NET وJava SDKs وضع HTTP في المحاكي. نظرا لأن هذا الإصدار من المحاكي يبدأ ب HTTP بشكل افتراضي، فستحتاج إلى تمكين HTTPS بشكل صريح عند بدء تشغيل الحاوية (انظر أدناه). بالنسبة إلى Java SDK، ستحتاج أيضا إلى تثبيت الشهادات.

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

أوامر Docker

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

المتطلبات	الارجنتين	الحياه الفطريه	القيم المسموح بها	افتراضي	‏‏الوصف
طباعة الإعدادات إلى stdout من الحاوية	--help، -h	‏‫غير متوفر‬	‏‫غير متوفر‬	‏‫غير متوفر‬	عرض معلومات حول التكوين المتوفر
تعيين منفذ نقطة نهاية Cosmos	--port [INT]	ميناء	Int	8081	منفذ نقطة نهاية Cosmos على الحاوية. لا تزال بحاجة إلى نشر هذا المنفذ (على سبيل المثال، -p 8081:8081).
تحديد البروتوكول المستخدم بواسطة نقطة نهاية Cosmos	--protocol	بروتوكول	https، ، httphttps-insecure	http	بروتوكول نقطة نهاية Cosmos على الحاوية.
تمكين مستكشف البيانات	--enable-explorer	ENABLE_EXPLORER	true، false	true	تمكين تشغيل Cosmos Data Explorer على نفس الحاوية.
تعيين المنفذ المستخدم من قبل مستكشف البيانات	--explorer-port	EXPLORER_PORT	Int	1234	منفذ Cosmos Data Explorer على الحاوية. لا تزال بحاجة إلى نشر هذا المنفذ (على سبيل المثال، -p 1234:1234).
يجب أن يكون المستخدم قادرا على تحديد البروتوكول المستخدم من قبل المستكشف، وإلا افتراضيا لما تستخدمه نقطة نهاية Cosmos	--explorer-protocol	EXPLORER_PROTOCOL	https، ، httphttps-insecure	<the value of --protocol>	بروتوكول Cosmos Data Explorer على الحاوية. الإعدادات الافتراضية لإعداد البروتوكول على نقطة نهاية Cosmos.
تحديد المفتاح عبر الملف	--key-file [PATH]	KEY_FILE	مسار	<default secret>	تجاوز المفتاح الافتراضي بالمفتاح المحدد في الملف. تحتاج إلى تحميل هذا الملف في الحاوية (على سبيل المثال، إذا كان KEY_FILE=/mykey، يمكنك إضافة خيار مثل ما يلي إلى تشغيل docker الخاص بك: --mount type=bind,source=./myKey,target=/myKey)
تعيين مسار البيانات	--data-path [PATH]	DATA_PATH	مسار	/data	حدد دليلا للبيانات. يستخدم بشكل متكرر مع docker run --mount الخيار (على سبيل المثال، إذا DATA_PATH=/usr/cosmos/data، يمكنك إضافة خيار مثل ما يلي إلى تشغيل docker الخاص بك: --mount type=bind,source=./.local/data,target=/usr/cosmos/data)
حدد مسار الشهادة الذي سيتم استخدامه ل https	--cert-path [PATH]	CERT_PATH	مسار	<default cert>	حدد مسارا إلى شهادة لتأمين نسبة استخدام الشبكة. تحتاج إلى تحميل هذا الملف في الحاوية (على سبيل المثال، إذا CERT_PATH=/mycert.pfx، يمكنك إضافة خيار مثل ما يلي إلى تشغيل docker الخاص بك: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx)
حدد سر الشهادة الذي سيتم استخدامه ل https	‏‫غير متوفر‬	CERT_SECRET	سلسلة	<default secret>	سر الشهادة المحددة في CERT_PATH.
تعيين مستوى السجل	--log-level [LEVEL]	LOG_LEVEL	quiet، error، warn، info، ، debugtrace	info	إسهاب السجلات التي يصدرها المحاكي ومستكشف البيانات.
تمكين إرسال معلومات التشخيص إلى Microsoft	--enable-telemetry	ENABLE_TELEMETRY	true، false	true	تمكين إرسال السجلات إلى Microsoft لمساعدتنا على تحسين المحاكي.

دعم الميزة

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

ميزة	الدعم
واجهة برمجة تطبيقات الدفعات	✅ مدعم
واجهة برمجة التطبيقات المجمعة	✅ مدعم
موجز التغيير	✅ مدعم
إنشاء مستند وقراءته باستخدام بيانات utf	✅ مدعم
إنشاء مجموعة	✅ مدعم
إنشاء مجموعة مرتين تعارض	✅ مدعم
إنشاء مجموعة باستخدام نهج الفهرس المخصص	⚠️ لم يتم تنفيذها بعد
إنشاء مجموعة مع انتهاء صلاحية ttl	✅ مدعم
إنشاء قاعدة بيانات	✅ مدعم
إنشاء قاعدة بيانات مرتين متعارضة	✅ مدعم
إنشاء مستند	✅ مدعم
إنشاء مجموعة مقسمة	✅ مدعم
حذف مجموعة	✅ مدعم
حذف قاعدة البيانات	✅ مدعم
حذف مستند	✅ مدعم
الحصول على أداء المجموعة وتغييره	⚠️ لم يتم تنفيذها بعد
إدراج مستند كبير	✅ مدعم
تصحيح المستند	✅ مدعم
الاستعلام عن المجموعة المقسمة بالتوازي	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام التجميعات	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام وتصفية	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام وتصفية وإسقاط	⚠️ لم يتم تنفيذها بعد
الاستعلام بالمساواة	✅ مدعم
الاستعلام بالتساوي على المعرف	✅ مدعم
الاستعلام مع الصلات	⚠️ لم يتم تنفيذها بعد
الاستعلام بالترتيب حسب	✅ مدعم
الاستعلام بترتيب للمجموعة المقسمة	⚠️ لم يتم تنفيذها بعد
الاستعلام بترتيب حسب الأرقام	✅ مدعم
الاستعلام بترتيب حسب السلاسل	⚠️ لم يتم تنفيذها بعد
استعلام مع ترحيل الصفحات	⚠️ لم يتم تنفيذها بعد
الاستعلام بأوقات تاريخ عوامل تشغيل النطاق	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام عوامل تشغيل النطاق على الأرقام	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام عوامل تشغيل النطاق على السلاسل	⚠️ لم يتم تنفيذها بعد
استعلام بصلة واحدة	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام عوامل تشغيل السلسلة الرياضية والصفيف	⚠️ لم يتم تنفيذها بعد
الاستعلام باستخدام المستندات الفرعية	⚠️ لم يتم تنفيذها بعد
استعلام بصلتين	⚠️ لم يتم تنفيذها بعد
استعلام بصلتين وتصفية	⚠️ لم يتم تنفيذها بعد
مجموعة القراءة	✅ مدعم
قراءة موجز المجموعة	⚠️ لم يتم تنفيذها بعد
قراءة قاعدة البيانات	✅ مدعم
قراءة موجز قاعدة البيانات	⚠️ لم يتم تنفيذها بعد
قراءة المستند	✅ مدعم
قراءة موجز المستند	✅ مدعم
استبدال المستند	✅ مدعم
وحدات الطلب	⚠️ لم يتم تنفيذها بعد
الإجراءات المخزنة	❌ غير مخطط له
المشغلات	❌ غير مخطط له
UDFs	❌ غير مخطط له
مجموعة التحديث	⚠️ لم يتم تنفيذها بعد
تحديث المستند	✅ مدعم

القيود

بالإضافة إلى الميزات غير المدعومة أو غير المخطط لها، تتضمن القائمة التالية القيود الحالية للمحاكي.

• لا يدعم .NET SDK ل Azure Cosmos DB التنفيذ المجمع في المحاكي.
• لا تدعم .NET وJava SDKs وضع HTTP في المحاكي.

تثبيت شهادات ل Java SDK

عند استخدام Java SDK ل Azure Cosmos DB مع هذا الإصدار من المحاكي في وضع https، من الضروري تثبيت شهاداته على مخزن ثقة Java المحلي.

الحصول على الشهادة

bash في نافذة، قم بتشغيل ما يلي:

# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH

تثبيت الشهادة

انتقل إلى دليل تثبيت java حيث cacerts يوجد الملف (استبدل أدناه بالدليل الصحيح):

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

استيراد الشهادة (قد يطلب منك كلمة مرور، القيمة الافتراضية هي "changeit"):

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

إذا تلقيت خطأ لأن الاسم المستعار موجود بالفعل، فاحذفه ثم قم بتشغيل ما سبق مرة أخرى:

keytool -cacerts -delete -alias cosmos_emulator

استخدام في سير عمل التكامل المستمر

هناك الكثير من الفوائد لاستخدام حاويات Docker في مسارات CI/CD، خاصة للأنظمة ذات الحالة مثل قواعد البيانات. قد يكون ذلك من حيث فعالية التكلفة والأداء والموثوقية والاتساق في مجموعات الاختبار الخاصة بك.

يمكن دمج المحاكي كجزء من البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD. يمكنك الرجوع إلى مستودع GitHub هذا الذي يوفر أمثلة حول كيفية استخدام المحاكي كجزء من سير عمل GitHub Actions CI لتطبيقات .NET وPython وJava وGo على كل من x64 البنيتين و ARM64 (موضحة لمشغل Linux باستخدام ubuntu).

فيما يلي مثال على سير عمل GitHub Actions CI الذي يوضح كيفية تكوين المحاكي كحاوية خدمة GitHub Actions كجزء من مهمة في سير العمل. يهتم GitHub ببدء تشغيل حاوية Docker ويدمرها عند اكتمال المهمة، دون الحاجة إلى التدخل اليدوي (مثل استخدام docker run الأمر).

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

تعمل هذه المهمة على مشغل Ubuntu وتستخدم mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview صورة Docker كحاوية خدمة. يستخدم متغيرات البيئة لتكوين سلسلة الاتصال واسم قاعدة البيانات واسم الحاوية. نظرا لأنه في هذه الحالة يتم تشغيل المهمة مباشرة على جهاز مشغل GitHub Actions، يمكن الوصول إلى خطوة تشغيل الاختبارات في الوظيفة إلى المحاكي باستخدام localhost:8081 (8081 هو المنفذ الذي يعرضه المحاكي).

خطوة تصدير شهادة محاكي Cosmos DB خاصة بتطبيقات Java نظرا لأن Azure Cosmos DB Java SDK لا يدعم HTTP حاليا الوضع في المحاكي. PROTOCOL يتم تعيين متغير البيئة إلى https في services القسم وتصدر هذه الخطوة شهادة المحاكي وتستوردها إلى مخزن مفاتيح Java. وينطبق الشيء نفسه على .NET أيضا.

الإبلاغ عن المشكلات

إذا واجهت مشكلات في استخدام هذا الإصدار من المحاكي، فافتح مشكلة في مستودع GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) وضع علامة عليها بالتسمية cosmosEmulatorVnextPreview.