ربط إخراج Azure Cosmos DB لوظائف Azure 2.x وأعلى

  • مقالة
  • قراءة خلال 19 دقائق

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

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

مثال

ما لم يذكر خلاف ذلك، تستهدف الأمثلة الواردة في هذه المقالة الإصدار 3.x من ملحق قاعدة بيانات Azure Cosmos. للاستخدام مع الإصدار الإضافي 4.x ، تحتاج إلى استبدال السلسلة collection في أسماء الخصائص والسمات ب container.

يحتوي هذا القسم على الأمثلة التالية:

تشير الأمثلة إلى نوع ToDoItem بسيط:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

مشغل قائمة الانتظار، كتابة مستند واحد

يظهر المثال التالي دالة C#‎ التي تضيف مستندًا إلى قاعدة بيانات، باستخدام البيانات المتوفرة في رسالة من مخزن قائمة الانتظار.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

مشغل قائمة الانتظار، كتابة مستند واحد (ملحق v4)

التطبيقات التي تستخدم Cosmos DB إصدار 4.x للملحق أو أعلى سيكون لها خصائص سمات مختلفة والتي تظهر أدناه. يظهر المثال التالي دالة C#‎ التي تضيف مستندًا إلى قاعدة بيانات، باستخدام البيانات المتوفرة في رسالة من مخزن قائمة الانتظار.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

مشغل قائمة الانتظار، كتابة مستندات باستخدام IAsyncCollector

يظهر المثال التالي دالة C#‎ التي تضيف مستندًا إلى قاعدة بيانات، باستخدام البيانات المتوفرة في JSON رسالة قائمة الانتظار.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

يمكن إنشاء الدالة C # باستخدام أحد أوضاع C # التالية:

قائمة انتظار المشغل، حفظ الرسالة إلى قاعدة البيانات عبر القيمة المرجعة

يظهر المثال التالي دالة Java التي تضيف مستندًا إلى قاعدة البيانات مع بيانات من رسالة في محزن قائمة الانتظار.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

مشغل HTTP، حفظ مستند واحد إلى قاعدة البيانات عبر القيمة المرجعة

يظهر المثال التالي دالة Java التي تم توضيح توقيعها بـ @CosmosDBOutput بالقيمة المرجعة من نوع String. سيتم كتابة المستند JSON الذي تم إرجاعه بواسطة الدالة تلقائيًا إلى مجموعة CosmosDB المطابقة.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

مشغل HTTP، حفظ مستند واحد إلى قاعدة البيانات عبر OutputBinding

يظهر المثال التالي دالة Java التي تكتب مستند إلى CosmosDB عبر معلمة إخراج OutputBinding<T>. في هذا المثال، المعلمة outputItem يجب أن تكون موضحة بـ @CosmosDBOutput، وليس بتوقيع الدالة. يتيح استخدام OutputBinding<T> للدالة الاستفادة من الربط لكتابة المستند إلى CosmosDB بينما يسمح أيضًا بإرجاع قيمة مختلفة إلى مستدعي الدالة مثل مستند JSON أو XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

مشغل HTTP، حفظ مستندات متعددة إلى قاعدة البيانات عبر OutputBinding

يظهر المثال التالي دالة Java التي تكتب مستندات متعددة إلى CosmosDB عبر معلمة إخراج OutputBinding<T>. في هذا المثال، المعلمة outputItem موضحة بـ @CosmosDBOutput، وليس بتوقيع الدالة. معلمة الإخراج، outputItem تحتوي على قائمة بالعناصر ToDoItem كنوع معلمة القالب الخاص بها. يتيح استخدام OutputBinding<T> للدالة الاستفادة من الربط لكتابة المستندات إلى CosmosDB بينما يسمح أيضًا بإرجاع قيمة مختلفة إلى مستدعي الدالة مثل مستند JSON أو XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي @CosmosDBOutput على المعلمات التي سيتم كتابتها إلى Cosmos DB. يجب أن يكون نوع معلمة التعليق التوضيحي OutputBinding<T>، حيث T هو إما نوع Java أصلي أو POJO.

يظهر المثال التالي رابط إخراج Azure Cosmos DB في ملف function.json و دالة JavaScript التي تستخدم الرابط. تستخدم الدالة رابط إدخال قائمة انتظار لقائمة انتظار تتلقى JSON بالتنسيق التالي:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

تقوم الدالة بإنشاء مستندات Azure Cosmos DB بالتنسيق التالي لكل سجل:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

إليك بيانات الربط في ملف function.json:

{
    "name": "employeeDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

يشرح قسم التكوين هذه الخصائص.

هنا رمز JavaScript:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

للعمليات المجمعة، قم بإدراج النموذج اللكائنات أولًا ثم قم بتشغيل دالة stringify. هنا رمز JavaScript:

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "id": "John Henry-123456",
            "name": "John Henry",
            "employeeId": "123456",
            "address": "A town nearby"
        },
        {
            "id": "John Doe-123457",
            "name": "John Doe",
            "employeeId": "123457",
            "address": "A town far away"
        }]);
    };

يوضح المثال التالي كيفية كتابة البيانات إلى Cosmos DB باستخدام ربط إخراج. يتم إعلان الربط في ملف تكوين الدالة (functions.json) وأخذ البيانات من رسالة قائمة انتظار والكتابة بمستند Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
}

في ملف run.ps1، العنصر الذي تم إرجاعه من الدالة يتم تعيينه إلى EmployeeDocument كائن، وهو ثابت في قاعدة البيانات.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

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

يُعرف ربط بيانات Azure في function.js حيث يُعين type إلى cosmosDB.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

للكتابة إلى قاعدة البيانات، قم بتمرير عنصر مستند إلى أسلوب set لمعلمة قاعدة البيانات.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

السمات

تستخدم كل من مكتبات C#‎ العملية قيد المعالجةوالعملية المعزولة سمات لتحديد الدالة. يستخدم البرنامج النصي C # بدلا من ذلك ملف تكوين function.json.

خاصية السمة الوصف
ConnectionStringSetting اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
CollectionName اسم المجموعة التي تتم مراقبتها.
CreateIfNotExists قيمة منطقية للإشارة إلى ما إذا كانت المجموعة قد تم إنشاؤها عند عدم وجودها أم لا. القيمة الافتراضية هي false لأنه يتم إنشاء مجموعات جديدة باستخدام معدل النقل المحجوز، والذي له آثار تكلفة. لمزيد من المعلومات، يُرجى الرجوع إلى صفحة التسعير.
PartitionKey عندما تكون CreateIfNotExists صحيحة، يحدد مسار مفتاح القسم للمجموعة التي تم إنشاؤها. قد تتضمن معلمات الربط.
*المجموعةالإنتاجية عندما تكون CreateIfNotExists صحيحة، فهي تحدد معدل نقل المجموعة التي تم إنشاؤها.
PreferredLocations (اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.
UseMultipleWriteLocations (اختياري) عند التعيين إلى جنبا إلى true جنب مع PreferredLocations، يدعم عمليات الكتابة متعددة المناطق في خدمة Azure Cosmos DB.

تعليقات توضيحية

من مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي على المعلمات @CosmosDBOutput التي تكتب إلى Azure Cosmos DB. يدعم التعليق التوضيحي الخصائص التالية:

تهيئة

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

خاصية function.json الوصف
connectionStringSetting اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collectionName اسم المجموعة التي يتم مراقبتها.
createIfNotExists قيمة منطقية للإشارة إلى ما إذا كانت المجموعة قد تم إنشاؤها عند عدم وجودها أم لا. القيمة الافتراضية هي false لأنه يتم إنشاء مجموعات جديدة باستخدام معدل النقل المحجوز، والذي له آثار تكلفة. لمزيد من المعلومات، يُرجى الرجوع إلى صفحة التسعير.
partitionKey عندما تكون createIfNotExists صحيحة، يحدد مسار مفتاح القسم للمجموعة التي تم إنشاؤها. قد تتضمن معلمات الربط.
*المجموعةالإنتاجية عندما تكون createIfNotExists صحيحة، فهي تحدد معدل نقل المجموعة التي تم إنشاؤها.
preferredLocations (اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.
useMultipleWriteLocations (اختياري) عند التعيين إلى جنبا إلى true جنب مع preferredLocations، يدعم عمليات الكتابة متعددة المناطق في خدمة Azure Cosmos DB.

راجع قسم المثال للحصول على أمثلة كاملة.

الاستخدام

بشكل افتراضي، عند الكتابة إلى معلمة الإخراج في الدالة الخاصة بك، يتم إنشاء مستند في قاعدة البيانات الخاصة بك. يحتوي هذا المستند على GUID تم إنشاؤه تلقائيًا كمعرف للمستند. يمكنك تحديد معرف الوثيقة لوثيقة الإخراج عن طريق تحديد خاصية المعرف في كائن JSON الذي تم تمريره إلى معلمة الإخراج.

ملاحظة

عند تحديد معرف مستند موجود، فإنه يُحذف بواسطة مستند الإخراج الجديد.

الاتصالات

تعد connectionStringSetting/connection الخصائص والخصائص leaseConnectionStringSetting/leaseConnection مراجع لتكوين البيئة الذي يحدد كيفية اتصال التطبيق بقاعدة بيانات Azure Cosmos. وقد تحدد:

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

سلسلة الاتصال

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

الاتصالات القائمة على الهوية

إذا كنت تستخدم الإصدار 4.x أو أعلى من الملحق، فبدلا من استخدام سلسلة اتصال مع سر، يمكنك جعل التطبيق يستخدم هوية Azure Active Directory. للقيام بذلك ، يمكنك تحديد الإعدادات ضمن بادئة شائعة يتم تعيينها إلى خاصية الاتصال في تكوين المشغل والربط.

في هذا الوضع، يتطلب الملحق الخصائص التالية:

الخاصية قالب متغير البيئة الوصف قيمة المثال
نقطة نهاية الحساب <CONNECTION_NAME_PREFIX>__accountEndpoint نقطة نهاية حساب Azure Cosmos DB URI. https://< database_account_name.documents.azure.com:443/>

قد يتم تعيين خصائص إضافية لتخصيص الاتصال. راجع الخصائص الشائعة للاتصالات المستندة إلى الهوية.

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

منح الإذن للهوية

مهما كانت الهوية المستخدمة يجب أن يكون لديك أذونات لتنفيذ الإجراءات المقصودة. ستحتاج إلى تعيين دور في Azure RBAC، باستخدام أدوار مضمنة أو مخصصة توفر هذه الأذونات.

هام

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

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

نوع الربط مثال على الأدوار المضمنة
مشغّل مساهم بيانات Cosmos DB المدمج
ربط بيانات الإدخال قارئ بيانات Cosmos DB المدمج
ربط بيانات الإخراج مساهم بيانات Cosmos DB المدمج

الاستثناءات والتعليمات البرمجية للإرجاع

Binding ‏‏المرجع
CosmosDB تعليمات الخطأ البرمجية لـCosmosDB

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