الاتصال Azure Functions إلى Azure Cosmos DB باستخدام رمز Visual Studio

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

هل لديك ملاحظات إضافية؟

سيتم إرسال الملاحظات إلى Microsoft: بالضغط على الزر «إرسال»، سيتم استخدام ملاحظاتك لتحسين منتجات Microsoft وخدماتها. نهج الخصوصية.

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

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

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

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

كوِّن بيئتك

قبل البدء، تأكد من تثبيت ملحق قواعد بيانات Azure ل Visual Studio Code.

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

هام

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

1. في Visual Studio Code، اختر أيقونة Azure في شريط النشاط.

2. في منطقة Azure : قواعد البيانات ، انقر بزر الماوس الأيمن (Ctrl+انقر فوق macOS) على اشتراك Azure حيث قمت بإنشاء تطبيق الوظائف الخاص بك في المقالة السابقة، وحدد إنشاء خادم...

   

3. قدّم المعلومات التالية عند المطالبات:

   المطالبة	التحديد
   تحديد خادم قاعدة بيانات Azure	اختر Core (SQL) إنشاء قاعدة بيانات مستندات يمكنك الاستعلام عنها باستخدام بناء جملة SQL. تعرف على المزيد حول واجهة برمجة تطبيقات Azure Cosmos DB SQL.
   اسم الحساب	أدخل اسماً فريداً لتعريف حساب Azure Cosmos DB الخاص بك. لا يمكن أن يستخدم اسم الحساب سوى الأحرف الصغيرة والأرقام والواصلات (-)، ويجب أن يتراوح طولها بين 3 و31 حرفًا.
   حدد نموذج سعة	حدد Serverless لإنشاء حساب في وضع دون خادم.
   تحديد مجموعة موارد للموارد الجديدة	اختر مجموعة الموارد التي أنشأت فيها تطبيق الوظائف في المقالة السابقة.
   حدد موقعاً للموارد الجديدة	حدد موقعًا جغرافيًا لاستضافة حساب Azure Cosmos DB. استخدم الموقع الجغرافي الأقرب إليك أو إلى المستخدمين للحصول على أسرع وصول إلى بياناتك.

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

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

1. انقر بزر الماوس الأيمن فوق حسابك وحدد إنشاء قاعدة بيانات....

2. قدّم المعلومات التالية عند المطالبات:

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

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

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

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

1. في Visual Studio Code، انقر بزر الماوس الأيمن (Ctrl+انقر فوق macOS) على حساب Azure Cosmos DB الجديد، وحدد نسخ سلسلة الاتصال.

   

2. اضغط على F1 لفتح لوحة الأوامر، ثم ابحث عن الأمر Azure Functions: Add New Setting...وقم بتشغيله .

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

   المطالبة	التحديد
   أدخل اسم إعداد التطبيق الجديد	اكتب ⁧CosmosDbConnectionString⁩.
   أدخل قيمة "CosmosDbConnectionString"	الصق سلسلة الاتصال الخاصة بحساب Azure Cosmos DB الذي نسخته للتو.

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

4. اضغط على F1 مرة أخرى لفتح لوحة الأوامر، ثم ابحث عن الأمر Azure Functions: Download Remote Settings...وقم بتشغيله .

5. اختر تطبيق الوظيفة الذي أنشأته في المقالة السابقة. حدد نعم للكل للكتابة فوق الإعدادات المحلية الموجودة.

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

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

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

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

قيد التنفيذ

dotnet add package Microsoft.Azure.WebJobs.Extensions.CosmosDB 

عملية معزولة

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

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

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

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

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

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

في الدالات، يتطلب كل نوع من أنواع الربط تعريف direction، typeوفريد name ليتم تعريفه في ملف function.json. تعتمد الطريقة التي تحدد بها هذه السمات على لغة تطبيق الوظائف.

في مشروع مكتبة فئة C # ، يتم تعريف الروابط كسمات ربط على طريقة الدالة. ثم يتم إنشاء ملف function.json المطلوب بواسطة Functions تلقائيا استنادا إلى هذه السمات.

قيد التنفيذ

فتح ملف المشروع HttpExample.cs وأضف المعلمة التالية إلى Run تعريف الأسلوب:

[CosmosDB(databaseName: "my-database", collectionName: "my-container",
    ConnectionStringSetting = "CosmosDbConnectionString"
    )]IAsyncCollector<dynamic> documentsOut,

المعلمة documentsOut عبارة عن IAsyncCollector<T> نوع يمثل مجموعة من مستندات JSON المكتوبة إلى حاوية قاعدة بيانات Azure Cosmos عند اكتمال الوظيفة. تشير السمات المحددة إلى أسماء الحاوية وقاعدة البيانات الأصلية الخاصة بها. يتم تعيين سلسلة الاتصال لحساب قاعدة بيانات Azure Cosmos الخاص بك بواسطة ConnectionStringSettingAttributeملف .

عملية معزولة

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

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString", 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 وإرجاع رسالة نجاح HTTP. نظرا لأنك تحتاج إلى إرجاع MultiResponse كائن ، فأنت بحاجة أيضا إلى تحديث توقيع الأسلوب.

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

يتم تعريف سمات الربط مباشرة في ملف function.json. اعتمادا على نوع الربط ، قد تكون هناك حاجة إلى خصائص إضافية. يصف تكوين إخراج قاعدة بيانات Azure Cosmos الحقول المطلوبة لربط إخراج قاعدة بيانات Azure Cosmos . يجعل الامتداد من السهل إضافة روابط إلى ملف function.json.

لإنشاء ربط ، انقر بزر الماوس الأيمن (Ctrl + انقر فوق macOS) function.json على الملف في مجلد HttpTrigger واختر إضافة ربط .... اتبع المطالبات لتحديد خصائص الربط التالية للربط الجديد:

المطالبة	القيمة	الوصف
تحديد اتجاه الربط	out	الربط هو ربط الإخراج.
حدد الربط مع الاتجاه "خارج"	Azure Cosmos DB	الربط هو ربط Azure Cosmos DB.
الاسم المستخدم لتحديد هذا الربط في التعليمات البرمجية الخاصة بك	outputDocument	الاسم الذي يحدد معلمة الربط المشار إليها في التعليمات البرمجية.
قاعدة بيانات Cosmos DB حيث ستتم كتابة البيانات	my-database	اسم قاعدة بيانات Azure Cosmos DB التي تحتوي على الحاوية الهدف.
جمع قاعدة البيانات حيث سيتم كتابة البيانات	my-container	اسم حاوية قاعدة بيانات Azure Cosmos حيث ستتم كتابة مستندات JSON.
إذا كان صحيحاً، ينشئ قاعدة بيانات مجموعة Cosmos DB	false	قاعدة البيانات المستهدفة والحاوية موجودة بالفعل.
حدد الإعداد من "local.setting.json"	CosmosDbConnectionString	اسم إعداد تطبيق يحتوي على سلسلة الاتصال لحساب قاعدة بيانات Azure Cosmos.
مفتاح التقسيم (اختياري)	اتركه فارغاً	مطلوب فقط عندما يقوم ربط الإخراج بإنشاء الحاوية.
إنتاجية المجموعة (اختيارية)	اتركه فارغاً	مطلوب فقط عندما يقوم ربط الإخراج بإنشاء الحاوية.

تتم إضافة ربط إلى الصفيف bindings في function.json الخاص بك ، والذي يجب أن يبدو كما يلي بعد إزالة أي undefined قيم موجودة

{
    "type": "cosmosDB",
    "direction": "out",
    "name": "outputDocument",
    "databaseName": "my-database",
    "collectionName": "my-container",
    "createIfNotExists": "false",
    "connectionStringSetting": "CosmosDbConnectionString"
}

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

قيد التنفيذ

إضافة تعليمات برمجية تستخدم كائن ربط المخرجات documentsOut لإنشاء مستند JSON. إضافة هذه التعليمات البرمجية قبل استرجاع الأسلوب.

if (!string.IsNullOrEmpty(name))
{
    // Add a JSON document to the output container.
    await documentsOut.AddAsync(new
    {
        // create a random ID
        id = System.Guid.NewGuid().ToString(),
        name = name
    });
}

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

[FunctionName("HttpExample")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    [CosmosDB(
        databaseName: "my-database",
        collectionName: "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    if (!string.IsNullOrEmpty(name))
    {
        // Add a JSON document to the output container.
        await documentsOut.AddAsync(new
        {
            // create a random ID
            id = System.Guid.NewGuid().ToString(),
            name = name
        });
    }

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
        : $"Hello, {name}. This HTTP triggered function executed successfully.";

    return new OkObjectResult(responseMessage);
}

عملية معزولة

استبدال أسلوب تشغيل موجود بالتعليمة البرمجية التالية:

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

إضافة تعليمات برمجية تستخدم كائن context.bindings ربط المخرجات outputDocument لإنشاء مستند JSON. إضافة هذا الرمز قبل عبارة context.res.

if (name) {
    context.bindings.outputDocument = JSON.stringify({
        // create a random ID
        id: new Date().toISOString() + Math.random().toString().substr(2,8),
        name: name
    });
}

عند هذه النقطة، يجب أن تبدو الدالة الخاصة بك كما يلي:

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const name = (req.query.name || (req.body && req.body.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.";

    if (name) {
        context.bindings.outputDocument = JSON.stringify({
            // create a random ID
            id: new Date().toISOString() + Math.random().toString().substr(2,8),
            name: name
        });
    }

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };
}

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

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

تعليمة Visual Studio برمجية مع ⁧⁩Azure Functions Core tools⁧⁩ للسماح لك بتشغيل هذا المشروع في حاسوب التنمية المحلية الخاص بك قبل أن تقوم بالنشر إلى Azure.

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

   

   إذا واجهتك مشكلة في تشغيل ويندوز، فتأكد من أن المحطة الطرفية الافتراضية للتعليمة البرمجية Visual Studio لم يتم ضبطها على ⁧⁩WSL Bash⁧⁩.

2. مع تشغيل Core Tools، انتقل إلى ⁧⁩ Azure: منطقة ⁧⁩الدوال. تحت ⁧⁩الدوال⁧⁩، قم بتوسيع مشروع ⁧⁩الدوال⁧⁩⁧>⁩⁧⁩المحلية⁧⁩. انقر بزر الماوس الأيمن فوق (Windows) أو اضغط على ⁦⁧⁩⁩Ctrl -⁦⁧⁩⁩ (في macOS) على الدالة HttpExample واختر ⁩⁩تنفيذ الدالة الآن..⁦.⁦⁩.

   

3. في Enter request body اضغط على Enter لإرسال رسالة الطلب هذه إلى وظيفتك.

4. عندما يتم تنفيذ الدالة محليًا وإرجاع استجابة، يظهر إشعار في Visual Studio Code. يتم عرض معلومات حول تنفيذ الدالة في اللوحة ⁩الطرفية⁧⁩.

5. اضغط ⁧⁩«Ctrl + C»⁧⁩ لإيقاف «Core Tools»، وفصل مصحح الأخطاء.

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

1. كما في المقالة السابقة ، اضغط على F5 لبدء مشروع تطبيق الوظيفة والأدوات الأساسية.

2. مع تشغيل الأدوات الأساسية، انتقل إلى ⁧⁩خدمة Azure: منطقة ⁧⁩الدوال. تحت ⁧⁩الدوال⁧⁩، قم بتوسيع مشروع ⁧⁩الدوال⁧⁩⁧>⁩⁧⁩المحلية⁧⁩. انقر بزر الماوس الأيمن (انقر بزر الماوس الأيمن فوق Ctrl على Mac) HttpExample الوظيفة واختر تنفيذ الوظيفة الآن ....

   

3. في إدخال نص الطلب، ترى قيمة نص رسالة الطلب { "name": "Azure" }. اضغط على "Enter" لإرسال رسالة الطلب إلى الدالة الخاصة بك.

4. بعد إرجاع استجابة، اضغط على Ctrl + C لإيقاف الأدوات الأساسية.

تحقق من إنشاء مستند JSON

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

2. قم بتوسيع قاعدة البيانات والحاوية، وحدد العناصر لسرد المستندات التي تم إنشاؤها في الحاوية الخاصة بك.

3. تحقق من إنشاء مستند JSON جديد بواسطة ربط المخرجات.

   

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

1. في فيجوال ستوديو كود، اضغط F1 لفتح لوحة الأوامر. في لوحة الأوامر، قم بالبحث والتحديدAzure Functions: Deploy to function app....

2. اختر تطبيق الوظائف الذي أنشأته في المقالة الأولى. نظرا لأنك تقوم بإعادة نشر مشروعك إلى التطبيق نفسه، حدد نشر لرفض التحذير حول الكتابة فوق الملفات.

3. بعد اكتمال النشر، يمكنك مرة أخرى استخدام ميزة "تنفيذ الوظيفة الآن... لتشغيل الوظيفة في Azure.

4. تحقق مرة أخرى من المستندات التي تم إنشاؤها في حاوية قاعدة بيانات Azure Cosmos للتحقق من أن ربط المخرجات ينشئ مرة أخرى مستند JSON جديدا.

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

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

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

1. في فيجوال ستوديو كود، اضغط F1 لفتح لوحة الأوامر. في لوحة الأوامر، قم بالبحث والتحديدAzure Functions: Open in portal.

2. اختر تطبيق الوظائف، واضغط على زر Enter. تفتح صفحة تطبيق الوظائف في مدخل Azure.

3. في علامة التبويب "Overview" ، حدد الرابط المسمى بجوار مجموعة الموارد.

   

4. في صفحة مجموعة الموارد، راجع قائمة الموارد المضمنة، وتحقق من أنها هي التي تريد حذفها.

5. حدد "Delete resource group" ، واتبع الإرشادات.

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

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

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

• تطوير وظائف Azure باستخدام التعليمات البرمجية Visual Studio

• Azure Functions المشغلات والروابط.

• أمثلة على مشاريع Function الكاملة في C#‎.

• مرجع مُطور C# في Azure Functions

• أمثلة على مشاريع Function الكاملة في JavaScript.

• دليل مطوّر JavaScript في Azure Functions