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

  • مقالة
  • قراءة خلال 21 دقائق

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

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

مثال

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

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

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

يوضح المثال التالي دالة C#‎تقرأ سجل جدول واحد. سيتم تشغيل الدالة، عند إرسال كل الرسائل إلى الصف.

تربط قيمة {queueTrigger} مفتاح الصف مفتاح الصف ببيانات تعريف الرسالة، وهي سلسلة الرسالة.

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

    [FunctionName("TableInput")]
    public static void TableInput(
        [QueueTrigger("table-items")] string input, 
        [Table("MyTable", "MyPartition", "{queueTrigger}")] MyPoco poco, 
        ILogger log)
    {
        log.LogInformation($"PK={poco.PartitionKey}, RK={poco.RowKey}, Text={poco.Text}");
    }
}

استخدم CloudTable معلمة أسلوب تقرأ جدول باستخدام SDK تخزين Azure. فيما يلي مثال على دالة تستعلم عن جدول سجل وظائف Azure:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.Cosmos.Table;
using System;
using System.Threading.Tasks;

namespace FunctionAppCloudTable2
{
    public class LogEntity : TableEntity
    {
        public string OriginalName { get; set; }
    }
    public static class CloudTableDemo
    {
        [FunctionName("CloudTableDemo")]
        public static async Task Run(
            [TimerTrigger("0 */1 * * * *")] TimerInfo myTimer, 
            [Table("AzureWebJobsHostLogscommon")] CloudTable cloudTable,
            ILogger log)
        {
            log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");

            TableQuery<LogEntity> rangeQuery = new TableQuery<LogEntity>().Where(
                TableQuery.CombineFilters(
                    TableQuery.GenerateFilterCondition("PartitionKey", QueryComparisons.Equal, 
                        "FD2"),
                    TableOperators.And,
                    TableQuery.GenerateFilterCondition("RowKey", QueryComparisons.GreaterThan, 
                        "t")));

            // Execute the query and loop through the results
            foreach (LogEntity entity in 
                await cloudTable.ExecuteQuerySegmentedAsync(rangeQuery, null))
            {
                log.LogInformation(
                    $"{entity.PartitionKey}\t{entity.RowKey}\t{entity.Timestamp}\t{entity.OriginalName}");
            }
        }
    }
}

لمزيد من المعلومات حول كيفية استخدام CloudTable، راجع البدء في استخدام تخزين جدول Azure.

إن كنت تحاول الربطCloudTableوتتلقى رسالة خطأ، تأكد من أن لديك مرجعًا إلى إصدار SDK للتخزين الصحيح.

يظهر المثال التالي دالة 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;
}

يوضح المثال التالي ربط إدخال جدول في ملف function.jsonورمز JavaScript الذي يستخدم الربط. تستخدم الدالة مشغل صف كي يقرأ سجل واحد في جدول.

يحدد ملفfunction.jsonملف a partitionKey و arowKey. تشير rowKeyالقيمة "{queueTrigger}" إلى أن مفتاح السجل يأتي من سلسلة رسائل الصف.

{
  "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
}

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

هنا رمز JavaScript:

module.exports = async function (context, myQueueItem) {
    context.log('Node.js queue trigger function processed work item', myQueueItem);
    context.log('Person entity name: ' + context.bindings.personEntity.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} جزء المسار في الطلب.

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

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

رمز Python في ملف __init__.py :

import json

import azure.functions as func

def main(req: func.HttpRequest, messageJSON) -> func.HttpResponse:

    message = json.loads(messageJSON)
    return func.HttpResponse(f"Table row: {messageJSON}")

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

السمات

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

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

خاصية السمة الوصف
TableName اسم الجدول.
PartitionKey ‏‏اختياري. مفتاح القسم الخاص بكيان الجدول المراد قراءته. راجع قسم الاستخدام للاطلاع على الإرشادات الخاصة بكيفية استخدام هذه الخاصية.
RowKey ‏‏اختياري. مفتاح الصف لكيان جدول واحد للقراءة. لا يمكن استخدامها مع Take أو Filter.
⁧⁩اتخاذ⁧⁩ ‏‏اختياري. الحد الأقصى لعدد الكيانات التي يجب إرجاعها. لا يمكن استخدامها مع RowKey.
عامل التصفية ‏‏اختياري. تعبير عامل تصفية OData للكيانات للعودة من الجدول. لا يمكن استخدامها مع RowKey.
الاتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بخدمة الجدول. راجع Connections.

يأخذ منشئ السمة اسم الجدول ومفتاح القسم ومفتاح الصف، كما هو موضح في المثال التالي:

[FunctionName("TableInput")]
public static void Run(
    [QueueTrigger("table-items")] string input, 
    [Table("MyTable", "Http", "{queueTrigger}")] MyPoco poco, 
    ILogger log)
{
    ...
}

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

[FunctionName("TableInput")]
public static void Run(
    [QueueTrigger("table-items")] string input, 
    [Table("MyTable", "Http", "{queueTrigger}", Connection = "StorageConnectionAppSetting")] MyPoco poco, 
    ILogger log)
{
    ...
}

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

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

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

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

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

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

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

التكوين

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

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

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

الاتصالات

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

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

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

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

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

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

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

إذا كنت تستخدم ملحق Table API، بدلا من استخدام سلسلة اتصال مع سر، يمكنك أن يكون التطبيق يستخدم هوية Azure Active Directory. ينطبق هذا فقط عند الوصول إلى الجداول في 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 RBAC، باستخدام أدوار مضمنة أو مخصصة توفر هذه الأذونات.

هام

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

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

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

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

الاستخدام

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

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

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

لإرجاع كيان معين حسب المفتاح، استخدم معلمة ربط مشتقة من TableEntity.

لتنفيذ الاستعلامات التي ترجع كيانات متعددة، اربط بعنصر CloudTable . يمكنك بعد ذلك استخدام هذا الكائن لإنشاء الاستعلامات وتنفيذها مقابل الجدول المرتبط. لاحظ أن CloudTable وواجهات برمجة التطبيقات ذات الصلة تنتمي إلى مساحة اسم Microsoft.Azure.Cosmos.Table .

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

تعيين filter و take خصائص. لا تقم بتعيين partitionKey أو rowKey. الوصول إلى كيان جدول إدخال (أو كيانات) باستخدام context.bindings.<BINDING_NAME>. تحتوي الكائنات الملغي تسلسلها على RowKey و PartitionKeyخصائص.

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

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

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

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