Connect Azure Functions to Azure Cosmos DB using Visual Studio Code

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

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

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

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

إشعار

تدعم هذه المقالة Node.js الإصدار الرابع للوظائف.

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

تكوين بيئتك

قبل أن get started، تأكد من تثبيت ><إضافة قواعد البيانات Azure لكود Visual Studio.

أنشئ حسابك في قاعدة بيانات Azure Cosmos

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لأنك تستخدم ملف مخرجات Azure Cosmos DB، يجب أن يكون لديك إضافة bindings المقابلة مثبتة قبل تشغيل project.

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

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

تم تكوين project الخاص بك ليستخدم <حزم >التوسيط، التي تقوم تلقائيا بتثبيت مجموعة محددة مسبقا من حزم الإضافات.

يتم تفعيل استخدام حزم الامتدادات في ملف host.json في جذر project، والذي يظهر كما يلي:

{
  "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"
    }
  }
}

تم تكوين project الخاص بك ليستخدم <حزم >التوسيط، التي تقوم تلقائيا بتثبيت مجموعة محددة مسبقا من حزم الإضافات.

يتم تفعيل استخدام حزم الامتدادات في ملف host.json في جذر project، والذي يظهر كما يلي:

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

الآن، يمكنك إضافة رابط إخراج قاعدة بيانات Azure Cosmos إلى project الخاص بك.

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

في project مكتبة فئة C#، تعرف الروابط كسمات ربط على طريقة الدالة.

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

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

MyDocumentتحدد الفئة عنصر تتم كتابته في قاعدة البيانات. يتم تحديد connection string الحساب Storage بواسطة خاصية Connection. في هذه الحالة، يمكنك حذف Connection لأنك بالفعل تستخدم حساب storage الافتراضي.

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

تحدد السمات المحددة الاسم الخاص بالحاوية والاسم الخاص بقاعدة البيانات الأصل الخاصة بها. connection string حساب قاعدة بيانات كوزموس Azure الخاص بك يتم تحديده بواسطة CosmosDbConnectionString.

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

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="CosmosDbConnectionString")

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

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

استبدل الطريقة الحالية Run بالرمز التالي:

[Function("HttpExample")]
public MultiResponse Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    // 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 = new OkObjectResult(message)
    };
}

أضف التعليمات البرمجية 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.

تحديث 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.FUNCTION)
@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="CosmosDbConnectionString")
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 الأساسية ليتيح لك تشغيل هذا project على جهاز التطوير المحلي قبل النشر على Azure. إذا لم يكن لديك Core Tools مثبتا محليا، يطلب منك تثبيته في المرة الأولى التي تشغل فيها project.

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

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

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

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

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

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

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

في Visual Studio Code، اضغط F1 لفتح لوحة الأوامر. في لوحة الأوامر، ابحث عن Azure Functions: Deploy to function app... واختره.
اختر تطبيق الوظائف الذي إنشاته في المقالة الأولى. لأنك تعيد نشر project في نفس التطبيق، اختر Deploy لإلغاء التحذير حول استبدال الملفات.
بعد اكتمال النشر، يمكنك مرة أخرى استخدام وظيفة تنفيذ الآن... ميزة لتفعيل الوظيفة في Azure. يقوم هذا الأمر تلقائيا باسترجاع مفتاح access للوظيفة ويستخدمه عند استدعاء نقطة نهاية مشغل HTTP.
مرة أخرى، تحقق من المستندات التي تم إنشاؤها في حاوية قاعدة بيانات كوزموس Azure للتحقق من أن الربط الناتج يولد مستند JSON جديد مرة أخرى.

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

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

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

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

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

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-03-11

مشاركة عبر

Connect Azure Functions to Azure Cosmos DB using Visual Studio Code

تكوين بيئتك

أنشئ حسابك في قاعدة بيانات Azure Cosmos

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

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

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

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

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

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

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

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

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

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

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

الملاحظات

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