روابط إدخال جداول Azure لوظائف Azure

استخدم ربط إدخال جداول Azure لقراءة جدول في Azure Cosmos DB للجدول أو مساحة تخزين Azure Table‬.

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

هام

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

مثال

دعم Go غير متوفر حاليا لهذا الربط.

يعتمد استخدام الربط على إصدار حزمة الامتداد وصيغة C# المستخدمة في تطبيق الوظيفة الخاص بك، والتي يمكن أن تكون واحدة مما يلي:

تعمل مكتبة فئة معالجة عامل معزولة تعمل دالة C# المحولة برمجيا في عملية معزولة عن وقت التشغيل.

اختر إصدارًا لعرض أمثلة على الوضع والإصدار.

تمثل الفئة التالية MyTableData صفاً من بيانات في الجدول:

public class MyTableData : Azure.Data.Tables.ITableEntity
{
    public string Text { get; set; }

    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

تقرأ الدالة التالية، التي يتم تشغيلها بواسطة مشغل Queue Storage، مفتاح صف من قائمة الانتظار، والذي يتم استخدامه للحصول على الصف من جدول الإدخال. يربط التعبير {queueTrigger} الصف مفتاح الصف ببيانات تعريف الرسالة، وهي سلسلة الرسالة.

[Function("TableFunction")]
[TableOutput("OutputTable", Connection = "AzureWebJobsStorage")]
public static MyTableData Run(
    [QueueTrigger("table-items")] string input,
    [TableInput("MyTable", "<PartitionKey>", "{queueTrigger}")] MyTableData tableInput,
    FunctionContext context)
{
    var logger = context.GetLogger("TableFunction");

    logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");

    return new MyTableData()
    {
        PartitionKey = "queue",
        RowKey = Guid.NewGuid().ToString(),
        Text = $"Output record with rowkey {input} created at {DateTime.Now}"
    };
}

ترجع الدالة التالية المشغلة بواسطة قائمة الانتظار أول 5 كيانات كـ IEnumerable<T>، مع تعيين قيمة مفتاح القسم كرسالة قائمة الانتظار.

[Function("TestFunction")]
public static void Run([QueueTrigger("myqueue", Connection = "AzureWebJobsStorage")] string partition,
    [TableInput("inTable", "{queueTrigger}", Take = 5, Filter = "Text eq 'test'", 
    Connection = "AzureWebJobsStorage")] IEnumerable<MyTableData> tableInputs,
    FunctionContext context)
{
    var logger = context.GetLogger("TestFunction");
    logger.LogInformation(partition);
    foreach (MyTableData tableInput in tableInputs)
    {
        logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");
    }
}

يتم استخدام الخاصيتين Filter وTake للحد من عدد الكيانات التي تم إرجاعها.

يظهر المثال التالي دالة HTTP المشغلة المسؤولة عن إرجاع قائمة بكائنات الشخص الموجود في قسم محدد داخل تخزين جدول. في المثال، يُستخرج مفتاح القسم من مسار http؛ بينما يُستخرج tableName والاتصال من إعدادات الدالة.

public class Person {
    private String PartitionKey;
    private String RowKey;
    private String Name;

    public String getPartitionKey() { return this.PartitionKey; }
    public void setPartitionKey(String key) { this.PartitionKey = key; }
    public String getRowKey() { return this.RowKey; }
    public void setRowKey(String key) { this.RowKey = key; }
    public String getName() { return this.Name; }
    public void setName(String name) { this.Name = name; }
}

@FunctionName("getPersonsByPartitionKey")
public Person[] get(
        @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="persons/{partitionKey}") HttpRequestMessage<Optional<String>> request,
        @BindingName("partitionKey") String partitionKey,
        @TableInput(name="persons", partitionKey="{partitionKey}", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons,
        final ExecutionContext context) {

    context.getLogger().info("Got query for person related to persons with partition key: " + partitionKey);

    return persons;
}

يمكن أيضًا للتعليق التوضيحي TableInput أن يستخرج الروابط من نص json الخاص بالطلب، كما في المثال التالي.

@FunctionName("GetPersonsByKeysFromRequest")
public HttpResponseMessage get(
        @HttpTrigger(name = "getPerson", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="query") HttpRequestMessage<Optional<String>> request,
        @TableInput(name="persons", partitionKey="{partitionKey}", rowKey = "{rowKey}", tableName="%MyTableName%", connection="MyConnectionString") Person person,
        final ExecutionContext context) {

    if (person == null) {
        return request.createResponseBuilder(HttpStatus.NOT_FOUND)
                    .body("Person not found.")
                    .build();
    }

    return request.createResponseBuilder(HttpStatus.OK)
                    .header("Content-Type", "application/json")
                    .body(person)
                    .build();
}

يستخدم المثال التالي عامل تصفية للاستعلام عن الأشخاص الذين يحملون اسمًا معينًا في جدول Azure، وللحد من عدد المطابقات المحتملة لتصل إلى 10 نتائج.

@FunctionName("getPersonsByName")
public Person[] get(
        @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="filter/{name}") HttpRequestMessage<Optional<String>> request,
        @BindingName("name") String name,
        @TableInput(name="persons", filter="Name eq '{name}'", take = "10", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons,
        final ExecutionContext context) {

    context.getLogger().info("Got query for person related to persons with name: " + name);

    return persons;
}

يوضح المثال التالي ربط إدخال جدول يستخدم مشغل قائمة انتظار لقراءة صف جدول واحد. يحدد الربط وpartitionKey.rowKey تشير rowKeyالقيمة "{queueTrigger}" إلى أن مفتاح السجل يأتي من سلسلة رسائل الصف.

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

const tableInput = input.table({
    tableName: 'Person',
    partitionKey: 'Test',
    rowKey: '{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

interface PersonEntity {
    PartitionKey: string;
    RowKey: string;
    Name: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Node.js queue trigger function processed work item', queueItem);
    const person = <PersonEntity>context.extraInputs.get(tableInput);
    context.log('Person entity name: ' + person.Name);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [tableInput],
    handler: storageQueueTrigger1,
});

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

const tableInput = input.table({
    tableName: 'Person',
    partitionKey: 'Test',
    rowKey: '{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [tableInput],
    handler: (queueItem, context) => {
        context.log('Node.js queue trigger function processed work item', queueItem);
        const person = context.extraInputs.get(tableInput);
        context.log('Person entity name: ' + person.Name);
    },
});

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

في هذا المثال، يحدد تكوين الربط قيمة صريحة للجدول partitionKey ويستخدم تعبيرًا للتمرير إلى rowKey. تشير كلمة rowKey تعبير{queueTrigger} إلى أن مفتاح السجل يأتي من سلسلة رسائل الصف.

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

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "MyQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "PersonEntity",
      "type": "table",
      "tableName": "Person",
      "partitionKey": "Test",
      "rowKey": "{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    }
  ],
  "disabled": false
}

تعليمة برمجية لـ PowerShell في run.ps1:

param($MyQueueItem, $PersonEntity, $TriggerMetadata)
Write-Host "PowerShell queue trigger function processed work item: $MyQueueItem"
Write-Host "Person entity name: $($PersonEntity.Name)"

تستخدم الدالة التالية HTTP كي يقرأ سجل واحد في جدول باعتباره إدخال إلى دالة.

في هذا المثال، يحدد تكوين الربط قيمة صريحة للجدول partitionKey ويستخدم تعبيرًا للتمرير إلى rowKey. يشير التعبير rowKey إلى {id} أن مفتاح الصف يأتي من جزء {id} المسار في الطلب.

import json
import azure.functions as func

app = func.FunctionApp()

@app.route(route="messages/{id}")
@app.table_input(arg_name="messageJSON",
                 connection="AzureWebJobsStorage",
                 table_name="messages",
                 row_key='{id}',
                 partition_key="message")
def table_in_binding(req: func.HttpRequest, messageJSON):
    message = json.loads(messageJSON)
    return func.HttpResponse(f"Table row: {messageJSON}")

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

السمات

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

في مكتبات فئة C #، يدعم ذلكTableInputAttribute الخصائص التالية:

خاصية السمة ‏‏الوصف
اسم الجدول اسم الجدول.
مفتاح القسم اختياري. مفتاح القسم الخاص بكيان الجدول المراد قراءته.
مفتاح الصف اختياري. مفتاح السجل الخاص بكيان الجدول المراد قراءته.
أخذ اختياري. الحد الأقصى لعدد الكيانات التي يجب قراءتها في IEnumerable<T>. لا يمكن استخدامها مع RowKey.
عامل التصفية اختياري. تعبير عامل تصفية OData للكيانات للقراءة في IEnumerable<T>. لا يمكن استخدامها مع RowKey.
اتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع الاتصالات.

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

من مكتبة وقت تشغيل دوال Java، استخدم @TableInput التعليق التوضيحي على معلمات الدالة التي تأتي قيمتها من تخزين جدول. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو POJOs أو القيم االخالية Optional<T>. يدعم هذا التعليق التوضيحي العناصر التالية:

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

التكوين

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

الخاصية ‏‏الوصف
اسم الجدول اسم الجدول.
مفتاح القسم اختياري. مفتاح القسم الخاص بكيان الجدول المراد قراءته.
مفتاح الصف اختياري. مفتاح السجل الخاص بكيان الجدول المراد قراءته. لا يمكن استخدامها مع take أو filter.
الوقت المستغرق اختياري. الحد الأقصى لعدد الكيانات التي يجب إرجاعها. لا يمكن استخدامها مع rowKey.
راووق اختياري. تعبير عامل تصفية OData للكيانات للعودة من الجدول. لا يمكن استخدامها مع rowKey.
الاتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع الاتصالات.

التكوين

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

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى table. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
الاتجاه يجب تعيينه إلى in. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم اسم المتغير الذي يمثل جدول أو كيان في تعليمة برمجية للدالة.
اسم الجدول اسم الجدول.
مفتاح القسم اختياري. مفتاح القسم الخاص بكيان الجدول المراد قراءته.
مفتاح الصف اختياري. مفتاح السجل الخاص بكيان الجدول المراد قراءته. لا يمكن استخدامها مع take أو filter.
الوقت المستغرق اختياري. الحد الأقصى لعدد الكيانات التي يجب إرجاعها. لا يمكن استخدامها مع rowKey.
راووق اختياري. تعبير عامل تصفية OData للكيانات للعودة من الجدول. لا يمكن استخدامها مع rowKey.
الاتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع الاتصالات.

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

الاتصالات

يتم تعيين connection الخاصية على مفتاح في إعدادات التطبيق يعيد قيمة مستخدمة في وقت تشغيل الدوال للاتصال بحساب التخزين المستخدم من قبل الامتداد. تعتمد قيمة إعداد خاصية الاتصال على نوع الاتصال:

  • اتصال الهوية المدارة: connection الخاصية مشتركة <CONNECTION_NAME_PREFIX> بين مجموعة من الإعدادات التي تحدد معا اتصالا قائما على الهوية مع حساب التخزين. لمزيد من المعلومات، انظر تعريف الروابط الهوية.
  • Key Vault reference: connection إعداد الخاصية يعيد مرجع Azure Key Vault إلى الموقع الذي يتم فيه صيانة سلسلة الاتصال بشكل مركزي. لمزيد من المعلومات، راجع تعريف اتصالات Key Vault.
  • مرجع App Configuration: connection إعداد الخاصية يعيد مرجع تكوين Azure App يعيد سلسلة سلسلة الاتصال أو مرجع Key Vault. لمزيد من المعلومات، راجع تكوين Azure App في مقالة الاتصالات.
  • Connection string: connection إعداد الخاصية يعيد سلسلة حساب التخزين الفعلية سلسلة الاتصال. نظرا لأن سلسلة الاتصال تحتوي على مفاتيح سرية مشتركة، يجب أن تفكر في استخدام اتصال هوية مدار، عندما يكون ذلك ممكنا. لمزيد من المعلومات، راجع تعريف الروابط.

لمعرفة المزيد عن روابط الربط، راجع إدارة الاتصال في دالات Azure. للحصول على سلسلة اتصال، اتبع الخطوات الموضحة في إدارة مفاتيح الوصول إلى حسابات التخزين.

عندما تعدين connection إلى بادئة مفتاح أو مفتاح مسمى AzureWebJobsStorage أو إلى سلسلة فارغة، يستخدم امتداد الربط حساب التخزين الافتراضي للمضيف. لمزيد من المعلومات، راجع تحسين أداء التخزين.

الاستخدام

يعتمد استخدام الربط على إصدار حزمة الامتداد وصيغة C# المستخدمة في تطبيق الوظائف الخاص بك، والتي يمكن أن تكون واحدة مما يلي:

تعمل مكتبة فئة معالجة عامل معزولة تعمل دالة C# المحولة برمجيا في عملية معزولة عن وقت التشغيل.

حدد إصدارًا للاطلاع على تفاصيل الاستخدام للوضع والإصدار.

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

النوع ‏‏الوصف
نوع JSON القابل للتسلسل الذي ينفذ ITableEntity تحاول الدالات إلغاء تسلسل الكيان إلى نوع كائن CLR (POCO) قديم عادي. يجب أن ينفذ النوع ITableEntity أو أن يكون له خاصية سلسلة RowKey وخاصية سلسلة PartitionKey .
جدولEntity1 الكيان كنوع يشبه القاموس.

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

النوع ‏‏الوصف
IEnumerable<T> حيث T ينفذ ITableEntity تعداد للكيانات التي تم إرجاعها بواسطة الاستعلام. يمثل كل إدخال كيانا واحدا. يجب أن ينفذ النوع T ITableEntity
TableClient1 عميل متصل بالجدول. يوفر هذا أكبر قدر من التحكم لمعالجة الجدول ويمكن استخدامه للكتابة إليه إذا كان الاتصال لديه إذن كاف.

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

تمنحك سمةTableInput حق الوصول إلى سجل جدول يشغّل دالة.

احصل على بيانات صف الإدخال باستخدام context.extraInputs.get().

يتم تمرير بيانات إلى معلمة إدخال على النحو المحدد بواسطة name المفتاح في الملف function.json. تحديد partitionKey و rowKey يسمح بتصفية إلى سجلات معينة.

يتم تمرير بيانات جدول إلى دالة على هيئة سلسلة JSON. إلغاء تسلسل رسالة عن طريق الاتصال json.loads كما هو موضح في مثالإدخال.

للحصول على تفاصيل استخدام محددة، راجع Example.

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

  • Last updated on