Azure Tables output bindings for Azure Functions

مقالة
04/19/2022
قراءة خلال 14 دقائق

استخدم ربط مخرجات جداول Azure لكتابة كيانات إلى جدول في حساب Azure Storage أو Cosmos DB.

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع النظرة العامة

ملاحظة

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

مثال

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

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

يوضح المثال التالي دالة C#‎التي تستخدم مشغل HTTP لكتابة سجل جدول واحد.

public class TableStorage
{
    public class MyPoco
    {
        public string PartitionKey { get; set; }
        public string RowKey { get; set; }
        public string Text { get; set; }
    }

    [FunctionName("TableOutput")]
    [return: Table("MyTable")]
    public static MyPoco TableOutput([HttpTrigger] dynamic input, ILogger log)
    {
        log.LogInformation($"C# http trigger function processed: {input.Text}");
        return new MyPoco { PartitionKey = "Http", RowKey = Guid.NewGuid().ToString(), Text = input.Text };
    }
}

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

public class MyTableData
{
    public string PartitionKey { get; set; }

    public string RowKey { get; set; }

    public string Text { get; set; }
}

تقوم الدالة التالية، التي يتم تشغيلها بواسطة مشغل "تخزين قائمة الانتظار"، بكتابة كيان جديد MyDataTable إلى جدول باسم OutputTable.

    [Function("TableFunction")]
    [TableOutput("OutputTable", Connection = "AzureWebJobsStorage")]
    public static MyTableData Run([QueueTrigger("table-items")] string input,
        [TableInput("MyTable", "MyPartition", "{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}"
        };
    }
}

يُوضح المثال التالي ربط إخراج الجدول في ملف function.json والتعليمة البرمجية الخاصة بالبرنامج النصي C#‎ التي تستخدم الربط. تكتب الدالة كيانات جدول متعددة.

إليك ملف function.json:

{
  "bindings": [
    {
      "name": "input",
      "type": "manualTrigger",
      "direction": "in"
    },
    {
      "tableName": "Person",
      "connection": "MyStorageConnectionAppSetting",
      "name": "tableBinding",
      "type": "table",
      "direction": "out"
    }
  ],
  "disabled": false
}

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

إليك رمز البرنامج النصي C#‎:

public static void Run(string input, ICollector<Person> tableBinding, ILogger log)
{
    for (int i = 1; i < 10; i++)
        {
            log.LogInformation($"Adding Person entity {i}");
            tableBinding.Add(
                new Person() { 
                    PartitionKey = "Test", 
                    RowKey = i.ToString(), 
                    Name = "Name" + i.ToString() }
                );
        }

}

public class Person
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string Name { get; set; }
}

يوضح المثال التالي دالة Java التي تستخدم مشغل HTTP لكتابة سجل جدول واحد.

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; }
}

public class AddPerson {

    @FunctionName("addPerson")
    public HttpResponseMessage get(
            @HttpTrigger(name = "postPerson", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION, route="persons/{partitionKey}/{rowKey}") HttpRequestMessage<Optional<Person>> request,
            @BindingName("partitionKey") String partitionKey,
            @BindingName("rowKey") String rowKey,
            @TableOutput(name="person", partitionKey="{partitionKey}", rowKey = "{rowKey}", tableName="%MyTableName%", connection="MyConnectionString") OutputBinding<Person> person,
            final ExecutionContext context) {

        Person outPerson = new Person();
        outPerson.setPartitionKey(partitionKey);
        outPerson.setRowKey(rowKey);
        outPerson.setName(request.getBody().get().getName());

        person.setValue(outPerson);

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

يوضح المثال التالي دالة Java التي تستخدم مشغل HTTP لكتابة سجلات جداول متعددة.

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; }
}

public class AddPersons {

    @FunctionName("addPersons")
    public HttpResponseMessage get(
            @HttpTrigger(name = "postPersons", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION, route="persons/") HttpRequestMessage<Optional<Person[]>> request,
            @TableOutput(name="person", tableName="%MyTableName%", connection="MyConnectionString") OutputBinding<Person[]> persons,
            final ExecutionContext context) {

        persons.setValue(request.getBody().get());

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

يوضح المثال التالي ربط إخراج جدول في ملف function.jsonودالة JavaScript تستخدم الربط. تكتب الدالة كيانات جدول متعددة.

إليك ملف function.json:

{
  "bindings": [
    {
      "name": "input",
      "type": "manualTrigger",
      "direction": "in"
    },
    {
      "tableName": "Person",
      "connection": "MyStorageConnectionAppSetting",
      "name": "tableBinding",
      "type": "table",
      "direction": "out"
    }
  ],
  "disabled": false
}

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

هنا رمز JavaScript:

module.exports = async function (context) {

    context.bindings.tableBinding = [];

    for (var i = 1; i < 10; i++) {
        context.bindings.tableBinding.push({
            PartitionKey: "Test",
            RowKey: i.toString(),
            Name: "Name " + i
        });
    }
};

يوضح المثال التالي كيفية كتابة كيانات متعددة إلى جدول من دالة.

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

{
  "bindings": [
    {
      "name": "InputData",
      "type": "manualTrigger",
      "direction": "in"
    },
    {
      "tableName": "Person",
      "connection": "MyStorageConnectionAppSetting",
      "name": "TableBinding",
      "type": "table",
      "direction": "out"
    }
  ],
  "disabled": false
}

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

param($InputData, $TriggerMetadata)

foreach ($i in 1..10) {
    Push-OutputBinding -Name TableBinding -Value @{
        PartitionKey = 'Test'
        RowKey = "$i"
        Name = "Name $i"
    }
}

يوضح المثال التالي كيفية استخدام ربط إخراج تخزين Table. تكوين الربط table في function.json عن طريق تعيين قيم إلى name، ، tableNamepartitionKeyو connection:

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "message",
      "type": "table",
      "tableName": "messages",
      "partitionKey": "message",
      "connection": "AzureWebJobsStorage",
      "direction": "out"
    },
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

الدالة التالية تنشئ UUI فريد للقيمة rowKey وتستمر في تخزين الرسالة في الجدول.

import logging
import uuid
import json

import azure.functions as func

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

    rowKey = str(uuid.uuid4())

    data = {
        "Name": "Output binding message",
        "PartitionKey": "message",
        "RowKey": rowKey
    }

    message.set(json.dumps(data))

    return func.HttpResponse(f"Message created with the rowKey: {rowKey}")

السمات

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

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

خاصية السمة	الوصف
TableName	اسم الجدول الذي تكتب إليه.
PartitionKey	مفتاح القسم الخاص بكيان الجدول المراد قراءته.
RowKey	مفتاح السجل الخاص بكيان الجدول المراد قراءته.
الاتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

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

[FunctionName("TableOutput")]
[return: Table("MyTable")]
public static MyPoco TableOutput(
    [HttpTrigger] dynamic input, 
    ILogger log)
{
    ...
}

يمكنك تعيين Connection الخاصية لتحديد اتصال بخدمة الجدول، كما هو موضح في المثال التالي:

[FunctionName("TableOutput")]
[return: Table("MyTable", Connection = "StorageConnectionAppSetting")]
public static MyPoco TableOutput(
    [HttpTrigger] dynamic input, 
    ILogger log)
{
    ...
}

بينما تأخذ السمة خاصية Connection ، يمكنك أيضا استخدام السمة StorageAccountAttribute لتحديد اتصال حساب تخزين. يمكنك القيام بذلك عندما تحتاج إلى استخدام حساب تخزين مختلف عن الوظائف الأخرى في المكتبة. تأخذ الدالة الإنشائية اسم إعداد تطبيق يحتوي على سلسلة اتصال تخزين. يمكن تطبيق السمة على مستوى المعلمة أو الأسلوب أو الفئة. يُظهر المثال التالي مستوى الفئة ومستوى الأسلوب:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

يتم تحديد حساب التخزين للاستخدام بالترتيب التالي:

خاصية المشغل أو السمة الملزمة Connection .
تم تطبيق السمة StorageAccount على نفس المعلمة مثل سمة المشغل أو الربط.
السمة StorageAccount المطبقة على الوظيفة.
السمة StorageAccount المطبقة على الفئة.
حساب التخزين الافتراضي لتطبيق الوظيفة، والذي يتم تعريفه في AzureWebJobsStorage إعداد التطبيق.

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

خاصية السمة	الوصف
TableName	اسم الجدول الذي تكتب إليه.
PartitionKey	مفتاح القسم الخاص بكيان الجدول المراد قراءته.
RowKey	مفتاح السجل الخاص بكيان الجدول المراد قراءته.
الاتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

يستخدم البرنامج النصي C# ملف function.json للتكوين بدلا من السمات.

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

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `table`. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
⁧⁩direction⁧⁩	يجب تعيينها إلى `out`. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم	اسم المتغير المُستخدَّم في التعليمة البرمجية للدالة التي تمثل الجدول أو الكيان. تعيين `$return` للإشارة إلى القيمة المرجعة للدالة.
tableName	اسم الجدول الذي تكتب إليه.
partitionKey	مفتاح القسم الخاص بكيان الجدول المراد قراءته.
rowKey	مفتاح السجل الخاص بكيان الجدول المراد قراءته.
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

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

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي TableOutput على المعلمات لكتابة القيم في جداولك. تدعم السمة العناصر التالية:

العنصر	الوصف
الاسم	اسم المتغير المُستخدَّم في التعليمة البرمجية للدالة التي تمثل الجدول أو الكيان.
dataType	يحدد كيفية تعامل وقت تشغيل الدالات مع قيمة المعلمة. لمعرفة المزيد، راجع dataType.
اسم الجدول	اسم الجدول الذي تكتب إليه.
partitionKey	مفتاح القسم الخاص بكيان الجدول المراد قراءته.
rowKey	مفتاح السجل الخاص بكيان الجدول المراد قراءته.
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

التكوين

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

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `table`. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
⁧⁩direction⁧⁩	يجب تعيينها إلى `out`. تعيَّن هذه الخاصية تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم	اسم المتغير المُستخدَّم في التعليمة البرمجية للدالة التي تمثل الجدول أو الكيان. تعيين `$return` للإشارة إلى القيمة المرجعة للدالة.
tableName	اسم الجدول الذي تكتب إليه.
partitionKey	مفتاح القسم الخاص بكيان الجدول المراد قراءته.
rowKey	مفتاح السجل الخاص بكيان الجدول المراد قراءته.
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

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

الاتصالات

connection الخاصية هي مرجع إلى تكوين البيئة الذي يحدد كيفية اتصال التطبيق بخدمة الجدول. وقد تحدد ما يلي:

اسم إعداد تطبيق يحتوي على سلسلة اتصال
اسم بادئة مشتركة لإعدادات تطبيق متعددة، تحدد معا اتصالا يستند إلى الهوية

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

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

للحصول على سلسلة اتصال للجداول في Azure Storage، اتبع الخطوات الموضحة في مفاتيح إدارة الوصول إلى حساب التخزين. للحصول على سلسلة اتصال للجداول في Cosmos DB (عند استخدام ملحق واجهة برمجة تطبيقات الجداول)، اتبع الخطوات الموضحة في الأسئلة المتداولة حول واجهة برمجة تطبيقات الجداول.

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

إذا كان اسم إعداد التطبيق يبدأ بـ "AzureWebJobs"، يمكنك تحديد باقي الاسم هنا فقط. على سبيل المثال، إذا قمت بتعيين connection "MyStorage"، يبحث وقت تشغيل الوظائف عن إعداد تطبيق يسمى "AzureWebJobsMyStorage". إذا تركت connection فارغة، سيستخدم وقت تشغيل الدوال سلسلة اتصال التخزين الافتراضية في إعدادات التطبيق التي تُسمى AzureWebJobsStorage.

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

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

إذا كنت تقوم بالإعداد connection إلى "AzureWebJobsStorage"، فراجع الاتصال بمساحة تخزين مضيفة باستخدام هوية. بالنسبة لكافة الاتصالات الأخرى، يتطلب الملحق الخصائص التالية:

الخاصية	قالب متغير البيئة	الوصف	قيمة المثال
خدمة الجدول URI	`<CONNECTION_NAME_PREFIX>__tableServiceUri`¹	مستوى البيانات URI لخدمة جدول تخزين Azure التي تتصل بها، باستخدام نظام HTTPS.	https://< storage_account_name.table.core.windows.net>

<CONNECTION_NAME_PREFIX>__serviceUri 1 يمكن استخدامها كاسم مستعار. إذا تم توفير كلا النموذجين ، tableServiceUri استخدام النموذج. serviceUri لا يمكن استخدام النموذج عند استخدام تكوين الاتصال العام عبر النقط و/أو قوائم الانتظار و/أو الجداول.

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

لا يمكن استخدام النموذج serviceUri عند استخدام تكوين الاتصال الكلي عبر النقط و/أو قوائم الانتظار و/أو الجداول في Azure Storage. يمكن لعنوان URI نفسه تعيين خدمة الجدول فقط. كبديل ، يمكنك توفير عنوان URI خصيصا لكل خدمة تحت نفس البادئة ، مما يسمح باستخدام اتصال واحد.

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

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

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

هام

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

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

نوع الربط	مثال على الأدوار المضمنة (Azure ^Storage1)
ربط بيانات الإدخال	قارئ بيانات جدول التخزين
ربط بيانات الإخراج	مساهم بيانات جدول التخزين

¹ إذا كان تطبيقك يتصل بدلا من ذلك بالجداول في قاعدة بيانات Cosmos، فهذا يعني أن استخدام هوية غير مدعوم، ويجب أن يستخدم الاتصال سلسلة اتصال.

الاستخدام

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

مكتبة الفئة أثناء العملية هي دالة C# مترجمة يتم تشغيلها في نفس العملية مثل وقت تشغيل الوظائف.

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