مشاركة عبر

روابط إخراج Azure Tables في وظائف Azure.

  • مقالة

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

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

إشعار

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

هام

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

مثال

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

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

هام

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

تمثل الفئة التالية 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، تكتب كياناً جديدًا MyDataTable إلى جدول يسمى OutputTable.

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

يوضح المثال التالي دالة 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();
    }
}

يوضح المثال التالي ربط إخراج الجدول الذي يكتب كيانات جدول متعددة.

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

const tableOutput = output.table({
    tableName: 'Person',
    connection: 'MyStorageConnectionAppSetting',
});

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

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const rows: PersonEntity[] = [];
    for (let i = 1; i < 10; i++) {
        rows.push({
            PartitionKey: 'Test',
            RowKey: i.toString(),
            Name: `Name ${i}`,
        });
    }
    context.extraOutputs.set(tableOutput, rows);
    return { status: 201 };
}

app.http('httpTrigger1', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [tableOutput],
    handler: httpTrigger1,
});

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

const tableOutput = output.table({
    tableName: 'Person',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [tableOutput],
    handler: async (request, context) => {
        const rows = [];
        for (let i = 1; i < 10; i++) {
            rows.push({
                PartitionKey: 'Test',
                RowKey: i.toString(),
                Name: `Name ${i}`,
            });
        }
        context.extraOutputs.set(tableOutput, rows);
        return { status: 201 };
    },
});

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

تكوين الربط في 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و tableNameو partitionKeyو 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#‎.

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

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

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

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

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

التكوين

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

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

التكوين

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

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

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

الاتصالات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

هام

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

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

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

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

الاستخدام

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

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

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

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

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

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

النوع ‏‏الوصف
T[] حيث T هو أحد أنواع الكيانات الفردية صفيف يحتوي على كيانات متعددة. يمثل كل إدخال كيانا واحدا.

بالنسبة لسيناريوهات الإخراج الأخرى، قم بإنشاء TableClient واستخدامه مع أنواع أخرى من Azure.Data.Tables مباشرة. راجع تسجيل عملاء Azure للحصول على مثال لاستخدام إدخال التبعية لإنشاء نوع عميل من Azure SDK.

هناك خياران لإخراج سجل تخزين Table من دالة باستخدام التعليق التوضيحي TableStorageOutput:

الخيارات الوصف
القيمة المرجعة من خلال تطبيق التعليق التوضيحي على الدالة نفسها، تستمر القيمة المرجعة للدالة كصف تخزين الجدول.
إلزامي لتعيين صف الجدول بشكل صريح، قم بتطبيق التعليق التوضيحي على معلمة محددة من النوع OutputBinding<T>، أينما T يتضمن PartitionKey خصائص وRowKey. يمكنك مرافقة هذه الخصائص بتنفيذ ITableEntity أو توريد TableEntity.

قم بتعيين بيانات صف الإخراج عن طريق إرجاع القيمة أو باستخدام context.extraOutputs.set().

للكتابة إلى بيانات الجدول، استخدم cmdlet Push-OutputBinding، عيِّن المعلمة -Name TableBinding والمعلمة -Value مُساويتين لبيانات السجل. راجع مثال PowerShell للاطلاع على مزيدٍ من التفاصيل.

هناك خياران لإخراج سجل تخزين Table من إحدى الدوال:

الخيارات الوصف
القيمة المرجعة عينname الخاصية في function.json إلى$return. باستخدام هذا التكوين، تستمر قيمة الإرجاع الخاصة بالدالة كصف تخزين الجدول.
إلزامي قم بتمرير قيمة إلى الطريقة المحددة للمعلمة المعلنة كنوع Out. تظل القيمة التي تم تمريرها إلى set صف الجدول.

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

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

Binding المرجع
جدول رموز خطأ Table
كائن ثنائي كبير الحجم، جدول، قائمة الانتظار رموز خطأ Storage
كائن ثنائي كبير الحجم، جدول، قائمة الانتظار استكشاف الأخطاء وإصلاحها

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

اعرف المزيد حول مشغلات وروابط وظائف Azure