ربط إدخال Azure Cosmos DB لدوال Azure 2.x والإصدارات الأحدث

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

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

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

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

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

ملاحظة

عند تقسيم المجموعة، يجب أن تحدد عمليات البحث أيضا قيمة مفتاح القسم.

مثال

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

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

• مكتبة الفئة أثناء العملية: الدالة C# المترجمة التي يتم تشغيلها في نفس العملية مثل وقت تشغيل الوظائف.
• مكتبة فئة العملية المعزولة: الدالة C # المترجمة التي يتم تشغيلها في عملية معزولة عن وقت التشغيل. مطلوب عملية معزولة لدعم وظائف C # التي تعمل على .NET 5.0.
• البرنامج النصي C#: يستخدم بشكل أساسي عند إنشاء وظائف C# في مدخل Azure.

قيد التنفيذ

يحتوي هذا القسم على الأمثلة التالية لاستخدام دالات مكتبة الفئة C# أثناء العملية مع الإصدار الإضافي 3.x:

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

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

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        [JsonProperty("id")]
        public string Id { get; set; }

        [JsonProperty("partitionKey")]
        public string PartitionKey { get; set; }

        public string Description { get; set; }
    }
}

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

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

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

        public string ToDoItemPartitionKeyValue { get; set; }
    }
}

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

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}",
                PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

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

ملاحظة

معلمة سلسلة استعلام HTTP حساسة لحالة الأحرف.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}",
                PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}",
                PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

يوضح المثال كيفية استخدام تعبير ربط في المعلمة SqlQuery. يمكنك تمرير بيانات المسار إلى المعلمة SqlQuery كما هو موضح، ولكن لا يمكنك حالياً تمرير قيم سلسلة الاستعلام.

ملاحظة

إذا كنت بحاجة إلى الاستعلام عن طريق المعرّف فقط، فمن المستحسن استخدام البحث، مثل الأمثلة السابقة، لأنه سيستهلك وحدات طلبأقل. عمليات قراءة النقطة (GET) أكثر فعاليةً من الاستعلامات حسب المعرّف.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequest req,
            [CosmosDB("ToDoItems", "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

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

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

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

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

ملاحظة

يمكنك أيضاً استخدام واجهة IDocumentClient لتسهيل الاختبار.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
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 Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"];
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");

            log.LogInformation($"Searching for: {searchterm}");

            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.LogInformation(result.Description);
                }
            }
            return new OkResult();
        }
    }
}

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

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

using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingCosmosClient
    {  
        [FunctionName("DocsByUsingCosmosClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")] CosmosClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"].ToString();
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Container container = client.GetDatabase("ToDoItems").GetContainer("Items");

            log.LogInformation($"Searching for: {searchterm}");

            QueryDefinition queryDefinition = new QueryDefinition(
                "SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
                .WithParameter("@searchterm", searchterm);
            using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
            {
                while (resultSet.HasMoreResults)
                {
                    FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
                    ToDoItem item = response.First();
                    log.LogInformation(item.Description);
                }
            }

            return new OkResult();
        }
    }
}

عملية معزولة

مثال معلق.

برنامج نصي C#‎

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

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

تشير أمثلة مشغِّل HTTP إلى نوع ToDoItem بسيط:

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

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

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

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

{
    "name": "inputDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "partitionKey": "{partition key value}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
}

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

إليك التعليمة البرمجية لبرنامج C# النصي:

    using System;

    // Change input document contents using Azure Cosmos DB input binding
    public static void Run(string myQueueItem, dynamic inputDocument)
    {
      inputDocument.text = "This has changed.";
    }

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

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

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

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

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

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

إليك التعليمة البرمجية لبرنامج C# النصي:

    public static void Run(QueuePayload myQueueItem, IEnumerable<dynamic> documents)
    {
        foreach (var doc in documents)
        {
            // operate on each document
        }
    }

    public class QueuePayload
    {
        public string departmentId { get; set; }
    }

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

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

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

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

إليك التعليمة البرمجية لبرنامج C# النصي:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

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

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

إليك التعليمة البرمجية لبرنامج C# النصي:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

إليك ملف function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "sqlQuery": "SELECT top 2 * FROM c order by c._ts desc"
    }
  ],
  "disabled": false
}

إليك التعليمة البرمجية لبرنامج C# النصي:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, IEnumerable<ToDoItem> toDoItems, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    foreach (ToDoItem toDoItem in toDoItems)
    {
        log.LogInformation(toDoItem.Description);
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

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

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

إليك ملف function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "client",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "inout"
    }
  ],
  "disabled": false
}

إليك التعليمة البرمجية لبرنامج C# النصي:

#r "Microsoft.Azure.Documents.Client"

using System.Net;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Extensions.Logging;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, DocumentClient client, ILogger log)
{
    log.LogInformation("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.LogInformation($"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.LogInformation(result.Description);
        }
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

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

• مشغِّل HTTP، البحث عن المعرّف من سلسلة الاستعلام - معلمة السلسة
• مشغِّل HTTP، البحث عن المعرّف من سلسلة الاستعلام - معلمة POJO
• مشغِّل HTTP، البحث عن معرّف من بيانات المسار
• مشغِّل HTTP، البحث عن معرّف من بيانات المسار، باستخدام SqlQuery
• مشغِّل HTTP، الحصول على مستندات متعددة من بيانات المسار، باستخدام SqlQuery

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

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

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

يوضح المثال التالي دالة Java التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم سلسلة استعلام لتحديد قيمة المعرّف ومفتاح القسم المطلوب البحث عنهما. تُستخدم قيمة المعرّف ومفتاح القسم لاسترداد مستند من قاعدة البيانات والمجموعة المحددة في شكل سلسلة.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

من مكتبة وقت تشغيل دوال Java، استخدم التعليق التوضيحي @CosmosDBInput على معلمات الدالة التي تأتي قيمتها من Cosmos DB. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو عناصر POJO أو القيم بدون قيمة باستخدام Optional<T>.

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

يوضح المثال التالي دالة Java التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم سلسلة استعلام لتحديد قيمة المعرّف ومفتاح القسم المطلوب البحث عنهما. تُستخدم قيمة المعرّف ومفتاح القسم لاسترداد مستند من المستندات من قاعدة البيانات والمجموعة المحددة. ثم يُحوَّل المستند إلى مثيل ToDoItem POJO الذي أُنشئ مسبقاً، ويُمرر باعتباره وسيطة إلى الدالة.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

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

يوضح المثال التالي دالة Java التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم معلمة مسار لتحديد قيمة المعرّف ومفتاح القسم المطلوب البحث عنهما. تُستخدم قيمة المعرّف ومفتاح القسم لاسترداد مستند من قاعدة البيانات والمجموعة المحددة، وإعادتها في شكل Optional<String>.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

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

يوضح المثال التالي دالة Java التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP الذي يستخدم معلمة مسار لتحديد المعرّف المطلوب البحث عنه. يُستخدم ذلك المعرّف لاسترداد مستند من قاعدة البيانات والمجموعة المحددة بحيث تُحوَّل مجموعة النتائج إلى ToDoItem[]، حيث يمكن إرجاع العديد من المستندات اعتماداً على معايير الاستعلام.

ملاحظة

إذا كنت بحاجة إلى الاستعلام عن طريق المعرّف فقط، فمن المستحسن استخدام البحث، مثل الأمثلة السابقة، لأنه سيستهلك وحدات طلبأقل. عمليات قراءة النقطة (GET) أكثر فعاليةً من الاستعلامات حسب المعرّف.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

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

يوضح المثال التالي دالة Java التي تسترد وثائق متعددةً. تُشغَّل الدالة بواسطة طلب HTTP الذي يستخدم معلمة مسار desc لتحديد السلسلة المطلوب البحث عنها في الحقل description. يُستخدم مصطلح البحث لاسترداد مجموعة من المستندات من قاعدة البيانات والمجموعة المحددة، وتحويل مجموعة النتائج إلى ToDoItem[] وتمريرها باعتبارها وسيطة إلى الدالة.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

يحتوي هذا القسم على الأمثلة التالية التي تقرأ مستنداً واحداً عن طريق تحديد قيمة معرّف من مصادر مختلفة:

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

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

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

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

{
    "name": "inputDocumentIn",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "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 التي تسترد مستنداً واحداً. تُشغَّل الدالة بواسطة طلب HTTP يستخدم سلسلة استعلام لتحديد قيمة المعرّف ومفتاح القسم المطلوب البحث عنهما. تُستخدم قيمة المعرّف ومفتاح القسم لاسترداد مستند ToDoItem من قاعدة البيانات والمجموعة المحددة.

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

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "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);
    }
};

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

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

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

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "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": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "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
  }
};

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

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

يوضح المثال التالي كيفية قراءة وتحديث مستند COSMOS DB واحد. يُوفَّر المعرّف الفريد للمستند من خلال قيمة JSON في رسالة قائمة الانتظار.

يُدرج ربط إدخال Cosmos DB أولاً في قائمة عمليات الروابط الموجودة في ملف تكوين الدالة (function.json).

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

يحتوي ملف run.ps1 على التعليمة البرمجية PowerShell التي تقرأ المستند الوارد والتغييرات في عمليات الإخراج.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document  

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

يوضح المثال التالي كيفية قراءة وتحديث مستند Cosmos DB واحد من واجهة برمجة تطبيقات الويب. يُوفَّر المعرّف الفريد للمستند من خلال معلمة سلسلة استعلام من طلب HTTP، كما هو محدد في خاصية "Id": "{Query.Id}" الربط.

يُدرج ربط إدخال Cosmos DB أولاً في قائمة عمليات الروابط الموجودة في ملف تكوين الدالة (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
} 

يحتوي ملف run.ps1 على التعليمة البرمجية PowerShell التي تقرأ المستند الوارد والتغييرات في عمليات الإخراج.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

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

يوضح المثال التالي كيفية قراءة وتحديث مستند Cosmos DB واحد من واجهة برمجة تطبيقات الويب. يُوفَّر المعرّف الفريد الخاص بالمستند من خلال معلمة مسار. تُعرَّف معلمة التوجيه في خاصية route ربط طلب HTTP والمُشار إليها في خاصية ربط "Id": "{Id}" Cosmos DB.

يُدرج ربط إدخال Cosmos DB أولاً في قائمة عمليات الروابط الموجودة في ملف تكوين الدالة (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
} 

يحتوي ملف run.ps1 على التعليمة البرمجية PowerShell التي تقرأ المستند الوارد والتغييرات في عمليات الإخراج.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
} 

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

يوضح المثال التالي كيفية قراءة مستندات Cosmos DB متعددة. يعرف ملف تكوين الدالة (function.json) خصائص الربط، والتي تتضمن sqlQuery. تحدد عبارة SQL المُزوَّدة إلى الخاصية sqlQuery مجموعة المستندات المُزوَّدة إلى الدالة.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
} 

يحتوي ملف run1.ps على التعليمة البرمجية PowerShell التي تقرأ المستند الوارد.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
} 

يحتوي هذا القسم على الأمثلة التالية التي تقرأ مستنداً واحداً عن طريق تحديد قيمة معرّف من مصادر مختلفة:

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

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

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

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

{
    "name": "documents",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "$return",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

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

فيما يلي التعليمة البرمجية لـ Python:

import azure.functions as func

def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Document:
    if documents:
        document = documents[0]
        document['text'] = 'This was updated!'
        return document

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

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

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

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "scriptFile": "__init__.py"
}

فيما يلي التعليمة البرمجية لـ Python:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])

    return 'OK'

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

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

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

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

فيما يلي التعليمة البرمجية لـ Python:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])
    return 'OK'

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

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

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

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

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

السمات

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

الوظائف 2.x+

خاصية السمة	الوصف
ConnectionStringSetting	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
CollectionName	اسم المجموعة التي تتم مراقبتها.
PartitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. وهو مطلوب للبحث في مجموعات مُقسَّمة.
المعرّف	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
SqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
PreferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، "شرق الولايات المتحدة، جنوب وسط الولايات المتحدة، شمال أوروبا".

الملحق 4.x+ (معاينة)

خاصية السمة	الوصف
الاتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بحساب قاعدة بيانات Azure Cosmos الذي يتم الاستعلام عنه. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName	اسم قاعدة بيانات Azure Cosmos DB مع مراقبة الحاوية.
containerName	اسم الحاوية التي تتم مراقبتها.
PartitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. مطلوب لعمليات البحث في حاويات مقسمة .
المعرّف	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
SqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
PreferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

الوظائف 2.x+

خاصية السمة	الوصف
ConnectionStringSetting	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
CollectionName	اسم المجموعة التي تتم مراقبتها.
PartitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. وهو مطلوب للبحث في مجموعات مُقسَّمة.
المعرّف	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
SqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
PreferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، "شرق الولايات المتحدة، جنوب وسط الولايات المتحدة، شمال أوروبا".

الملحق 4.x+ (معاينة)

خاصية السمة	الوصف
الاتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بحساب قاعدة بيانات Azure Cosmos الذي يتم الاستعلام عنه. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName	اسم قاعدة بيانات Azure Cosmos DB مع مراقبة الحاوية.
containerName	اسم الحاوية التي تتم مراقبتها.
PartitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. مطلوب لعمليات البحث في حاويات مقسمة .
المعرّف	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
SqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص Id و SqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
PreferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

الوظائف 2.x+

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
connectionStringSetting	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collectionName	اسم المجموعة التي يتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. وهو مطلوب للبحث في مجموعات مُقسَّمة.
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

الملحق 4.x+ (معاينة)

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
اتصال	اسم إعداد التطبيق أو حاوية الإعداد التي تحدد كيفية الاتصال بحساب قاعدة بيانات Azure Cosmos الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع مراقبة الحاوية.
containerName	اسم الحاوية التي تتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. مطلوب لعمليات البحث في حاويات مقسمة .
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

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

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

• الاسم
• connectionStringSetting
• databaseName
• collectionName
• dataType
• ⁧⁩المُعرف⁧⁩
• partitionKey
• sqlQuery

تهيئة

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

الوظائف 2.x+

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
connectionStringSetting	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collectionName	اسم المجموعة التي يتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. وهو مطلوب للبحث في مجموعات مُقسَّمة.
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

الملحق 4.x+ (معاينة)

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
اتصال	اسم إعداد التطبيق أو حاوية الإعداد التي تحدد كيفية الاتصال بحساب قاعدة بيانات Azure Cosmos الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع مراقبة الحاوية.
containerName	اسم الحاوية التي تتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. مطلوب لعمليات البحث في حاويات مقسمة .
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

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

الاستخدام

يعتمد نوع المعلمة الذي يدعمه مشغل Event Grid على إصدار وقت تشغيل الدالات وإصدار حزمة الملحقات وطريقة C # المستخدمة.

الوظائف 2.x+

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

الملحق 4.x+ (معاينة)

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

الوظائف 2.x+

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

الملحق 4.x+ (معاينة)

يتم حاليا دعم مدخلات سلسلة JSON فقط.

الوظائف 2.x+

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
connectionStringSetting	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collectionName	اسم المجموعة التي يتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. وهو مطلوب للبحث في مجموعات مُقسَّمة.
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تُعيِّن أياً منهما، تُسترد المجموعة بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

الملحق 4.x+ (معاينة)

خاصية function.json	الوصف
النوع	يجب تعيينها إلى cosmosDBTrigger.
⁧⁩direction⁧⁩	يجب تعيينها إلى in.
الاسم	اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
اتصال	اسم إعداد التطبيق أو حاوية الإعداد التي تحدد كيفية الاتصال بحساب قاعدة بيانات Azure Cosmos الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName	اسم قاعدة بيانات Azure Cosmos DB مع مراقبة الحاوية.
containerName	اسم الحاوية التي تتم مراقبتها.
partitionKey	تحديد قيمة مفتاح القسم المطلوب للبحث. قد تتضمن معلمات الربط. مطلوب لعمليات البحث في حاويات مقسمة .
⁧⁩المُعرف⁧⁩	معرّف المستند المطلوب استرداده. تدعم هذه الخاصية تعبيرات الربط. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
sqlQuery	استعلام Azure Cosmos DB SQL المستخدم لاسترداد مستندات متعددة. تدعم الخاصية روابط وقت التشغيل، كما هو الحال في هذا المثال: SELECT * FROM c where c.departmentId = {departmentId}. لا تُعيِّن كلاً من خصائص id و sqlQuery. إذا لم تقم بتعيين أي منهما، استرداد الحاوية بأكملها.
preferredLocations	(اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافيا في خدمة Azure Cosmos DB. يجب فصل القيم بفواصل. على سبيل المثال، ⁧East US,South Central US,North Europe⁩.

من مكتبة وقت تشغيل وظائف Java ، يعرض التعليق التوضيحي @CosmosDBInput بيانات قاعدة بيانات Cosmos إلى الدالة. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو POJOs أو القيم االخالية Optional<T>.

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

لا تُجرى التحديثات على المستندات تلقائيّاً عند الخروج من الدالة. لتحديث المستندات في إحدى الدوال، استخدم ربط إخراج. راجع مثال PowerShell للاطلاع على مزيدٍ من التفاصيل.

تصبح البيانات متاحة للدالة عبر معلمة DocumentList. لا تستمر أي تغييرات أُجريت على المستند تلقائياً.

الاتصالات

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

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

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

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

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

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

إذا كنت تستخدم الإصدار 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 المدمج

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

• تشغيل دالة عند إنشاء مستند Azure Cosmos DB أو تعديله (المشغِّل)
• حفظ التغييرات على مستند Azure Cosmos DB (ربط الإخراج)