روابط Azure Cosmos DB لدالات Azure 1.x

• الإصدار 1
• الإصدار 2

هام

سينتهي الدعم للإصدار 1.x من وقت تشغيل Azure Functions في 14 سبتمبر 2026. نوصي بشدة بترحيل تطبيقاتك إلى الإصدار 4.x للحصول على الدعم الكامل.

توضح هذه المقالة كيفية العمل مع روابط AZURE Cosmos DB في دالات Azure. تدعم دالات Azure روابط المشغل والإدخال والإخراج لـ Azure Cosmos DB.

إشعار

هذه المقالة مخصصة لدالات Azure 1.x. للحصول على معلومات حول كيفية استخدام هذه الروابط في الدالات 2.x فالأحدث، راجع روابط Azure Cosmos DB لدالات Azure 2.x.

يُطلق على هذا الرابط في الأصل DocumentDB. في Azure Functions الإصدار 1.x، تمت إعادة تسمية المشغل فقط Azure Cosmos DB؛ يحتفظ ربط الإدخال وربط الإخراج وحزمة NuGet باسم DocumentDB.

إشعار

يتم دعم روابط Azure Cosmos DB للاستخدام مع API SQL فقط. بالنسبة لجميع واجهات برمجة تطبيقات Azure Cosmos DB الأخرى، يجب عليك الوصول إلى قاعدة البيانات من دالتك باستخدام العميل الثابت لواجهة برمجة التطبيقات الخاصة بك، بما في ذلك Azure Cosmos DB ل MongoDB وAzure Cosmos DB ل Apache Cassandra وAzure Cosmos DB ل Apache Gremlin وAzure Cosmos DB for Table.

الحزم - الدوال 1.x

يتم توفير روابط DB Cosmos Azure لدالات الإصدار 1.x في حزمة Microsoft.Azure.WebJobs.ExtensionsDocumentDB، الإصدار 1.x. التعليمات البرمجية المصدر للروابط موجودة في مستودع GitHub azure-webjobs-sdk-extensions.

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

بيئة التطوير	لإضافة دعم في Functions 1.x
التطوير المحلي: مكتبة فئات C#‎	تثبيت الحزمة
التطوير المحلي: برنامج C# النصي، JavaScript، F#‎	تلقائي
تطوير المدخل	تلقائي

المشغِّل

يستخدم مشغل Azure Cosmos DB Triggerموجز تغيير Azure Cosmos DB للاستماع إلى الإدراجات والتحديثات عبر الأقسام. نشر موجز التغيير إدراج والتحديثات، وليس الحذف.

المشغل - مثال

C#‎

يوضح المثال التالي دالة C# قيد المعالجة يتم استدعاؤها عند وجود إدراجات أو تحديثات في قاعدة البيانات والمجموعة المحددة.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;

namespace CosmosDBSamplesV1
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            TraceWriter log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.Info($"Documents modified: {documents.Count}");
                log.Info($"First document Id: {documents[0].Id}");
            }
        }
    }
}

JavaScript

يظهر المثال التالي ربط مشغل Azure Cosmos DB في ملف function.json ودالة JavaScript التي تستخدم الربط. تكتب الدالة رسائل السجل عند تعديل سجلات Azure Cosmos DB.

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

ها هي كود JavaScript:

    module.exports = async function (context, documents) {
        context.log('First document Id modified : ', documents[0].id);
    }

المشغل - السمات

C#‎

بالنسبة لمكتبات فئات C# قيد المعالجة، استخدم السمة CosmosDBTrigger .

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

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

للحصول على مثال كامل، راجع المشغل - مثال C#‎.

JavaScript

السمات غير مدعومة من JavaScript.

المشغل - التكوين

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

خاصية function.json	خاصية السمة	‏‏الوصف
النوع	غير متوفر	يجب تعيينه إلى cosmosDBTrigger.
الاتجاه	غير متوفر	يجب تعيينه إلى in. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء المشغل في مدخل Azure.
الاسم	غير متوفر	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
connectionStringSetting	ConnectionStringSetting	اسم إعداد تطبيق يحتوي على سلسلة الاتصال المستخدمة للاتصال بحساب Azure Cosmos DB الذي تتم مراقبته.
databaseName	DatabaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collectionName	CollectionName	اسم المجموعة التي يتم مراقبتها.
leaseConnectionStringSetting	LeaseConnectionStringSetting	(اختياري) اسم إعداد تطبيق يحتوي على سلسلة الاتصال بالخدمة التي تحتوي على مجموعة التأجير. عند عدم التعيين، تُستخدم القيمة connectionStringSetting. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في المدخل. يجب أن يكون لسلسلة الاتصال لمجموعة التأجير أذونات الكتابة.
leaseDatabaseName	LeaseDatabaseName	(اختياري) اسم قاعدة البيانات التي تحتوي على المجموعة المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم قيمة الإعداد databaseName. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في المدخل.
leaseCollectionName	LeaseCollectionName	(اختياري) اسم المجموعة المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم القيمة leases.
createLeaseCollectionIfNotExists	CreateLeaseCollectionIfNotExists	(اختياري) عند تعيينها إلى true، يتم إنشاء مجموعة عقود الإيجار تلقائيًّا عندما لا تكون موجودة بالفعل. القيمة الافتراضية هي false.
leasesCollectionThroughput	LeasesCollectionThroughput	(اختياري) تحدد مقدار وحدات الطلب لتعيينها عند إنشاء مجموعة عقود الإيجار. يتم استخدام هذا الإعداد فقط عند تعيين createLeaseCollectionIfNotExists إلى true. يتم تعيين هذه المعلمة تلقائيا عند إنشاء الربط باستخدام المدخل.
leaseCollectionPrefix	LeaseCollectionPrefix	(اختياري) عند تعيينها، فإنها تضيف بادئة إلى عقود الإيجار التي تم إنشاؤها في مجموعة التأجير لهذه الدالة، مما يسمح بشكل فعال لدالتي Azure منفصلتين بمشاركة نفس مجموعة التأجير باستخدام بادئات مختلفة.
feedPollDelay	FeedPollDelay	(اختياري) عند تعيينها، فإنها تحدد بالمللي ثانية، التأخير بين الاستقصاء عن قسم للتغييرات الجديدة في الموجز، بعد أن يتم استنزاف كافة التغييرات الحالية. القيمة الافتراضية هي 5000 (5 ثوان).
leaseAcquireInterval	LeaseAcquireInterval	(اختياري) عند تعيينها، فإنه يعرف، في ميلي ثانية، الفاصل الزمني لبدء مهمة لحساب إذا تم توزيع الأقسام بالتساوي بين مثيلات المضيف المعروفة. الافتراضي هو 13000 (13 ثانية).
leaseExpirationInterval	LeaseExpirationInterval	(اختياري) عند تعيينها، تعرف، بالمللي ثانية، الفترة الزمنية التي يتم أخذ التأجير من أجلها على عقد إيجار يمثل قسمًا. إذا لم يتم تجديد التأجير ضمن هذه الفترة الزمنية، فإنه يؤدي إلى انتهاء صلاحية وملكية القسم سينتقل إلى مثيل آخر. الافتراضي هو 60000 (60 ثانية).
leaseRenewInterval	LeaseRenewInterval	(اختياري) عند تعيينها، تعرف، بالمللي ثانية، فترة التجديد لكافة عقود الإيجار للأقسام الموجودة حاليا بواسطة مثيل. الافتراضي هو 17000 (17 ثانية).
checkpointFrequency	CheckpointFrequency	(اختياري) عند تعيينها، تعرف، بالمللي ثانية، الفاصل الزمني بين نقاط التفتيش التأجير. الافتراضي هو دائما بعد كل استدعاء دالة.
maxItemsPerInvocation	MaxItemsPerInvocation	(اختياري) عند تعيينه، فإنه يخصص الحد الأقصى لمقدار العناصر التي يتم تلقيها لكل استدعاء دالة.
startFromBeginning	StartFromBeginning	(اختياري) عند التعيين، فإنه يخبر المشغل لبدء قراءة التغييرات من بداية محفوظات المجموعة بدلاً من الوقت الحالي. يعمل هذا فقط في المرة الأولى لقيام المشغل ببدء تشغيل، كما في عمليات التشغيل اللاحقة، نقاط التحقق المخزنة بالفعل. وتعيين هذا إلى true عندما يكون هناك عقود إيجار تم إنشاؤها بالفعل ليس له أي تأثير.

عندما تقوم بالتطوير محليًا، أضف إعدادات التطبيق في ملف local.settings.json في المجموعة Values.

المشغل - الاستخدام

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

هام

إذا تم تكوين دوال متعددة لاستخدام مشغل Azure Cosmos DB لنفس المجموعة، يجب أن تستخدم كل دالة مجموعة تأجير مخصصة أو تحدد مختلفة LeaseCollectionPrefix لكل دالة. وإلا، سيتم تشغيل واحد فقط من الدالات. للحصول على معلومات حول البادئة، راجع قسم التكوين.

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

إدخال

يستخدم رابط إدخال Azure Cosmos DB واجهة برامج تطبيقات SQL لاسترداد مستند أو أكثر من مستندات Azure Cosmos DB ويمررها إلى معلمة الإدخال للدالة. يمكن تحديد معرّف المستند أو معلمات الاستعلام استنادًا إلى المشغل الذي يستدعي الوظيفة.

الإدخال - مثال

C#‎

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

• مشغِّل قائمة الانتظار، البحث عن معرّف من JSON
• مشغِّل HTTP، البحث عن معرّف من سلسلة الاستعلام
• مشغِّل HTTP، البحث عن معرّف من بيانات المسار
• مشغِّل HTTP، البحث عن معرّف من بيانات المسار، باستخدام SqlQuery
• مشغِّل HTTP، الحصول على مستندات متعددة، وذلك باستخدام SqlQuery
• مشغِّل HTTP، الحصول على مستندات متعددة، وذلك باستخدام DocumentClient

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

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

مشغِّل قائمة الانتظار، البحث عن معرّف من JSON

يظهر المثال التالي دالة C#‎ التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة رسالة قائمة انتظار تحتوي على كائن JSON. يقوم مشغل قائمة الانتظار بتحليل JSON في كائن مسمى ToDoItemLookup، والذي يحتوي على معرف للبحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

namespace CosmosDBSamplesV1
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }
    }
}

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}")]ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId}");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }
}

مشغِّل HTTP، البحث عن معرّف من سلسلة الاستعلام

يظهر المثال التالي دالة C#‎ التي تسترد مستنداً واحداً. يتم تشغيل الوظيفة بواسطة طلب بروتوكول نص تشعبي يستخدم سلسلة استعلام لتحديد المعرّف للبحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

مشغِّل HTTP، البحث عن معرّف من بيانات المسار

يظهر المثال التالي دالة C#‎ التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم بيانات المسار لتحديد المعرّف المطلوب البحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static HttpResponseMessage Run(
            [HttpTrigger(
                AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

تخطي أمثلة الإدخال

مشغِّل HTTP، البحث عن معرّف من بيانات المسار، باستخدام SqlQuery

يظهر المثال التالي دالة C#‎ التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم بيانات المسار لتحديد المعرّف المطلوب البحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")] IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

تخطي أمثلة الإدخال

مشغِّل HTTP، الحصول على مستندات متعددة، وذلك باستخدام SqlQuery

يظهر المثال التالي دالة C#‎ التي تسترد قائمة مستندات. تُشغَّل الدالة بواسطة طلب HTTP. يُحدد الاستعلام في خاصية السمة SqlQuery.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

تخطي أمثلة الإدخال

مشغل HTTP، الحصول على مستندات متعددة، وذلك باستخدام DocumentClient (C#)

يظهر المثال التالي دالة C#‎ التي تسترد قائمة مستندات. تُشغَّل الدالة بواسطة طلب HTTP. تستخدم التعليمة البرمجية مثيل DocumentClient وفره ربط Azure Cosmos DB لقراءة قائمة المستندات. يمكن أيضاً استخدام المثيل DocumentClient لعمليات الكتابة.

using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
            string searchterm = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
                .Value;

            if (searchterm == null)
            {
                return req.CreateResponse(HttpStatusCode.NotFound);
            }

            log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
            IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
                .Where(p => p.Description.Contains(searchterm))
                .AsDocumentQuery();

            while (query.HasMoreResults)
            {
                foreach (ToDoItem result in await query.ExecuteNextAsync())
                {
                    log.Info(result.Description);
                }
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

JavaScript

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

• مشغِّل قائمة الانتظار، البحث عن معرّف من JSON
• مشغِّل HTTP، البحث عن معرّف من سلسلة الاستعلام
• مشغِّل HTTP، البحث عن معرّف من بيانات المسار
• مشغِّل قائمة الانتظار، الحصول على مستندات متعددة، وذلك باستخدام SqlQuery

مشغِّل قائمة الانتظار، البحث عن معرّف من JSON

يظهر المثال التالي ربط إدخال Azure Cosmos DB في ملف function.json و دالة JavaScript التي تستخدم الربط. تقرأ الدالة مستنداً واحداً وتحدِّث قيمة النص الخاصة بالمستند.

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

{
    "name": "inputDocumentIn",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

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

ها هي كود JavaScript:

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

مشغِّل HTTP، البحث عن معرّف من سلسلة الاستعلام

يظهر المثال التالي دالة JavaScript التي تسترد مستنداً واحداً. يتم تشغيل الوظيفة بواسطة طلب بروتوكول نص تشعبي يستخدم سلسلة استعلام لتحديد المعرّف للبحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

إليك الملف function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}"
    }
  ],
  "disabled": true
}

ها هي كود JavaScript:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

مشغِّل HTTP، البحث عن معرّف من بيانات المسار

يظهر المثال التالي دالة JavaScript التي تسترد مستنداً واحداً. يتم تشغيل الوظيفة بواسطة طلب بروتوكول نص تشعبي يستخدم سلسلة استعلام لتحديد المعرّف للبحث عنه. يُستخدم ذلك المعرّف لاسترداد ToDoItem مستند من قاعدة البيانات والمجموعة المحددة.

إليك الملف function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}"
    }
  ],
  "disabled": false
}

ها هي كود JavaScript:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

مشغِّل قائمة الانتظار، الحصول على مستندات متعددة، وذلك باستخدام SqlQuery

يظهر المثال التالي ربط إدخال Azure Cosmos DB في ملف function.json و دالة JavaScript التي تستخدم الربط. تسترد الدالة مستندات متعددة محددة بواسطة استعلام SQL، وذلك باستخدام مشغِّل قائمة انتظار لتخصيص معلمات الاستعلام.

يوفر مشغِّل قائمة الانتظار معلمة departmentId. رسالة قائمة انتظار { "departmentId" : "Finance" } سترجع جميع السجلات للإدارة المالية.

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

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connection": "CosmosDBConnection"
}

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

ها هي كود JavaScript:

    module.exports = async function (context, input) {
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }
    };

الإدخال - السمات

C#‎

في مكتبات فئات C# قيد المعالجة، استخدم السمة DocumentDB.

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

JavaScript

السمات غير مدعومة من JavaScript.

الإدخال - التكوين

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

خاصية function.json	خاصية السمة	‏‏الوصف
النوع	غير متوفر	يجب تعيينه إلى documentdb.
الاتجاه	غير متوفر	يجب تعيينه إلى in.
الاسم	غير متوفر	اسم معلمة الربط التي تمثل المستند في الدالة.
databaseName	DatabaseName	قاعدة البيانات التي تحتوي على المستند.
collectionName	CollectionName	اسم المجموعة التي تحتوي على المستند.
معرف	معرّف	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تقم بتعيين كل من خصائص المعرف و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
sqlQuery	SqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تقم بتعيين كل من خصائص المعرف و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
الاتصال	ConnectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال Azure Cosmos DB.
partitionKey	مفتاح القسم	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط.

عندما تقوم بالتطوير محليًا، أضف إعدادات التطبيق في ملف local.settings.json في المجموعة Values.

الإدخال - الاستخدام

C#‎

عند الخروج من الدالة بنجاح، تستمر أي تغييرات أُجريت على مستند الإدخال عبر معلمات الإدخال المسماة تلقائياً.

JavaScript

لا تُجرى التحديثات تلقائيّاً عند الخروج من الدالة. بدلاً من ذلك، استخدم context.bindings.<documentName>In و context.bindings.<documentName>Out لإجراء التحديثات. راجع مثال الإدخال.

المخرجات

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

مثال - الإخراج

C#‎

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

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

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

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

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

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

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

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

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

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

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

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

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

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

JavaScript

يظهر المثال التالي رابط إخراج 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": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "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
      });
    };

الإخراج - سمات

C#‎

في مكتبات فئات C# قيد المعالجة، استخدم السمة DocumentDB.

الدالة الإنشائية للسمة تأخذ اسم قاعدة البيانات واسم المجموعة. للحصول على معلومات حول هذه الإعدادات والخصائص الأخرى التي يمكنك تكوينها، راجع الإخراج - التكوين. فيما يلي DocumentDB مثال سمة في توقيع أسلوب:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

للحصول على مثال كامل، راجع الإخراج.

JavaScript

السمات غير مدعومة من JavaScript.

الإخراج - التكوين

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

خاصية function.json	خاصية السمة	‏‏الوصف
النوع	غير متوفر	يجب تعيينه إلى documentdb.
الاتجاه	غير متوفر	يجب تعيينه إلى out.
الاسم	غير متوفر	اسم معلمة الربط التي تمثل المستند في الدالة.
databaseName	DatabaseName	قاعدة البيانات التي تحتوي على المجموعة حيث يتم إنشاء المستند.
collectionName	CollectionName	اسم المجموعة حيث تم إنشاء المستند.
createIfNotExists	CreateIfNotExists	قيمة منطقية للإشارة إلى ما إذا كانت المجموعة قد تم إنشاؤها عند عدم وجودها أم لا. القيمة الافتراضية هي false لأنه يتم إنشاء مجموعات جديدة باستخدام معدل النقل المحجوز، والذي له آثار تكلفة. لمزيد من المعلومات، راجع صفحة التسعير.
partitionKey	مفتاح القسم	عندما تكون CreateIfNotExists صحيحة، يحدد مسار مفتاح القسم للمجموعة التي تم إنشاؤها.
collectionThroughput	CollectionThroughput	عندما تكون CreateIfNotExists صحيحة، تحدد معدل نقل المجموعة التي تم إنشاؤها.
الاتصال	ConnectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال Azure Cosmos DB.

عندما تقوم بالتطوير محليًا، أضف إعدادات التطبيق في ملف local.settings.json في المجموعة Values.

الإخراج - الاستخدام

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

إشعار

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

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

Binding	المرجع
Azure Cosmos DB	رموز حالة HTTP لـ Azure Cosmos DB

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

• تعرف على المزيد حول حوسبة قاعدة البيانات بلا خادم باستخدام Azure Cosmos DB
• تعرف على المزيد حول مشغلات وروابط Azure Functions