توصيل Azure Functions بـ Azure Cosmos DB عن طريق استخدام Visual Studio Code

مقالة
04/25/2024

تتيح Azure Functions توصيل خدمات Azure والموارد الأخرى بوظائف دون الحاجة إلى كتابة رمز التكامل. تُعرَّف هذهالارتباطات، التي تمثل الإدخال والإخراج، ضمن تعريف الدالة. يتم توفير البيانات من الارتباطات للوظيفة في صورة معلمات. المشغل هو نوع خاص من ربط الإدخال. على الرغم من أن الدالة تحتوي على مشغل واحد فقط، إلا أنها يمكن أن تحتوي على روابط إدخال وإخراج متعددة. لمعرفة المزيد، راجع مفاهيم مشغلات وروابط دالات Azure.

توضح لك هذه المقالة كيفية استخدام Visual Studio Code لتوصيل Azure Cosmos DB بالوظيفة التي أنشأتها في المقالة السابقة للتشغيل السريع. يكتب ربط الإخراج الذي تضيفه إلى هذه الوظيفة البيانات من طلب HTTP إلى مستند JSON المخزن في حاوية Azure Cosmos DB.

قبل البدء، يتعين إكمالالتشغيل السريع: إنشاء دالة C# في Azure باستعمال Visual Studio Code. إذا قمت بالفعل بتنظيف الموارد في نهاية هذه المقالة، فانتقل إلى الخطوات مرة أخرى لإعادة إنشاء تطبيق الدالة والموارد ذات الصلة في Azure.

قبل البدء، يتعين إكمالالتشغيل السريع: إنشاء دالة JavaScript في Azure باستعمال Visual Studio Code. إذا قمت بالفعل بتنظيف الموارد في نهاية هذه المقالة، فانتقل إلى الخطوات مرة أخرى لإعادة إنشاء تطبيق الدالة والموارد ذات الصلة في Azure.

إشعار

تدعم هذه المقالة حاليا Node.js v3 للدالات فقط.

قبل البدء، يجب إكمال التشغيل السريع: إنشاء دالة Python في Azure باستخدام Visual Studio Code. إذا قمت بالفعل بتنظيف الموارد في نهاية هذه المقالة، فانتقل إلى الخطوات مرة أخرى لإعادة إنشاء تطبيق الدالة والموارد ذات الصلة في Azure.

تكوين بيئتك

قبل البدء، تأكد من تثبيت الملحق الخاص بـ Azure Databases لـ Visual Studio Code.

إنشاء حساب Azure Cosmos DB الخاص بك

الآن، يمكنك إنشاء حساب Azure Cosmos DB كنوع حساب بلا خادم. يعمل هذا الوضع على جعل القائم على الاستهلاك Azure Cosmos DB خيارًا قويًا لأحمال العمل بلا خادم.

في Visual Studio Code، حدد View>Command Palette... ثم في لوحة الأوامر ابحث عن Azure Databases: Create Server...

قدِّم المعلومات التالية في المطالبات:

المطالبة	التحديد
حدد Azure Database Server	اختر Core (NoSQL) لإنشاء قاعدة بيانات مستندات يمكنك الاستعلام بها باستخدام بناء جملة SQL أو Query Copilot (معاينة) لتحويل مطالبات اللغة الطبيعية إلى استعلامات. تعرف على المزيد حول Azure Cosmos DB.
Account name	أدخل اسماً فريداً لتعريف حساب Azure Cosmos DB الخاص بك. لا يمكن أن يستخدم اسم الحساب سوى الأحرف الصغيرة والأرقام والواصلات (-)، ويجب أن يتراوح طولها بين 3 و31 حرفًا.
حددcapacity model	حدد Serverless لإنشاء حساب في وضع دون خادم.
حدد resource group للموارد الجديدة	اختر resource group التي أنشأت فيها تطبيق الوظائف في المقالة السابقة.
حدد موقعاً للموارد الجديدة	حدد موقعًا جغرافيًّا لاستضافة حساب Azure Cosmos DB. استعمل الموقع الأقرب إلى مستخدميك لمنحهم أسرع وصول إلى البيانات.

بعد توفير حسابك الجديد، تعرض رسالة في مساحة الإعلام.

إنشاء حساب Azure Cosmos DB وقاعدة البيانات، والحاوية

حدد أيقونة Azure في شريط النشاط، وقم بتوسيع Resources>Azure Cosmos DB، وانقر بزر الماوس الأيمن (Ctrl+select على macOS) على حسابك، وحدد Create database....

قدِّم المعلومات التالية في المطالبات:

المطالبة	التحديد
اسم قاعدة البيانات	اكتب`my-database`.
الإدخال والمعرف للمجموعة الخاصة بك	اكتب`my-container`.
أدخل مفتاح القسم الخاص بالمجموعة	اكتب `/id` باعتباره مفتاح القسم.

حدد OK لإنشاء الحاوية وقاعدة البيانات.

تحديث إعدادات تطبيق الوظائف

في مقالة Quickstart السابقة، قمت بإنشاء تطبيق وظيفي في Azure. في هذه المقالة، يمكنك تحديث تطبيقك لكتابة مستندات JSON إلى حاوية Azure Cosmos DB التي أنشأتها. للاتصال بحساب Azure Cosmos DB الخاص بك، يتعين إضافة سلسلة الاتصال الخاصة به إلى إعدادات التطبيق. ثم تنزِّل الإعداد الجديد إلى ملف local.settings.json حتى تستطيع الاتصال بحساب Azure Cosmos DB الخاص بك عند التشغيل محليًا.

في Visual Studio Code، انقر بزر الماوس الأيمن (Ctrl+select على macOS) على حساب Azure Cosmos DB الجديد، وحدد Copy Connection String.
اضغط على F1 لفتح لوحة الأوامر، ثم ابحث عن الأمر Azure Functions: Add New Setting...وشغلة.

اختر تطبيق الدالة الذي أنشأته في المقالة السابقة. قدِّم المعلومات التالية في المطالبات:

المطالبة	التحديد
أدخل اسم إعداد التطبيق الجديد	اكتب`CosmosDbConnectionSetting`.
أدخل قيمة ل "CosmosDbConnectionSetting"	الصق سلسلة الاتصال حساب Azure Cosmos DB الذي نسخته. يمكنك أيضا تكوين هوية Microsoft Entra كبديل.

يعمل ذلك على إنشاء إعداد تطبيق يسمى الاتصال CosmosDbConnectionSetting في تطبيق الوظائف في Azure. الآن، تستطيع تنزيل هذا الإعداد إلى ملف local.settings.json.

اضغط F1 لفتح اللوحة الخاصة بالأوامر، ثم ابحث عن الأمر Azure Functions: Download Remote Settings...وشغلة.
اختر تطبيق الدالة الذي أنشأته في المقالة السابقة. حدد Yes to all للكتابة فوق الإعدادات المحلية الموجودة.

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

تسجيل ملحقات الربط

نظرًا لأنك تستخدم ربط إخراج Azure Cosmos DB، يتعين أن يكون لديك ملحق الارتباطات المقابل مثبتًا قبل تشغيل المشروع.

باستثناء HTTP والمشغلات الموقتة، يتم تنفيذ الارتباطات كحزم ملحقة. شغل الأمر التالي dotnet add package في نافذة terminal الطرفية لإضافة حزمة ملحق التخزين إلى المشروع الخاص بك.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

تم تكوين المشروع الخاص بك لاستخدام مجموعة الملحقات، والتي تقوم تلقائيًا بتثبيت مجموعة محددة مسبقًا من حزم الملحقات.

يتم تمكين استخدام مجموعة الملحقات في ملف host.json في جذر المشروع، والذي يظهر على النحو التالي:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

يتم تمكين استخدام مجموعة الملحقات في ملف host.json في جذر المشروع، والذي يظهر على النحو التالي:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  } 
}

الآن، يمكنك إضافة ربط إخراج Azure Cosmos DB بالمشروع الخاص بك.

إضافة ربط المخرجات

في مشروع مكتبة فئة C #، يتم تعريف الارتباطات على أنها سمات ربط في أسلوب الوظيفة.

افتح ملف مشروع HttpExample.cs وأضف الفئة التالية:

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

MyDocumentتحدد الفئة عنصر تتم كتابته في قاعدة البيانات. يتم تعيين سلسلة الاتصال لحساب التخزين حسب الخاصية Connection. في هذه الحالة، يمكنك حذف Connection لأنك تستخدم حساب التخزين الافتراضي بالفعل.

MultiResponse تتيح لك الفئة بالكتابة إلى المجموعة المحددة في Azure Cosmos DB وإرجاع رسالة نجاح HTTP. نظرًا لأنك تحتاج إلى إرجاع عنصرMultiResponse، تحتاج أيضًا إلى تحديث توقيع الأسلوب.

تحدد السمات المحددة الاسم الخاص بالحاوية والاسم الخاص بقاعدة البيانات الأصل الخاصة بها. تعيين سلسلة الاتصال لحساب Azure Cosmos DB الخاص بواسطةCosmosDbConnectionSetting.

يتم تعريف سمات الربط مباشرة في التعليمات البرمجية للدالة. يصف تكوين إخراج Azure Cosmos DB الحقول المطلوبة لعملية ربط إخراج Azure Cosmos DB.

MultiResponse لهذا السيناريو، تحتاج إلى إضافة extraOutputs ربط إخراج إلى الدالة .

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

أضف الخصائص التالية إلى تكوين الربط:

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

يتم تعريف سمات الربط مباشرة في ملف function_app.py . يمكنك استخدام cosmos_db_output مصمم الديكور لإضافة ربط إخراج Azure Cosmos DB:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

في هذه التعليمة البرمجية، arg_name تحدد معلمة الربط المشار إليها في التعليمات البرمجية الخاصة بك، database_name container_name وهي أسماء قاعدة البيانات والمجموعة التي يكتب الربط إليها، وهي connection اسم إعداد تطبيق يحتوي على سلسلة الاتصال لحساب Azure Cosmos DB، الموجود في CosmosDbConnectionSetting الإعداد في ملف local.settings.json.

إضافة التعليمات البرمجية التي تستخدم ربط المخرجات

استبدل طريقة التشغيل الحالية بالتعليمة البرمجية التالية:

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

أضف التعليمات البرمجية extraInputs التي تستخدم كائن ربط الإخراج على context لإرسال مستند JSON إلى دالة ربط الإخراج المسماة، sendToCosmosDb. إضافة هذا الرمز قبل عبارة return.

context.extraOutputs.set(sendToCosmosDb, {
  // create a random ID
  id:
    new Date().toISOString() + Math.random().toString().substring(2, 10),
  name: name,
});

في هذه المرحلة، يجب أن تبدو الدالة كما يلي:

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

ترجع هذه التعليمة البرمجية الآن عنصر MultiResponse يحتوي على كل من مستند واستجابة HTTP.

تحديث HttpExample\function_app.py لمطابقة التعليمات البرمجية التالية. أضف المعلمة outputDocument إلى تعريف الدالة وضمن outputDocument.set() العبارة if name: :

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

يتم إنشاء المستند {"id": "name"} في مجموعة قاعدة البيانات المحددة في الربط.

تشغيل الدالة محليًا

يتكامل Visual Studio Code مع أدوات Azure Functions Core للسماح لك بتشغيل هذا المشروع على كمبيوتر التطوير المحلي قبل النشر إلى Azure. إذا لم يكن لديك Core Tools مثبتة محليا بالفعل، فستتم مطالبتك بتثبيتها في المرة الأولى التي تقوم فيها بتشغيل مشروعك.

للاتصال بالوظيفة اضغط على F5 لبدء مشروع تطبيق الوظائف. تعرض لوحة Terminal عملية الإخراج من Core Tools. يبدأ تطبيقك في لوحة المحطة الطرفية. يمكنك مشاهدة نقطة نهاية URL للوظيفة التي تم تشغيلها بواسطة HTTP وتعمل محليًا.

إذا لم يكن لديك Core Tools مثبتة بالفعل، فحدد Install لتثبيت Core Tools عند مطالبتك بذلك.
إذا كنت تواجه مشكلة في التشغيل على Windows، فتأكد من عدم تعيين المحطة الطرفية الافتراضية ل Visual Studio Code إلى WSL Bash.
مع تشغيل Core Tools، انتقل إلى مساحة Azure: Functions. ضمن Functions وسع Local Project>Functions. انقر بزر الماوس الأيمن (Windows) أو Ctrl - انقر فوق الدالة (macOS) HttpExample واختر تنفيذ الدالة الآن....
في Enter request body اضغط Enter لإرسال رسالة الطلب هذه إلى الوظيفة الخاصة بك.
عند تنفيذ الوظيفة محليًا وإرجاع استجابة، يرفع تنبيه في Visual Studio التعليمات البرمجية. تعرض المعلومات حول تنفيذ الدالة في لوحة Terminal.
اضغط على Ctrl + C لإيقاف Core Tools وقطع اتصال مصحح الأخطاء.

تشغيل الدالة محليًا

كما هو الحال في المقالة السابقة، اضغط F5 لبدء مشروع تطبيق الوظائف وأدوات الذاكرة الرئيسة.
مع تشغيل الأدوات الأساسية، انتقل إلى منطقة Azure: Functions. ضمن Functions وسع Local Project>Functions. انقر بزر الماوس الأيمن (Windows) أو Ctrl مع النقر في Mac على وظيفة HttpExample واختر Execute Function Now....
في Enter request body سترى قيمة نص رسالة الطلب الخاصة { "name": "Azure" }. اضغط فوق Enter لإرسال رسالة الطلب هذه إلى الوظيفة الخاصة بك.
بعد إرجاع الاستجابة، اضغط Ctrl + C لإيقاف Core Tools.

تأكد من إنشاء مستند JSON

في مدخل Microsoft Azure، ارجع إلى الحساب الخاص بـ Azure Cosmos DB وحدد Data Explorer.
قم بتوسيع قاعدة البيانات والحاوية، وحدد Items لسرد المستندات التي تم إنشاؤها في الحاوية الخاصة بك.
تحقق من إنشاء مستند JSON جديد عن طريق ربط الإخراج.

إعادة نشر التطبيق المحدث والتحقق منه

لفتح لوحة الأوامر في تعليمة Visual Studio البرمجية، اضغط على F1. في لوحة الأوامر، ابحث عن Azure Functions: Deploy to function app... واختره.
اختر تطبيق الوظائف الذي إنشاته في المقالة الأولى. نظرًا لأنك تقوم بإعادة توزيع مشروعك إلى نفس التطبيق، حدد Deploy لتجاهل التحذير حول الكتابة فوق الملفات.
بعد اكتمال التوزيع، يمكنك مرة أخرى استخدام ميزةExecute Function Now... لتشغيل الدالة في Azure.
تحقق مرة ثانية من المستندات التي تم إنشاؤها في حاوية Azure Cosmos DB للتحقق من أن ربط الإخراج ينشئ مرة أخرى مستند JSON جديدا.

تنظيف الموارد

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

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

لفتح لوحة الأوامر في تعليمة Visual Studio البرمجية، اضغط على F1. في لوحة الأوامر، ابحث عن Azure: Open in portal واختره.
اختر التطبيق الخاص بالوظائف، واضغط زر Enter. تفتح صفحة تطبيق الوظيفة في مدخل Microsoft Azure.
في علامة التبويب نظرة عامة حدد الارتباط المسمى بجوار Resource group.
في صفحة مجموعة الموارد، راجع قائمة الموارد المدرجة وتحقق من أنها هي التي تريد حذفها.
حدد حذف مجموعة الموارد، واتبع الإرشادات.

قد يستغرق الحذف دقيقتين. عند الانتهاء من ذلك، يظهر تنبيه لبضع ثوان. يمكنك أيضا تحديد رمز الجرس في أعلى الصفحة لعرض التنبيه.

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

قمت بتحديث الوظيفة التي تم تشغيلها من قبل HTTP لكتابة مستندات JSON إلى حاوية Azure Cosmos DB. الآن يمكنك معرفة المزيد حول تطوير الوظائف باستعمال Visual Studio Code:

مشاركة عبر

توصيل Azure Functions بـ Azure Cosmos DB عن طريق استخدام Visual Studio Code

تكوين بيئتك

إنشاء حساب Azure Cosmos DB الخاص بك

إنشاء حساب Azure Cosmos DB وقاعدة البيانات، والحاوية

تحديث إعدادات تطبيق الوظائف

تسجيل ملحقات الربط

إضافة ربط المخرجات

إضافة التعليمات البرمجية التي تستخدم ربط المخرجات

تشغيل الدالة محليًا

تشغيل الدالة محليًا

تأكد من إنشاء مستند JSON

إعادة نشر التطبيق المحدث والتحقق منه

تنظيف الموارد

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

الملاحظات

الموارد الإضافية