Share via

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

  • مقالة

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

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

إشعار

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

هام

تستخدم هذه المقالة علامات التبويب لدعم إصدارات متعددة من نموذج البرمجة Node.js. يتوفر نموذج v4 بشكل عام وتم تصميمه للحصول على تجربة أكثر مرونة وبديهية لمطوري JavaScript وTypeScript. لمزيد من التفاصيل حول كيفية عمل نموذج v4، راجع دليل مطور Azure Functions Node.js. لمعرفة المزيد حول الاختلافات بين v3 وv4، راجع دليل الترحيل.

تدعم Azure Functions نموذجي برمجة ل Python. تعتمد الطريقة التي تحدد بها روابطك على نموذج البرمجة الذي اخترته.

يتيح لك نموذج برمجة Python v2 تحديد الروابط باستخدام المحسنات مباشرة في التعليمات البرمجية لدالة Python. لمزيد من المعلومات، راجع دليل مطور Python.

تدعم هذه المقالة كلا نموذجي البرمجة.

مثال

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

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

  • نموذج العامل المعزول: دالة C# المترجمة التي يتم تشغيلها في عملية عامل معزولة عن وقت التشغيل. عملية العامل المعزولة مطلوبة لدعم وظائف C# التي تعمل على إصدارات LTS وغير LTS .NET و.NET Framework. تستخدم Microsoft.Azure.Functions.Worker.Extensions.* ملحقات دالات عملية العامل المعزولة مساحات الأسماء.
  • نموذج قيد المعالجة: دالة C# المحولة برمجيا التي تعمل في نفس العملية مثل وقت تشغيل الوظائف. في تباين هذا النموذج، يمكن تشغيل الدالات باستخدام البرمجة النصية C#، والتي يتم دعمها بشكل أساسي لتحرير مدخل C#. تستخدم Microsoft.Azure.WebJobs.Extensions.* ملحقات الوظائف قيد المعالجة مساحات الأسماء.

هام

سينتهي الدعم للنموذج قيد التنفيذ في 10 نوفمبر 2026. نوصي بشدة بترحيل تطبيقاتك إلى نموذج العامل المعزول للحصول على الدعم الكامل.

يحتوي هذا القسم على أمثلة تتطلب الإصدار 3.x من ملحق Azure Cosmos DB و5.x من ملحق Azure Storage. إذا لم يكن موجودًا بالفعل في تطبيق الوظائف، أضف مرجعا إلى حزم NuGet التالية:

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

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

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

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

تشير الأمثلة إلى نوع 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 على معلمات الدالة التي تأتي قيمتها من Azure Cosmos DB. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو POJOs أو القيم االخالية 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

يظهر المثال التالي دالة TypeScript تقرأ مستندا واحدا وتحدث القيمة النصية للمستند.

import { app, input, InvocationContext, output } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

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

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

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

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

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

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

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

يظهر المثال التالي دالة TypeScript التي تسترد مستندات متعددة محددة بواسطة استعلام SQL، باستخدام مشغل قائمة انتظار لتخصيص معلمات الاستعلام.

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

import { app, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

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

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

يوضح المثال التالي دالة JavaScript التي تقرأ مستندا واحدا وتحدث القيمة النصية للمستند.

const { app, input, output } = require('@azure/functions');

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

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

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

const { app, input } = require('@azure/functions');

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

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

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

const { app, input } = require('@azure/functions');

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

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

يظهر المثال التالي دالة JavaScript التي تسترد مستندات متعددة محددة بواسطة استعلام SQL، باستخدام مشغل قائمة انتظار لتخصيص معلمات الاستعلام.

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

const { app, input } = require('@azure/functions');

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

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

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

يتم إدراج ربط إدخال Azure 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، البحث عن معرّف من سلسلة الاستعلام

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

يتم إدراج ربط إدخال Azure 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، البحث عن معرّف من بيانات المسار

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

يتم إدراج ربط إدخال Azure 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

يوضح المثال التالي كيفية قراءة مستندات Azure 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.ps1 على رمز PowerShell الذي يقرأ المستندات الواردة.

param($QueueItem, $Documents, $TriggerMetadata)

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

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

تعتمد الأمثلة على ما إذا كنت تستخدم نموذج برمجة v1 أو v2 Python.

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

يوضح المثال التالي ربط إدخال Azure Cosmos DB. تقرأ الدالة مستنداً واحداً وتحدِّث قيمة النص الخاصة بالمستند.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

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

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

لا يوجد نموذج مكافئ للإصدار 2 في هذا الوقت.

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

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

لا يوجد نموذج مكافئ للإصدار 2 في هذا الوقت.

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

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

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

لا يوجد نموذج مكافئ للإصدار 2 في هذا الوقت.

السمات

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

خاصية السمة ‏‏الوصف
Connection اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB المطلوب. لمزيد من المعلومات، راجع الاتصالات.
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

الديكور

ينطبق فقط على نموذج برمجة Python v2.

بالنسبة لوظائف Python v2 المعرفة باستخدام مصمم الديكور، الخصائص التالية على cosmos_db_input:

الخاصية ‏‏الوصف
arg_name اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
database_name اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collection_name اسم مجموعة Azure Cosmos DB التي تتم مراقبتها.
connection_string_setting تتم مراقبة سلسلة الاتصال Azure Cosmos DB.
partition_key يتم مراقبة مفتاح القسم ل Azure Cosmos DB.
id معرّف المستند المطلوب استرداده.

للحصول على وظائف Python المعرفة باستخدام function.json، راجع قسم التكوين.

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

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

التكوين

ينطبق فقط على نموذج برمجة Python v1.

يوضح الجدول التالي الخصائص التي يمكنك تعيينها على الكائن الذي options تم تمريره input.cosmosDB() إلى الأسلوب . typedirectionلا تنطبق الخصائص و و name على نموذج v4.

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

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى cosmosDB.
الاتجاه يجب تعيينه إلى in.
الاسم اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
الاتصال اسم إعداد تطبيق أو حاوية إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
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

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

الاستخدام

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

يعتمد نوع المعلمة التي يدعمها ربط إدخال Cosmos DB على إصدار وقت تشغيل الوظائف وإصدار حزمة الملحق ونمط C# المستخدم.

عندما تريد أن تعالج الدالة مستندا واحدا، يمكن ربط إدخال Cosmos DB بالأنواع التالية:

النوع ‏‏الوصف
‏‏أنواع قابلة للتسلسل إلى JSON تحاول الدالات إلغاء تسلسل بيانات JSON للمستند إلى نوع كائن CLR (POCO) قديم عادي.

عندما تريد أن تعالج الدالة مستندات متعددة من استعلام، يمكن ربط ربط إدخال Cosmos DB بالأنواع التالية:

النوع ‏‏الوصف
IEnumerable<T>حيث T هو نوع JSON قابل للتسلسل تعداد للكيانات التي تم إرجاعها بواسطة الاستعلام. يمثل كل إدخال مستندا واحدا.
CosmosClient1 عميل متصل بحساب Cosmos DB.
قاعدة البيانات1 عميل متصل بقاعدة بيانات Cosmos DB.
الحاوية1 عميل متصل بحاوية Cosmos DB.

1 لاستخدام هذه الأنواع، تحتاج إلى الرجوع إلى Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 أو أحدث والتبعيات الشائعة لروابط نوع SDK.

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

الوصول إلى المستند باستخدام context.extraInputs.get().

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

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

الاتصالات

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

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

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

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

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

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

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

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

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

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

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

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

هام

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

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

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

1 لا يمكن استخدام هذه الأدوار في تعيين دور Azure RBAC. راجع وثائق نظام التحكم في الوصول استنادا إلى الدور المضمن في Cosmos DB للحصول على تفاصيل حول كيفية تعيين هذه الأدوار.

2 عند استخدام الهوية، يتعامل Cosmos DB مع إنشاء الحاوية على أنها عملية إدارة. لا يتوفر كلعملية مستوى بيانات للمشغل. ستحتاج إلى التأكد من إنشاء الحاويات التي يحتاجها المشغل (بما في ذلك حاوية التأجير) قبل إعداد وظيفتك.

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