مشغّل Azure Event Grid من أجل Azure Functions

مقالة
04/21/2022
قراءة خلال 7 دقائق

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

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

ملاحظة

لا يتم دعم مشغلات شبكة الأحداث بشكل أصلي في بيئة خدمة تطبيق موازن التحميل الداخلي (ASE). يستخدم المشغل طلب HTTP الذي لا يمكنه الوصول إلى تطبيق الدالة بدون بوابة إلى الشبكة الظاهرية.

مثال

للحصول على مثال لمشغل HTTP، راجع تلقي الأحداث إلى نقطة نهاية HTTP.

يعتمد نوع معلمة الإدخال المستخدمة مع مشغل شبكة الأحداث على هذه العوامل الثلاثة:

إصدار وقت تشغيل الوظائف
إصدار ملحق ملزم
طريقة الدالة C #.

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

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

يوضح المثال التالي دالة Functions version 3.x التي تستخدم CloudEvent معلمة ربط:

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(
            ILogger logger,
            [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

يوضح المثال التالي دالة Functions version 3.x التي تستخدم EventGridEvent معلمة ربط:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerDemo
    {
        [FunctionName("EventGridTriggerDemo")]
        public static void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
        }
    }
}

يوضح المثال التالي دالة تستخدم JObject معلمة ربط:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerCSharp
    {
        [FunctionName("EventGridTriggerCSharp")]
        public static void Run([EventGridTrigger] JObject eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.ToString(Formatting.Indented));
        }
    }
}

عند تشغيل الدالة C# في عملية معزولة، تحتاج إلى تحديد نوع مخصص لخصائص الحدث. يعرف MyEventType المثال التالي فئة.

    public class MyEventType
    {
        public string Id { get; set; }

        public string Topic { get; set; }

        public string Subject { get; set; }

        public string EventType { get; set; }

        public DateTime EventTime { get; set; }

        public IDictionary<string, object> Data { get; set; }
    }
}

يوضح المثال التالي كيفية استخدام النوع المخصص في كل من المشغل وربط مخرجات شبكة الأحداث:

public static class EventGridFunction
{
    [Function("EventGridFunction")]
    [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
    public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
    {
        var logger = context.GetLogger("EventGridFunction");

        logger.LogInformation(input.Data.ToString());

        var outputEvent = new MyEventType()
        {
            Id = "unique-id",
            Subject = "abc-subject",
            Data = new Dictionary<string, object>
            {
                { "myKey", "myValue" }
            }
        };

        return outputEvent;
    }
}

يوضح المثال التالي مشغل شبكة الأحداث المحدد في الملف function.json.

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

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ],
  "disabled": false
}

فيما يلي مثال على دالة برنامج نصي C # تستخدم EventGridEvent معلمة ربط:

#r "Microsoft.Azure.EventGrid"
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Extensions.Logging;

public static void Run(EventGridEvent eventGridEvent, ILogger log)
{
    log.LogInformation(eventGridEvent.Data.ToString());
}

لمزيدٍ من المعلومات، راجع الحزم والسمات، والتكوين، والاستخدام.

فيما يلي مثال على دالة برنامج نصي C # تستخدم JObject معلمة ربط:

#r "Newtonsoft.Json"

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public static void Run(JObject eventGridEvent, TraceWriter log)
{
    log.Info(eventGridEvent.ToString(Formatting.Indented));
}

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

مشغل Event Grid، ومعلمة سلسلة
مشغل Event Grid، ومعلمة POJO

توضح الأمثلة التالية ربط المشغل في Java الذي يستخدم الربط ويولد حدثا ، أولا يتلقى الحدث باسم String POJO وثانيا كPOJO.

مشغل Event Grid، ومعلمة سلسلة

  @FunctionName("eventGridMonitorString")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    String content,
    final ExecutionContext context) {
      context.getLogger().info("Event content: " + content);
  }

مشغل Event Grid، ومعلمة POJO

يستخدم هذا المثال POJO التالي، ويمثل خصائص المستوى الأعلى لحدث Event Grid:

import java.util.Date;
import java.util.Map;

public class EventSchema {

  public String topic;
  public String subject;
  public String eventType;
  public Date eventTime;
  public String id;
  public String dataVersion;
  public String metadataVersion;
  public Map<String, Object> data;

}

عند الوصول، يتم إلغاء تسلسل بيانات JSON الأساسية للحدث إلى EventSchema POJO لاستخدامها من قِبل الدالة. تسمح هذه العملية للدالة بالوصول إلى خصائص الحدث بطريقة موجهة للعنصر.

  @FunctionName("eventGridMonitor")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    EventSchema event,
    final ExecutionContext context) {
      context.getLogger().info("Event content: ");
      context.getLogger().info("Subject: " + event.subject);
      context.getLogger().info("Time: " + event.eventTime); // automatically converted to Date by the runtime
      context.getLogger().info("Id: " + event.id);
      context.getLogger().info("Data: " + event.data);
  }

من مكتبة وقت تشغيل دوال Java، استخدم تعليق EventGridTrigger التوضيحي على معلمات الدالة التي تأتي قيمتها من EventGrid. تؤدي المعلمات مع هذه التعليقات التوضيحية إلى تشغيل الدالة عند وصول حدث. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو عناصر POJO أو القيم الفارغة باستخدام Optional<T>.

يُظهر المثال التالي ربط مشغل في ملف function.json وملف دالة JavaScript التي تستخدم الربط.

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

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ],
  "disabled": false
}

هنا تعليمة برمجية JavaScript:

module.exports = async function (context, eventGridEvent) {
    context.log("JavaScript Event Grid function processed a request.");
    context.log("Subject: " + eventGridEvent.subject);
    context.log("Time: " + eventGridEvent.eventTime);
    context.log("Data: " + JSON.stringify(eventGridEvent.data));
};

يوضح المثال التالي كيفية تكوين ربط مشغل Event Grid في ملف function.json.

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ]
}

يتم توفير حدث Event Grid للدالة عبر معلمة اسمها eventGridEvent كما هو موضح في مثال PowerShell التالي.

param($eventGridEvent, $TriggerMetadata)

# Make sure to pass hashtables to Out-String so they're logged correctly
$eventGridEvent | Out-String | Write-Host

يظهر المثال التالي ربط مشغل في ملف function.js ودالة Python التي تستخدم الربط.

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

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "event",
      "direction": "in"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

إليك التعليمة البرمجية لـ Python:

import json
import logging

import azure.functions as func

def main(event: func.EventGridEvent):

    result = json.dumps({
        'id': event.id,
        'data': event.get_json(),
        'topic': event.topic,
        'subject': event.subject,
        'event_type': event.event_type,
    })

    logging.info('Python EventGrid trigger processed an event: %s', result)

السمات

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

فيما يلي سمة EventGridTrigger في توقيع أسلوب:

[FunctionName("EventGridTest")]
public static void EventGridTest([EventGridTrigger] JObject eventGridEvent, ILogger log)
{

فيما يلي سمة EventGridTrigger في توقيع أسلوب:

[Function("EventGridFunction")]
[EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
{

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

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

خاصية function.json	الوصف
النوع	مطلوب - يجب تعيينه إلى `eventGridTrigger`.
الاتجاه	مطلوب - يجب تعيينه إلى `in`.
الاسم	مطلوب - اسم المتغير المستخدم في التعليمة البرمجية للدالة للمعلمة التي تتلقى بيانات الحدث.

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

يتيح لك تعليق EventGridTrigger التوضيحي تكوين ربط Event Grid بشكل تعريفي عن طريق تقديم قيم التكوين. راجع قسمي المثال و التهيئة لمزيد من التفاصيل.

التكوين

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

خاصية function.json	الوصف
النوع	مطلوب - يجب تعيينه إلى `eventGridTrigger`.
الاتجاه	مطلوب - يجب تعيينه إلى `in`.
الاسم	مطلوب - اسم المتغير المستخدم في التعليمة البرمجية للدالة للمعلمة التي تتلقى بيانات الحدث.

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

الاستخدام

يعتمد نوع المعلمة الذي يدعمه مشغل Event Grid على إصدار وقت تشغيل الدالات وإصدار حزمة الملحقات وطريقة C # المستخدمة.

تدعم وظائف مكتبة الفئة C# أثناء العملية الأنواع التالية:

يتوفر مثيل حدث Event Grid عبر المعلمة المقترنة بالسمة EventGridTrigger المكتوبة في شكل EventSchema.

يتوفر مثيل Event Grid عبر المعلمة المكونة في خاصية ملف function.jsonname.

يتوفر مثيل Event Grid عبر المعلمة المكونة في خاصية ملف function.jsonname المكتوبة في شكل func.EventGridEvent.

مخطط الأحداث

يتم تلقي البيانات لحدث Event Grid كعنصر JSON في نص طلب HTTP. تبدو JSON مماثلة للمثال التالي:

[{
  "topic": "/subscriptions/{subscriptionid}/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstore",
  "subject": "/blobServices/default/containers/{containername}/blobs/blobname.jpg",
  "eventType": "Microsoft.Storage.BlobCreated",
  "eventTime": "2018-01-23T17:02:19.6069787Z",
  "id": "{guid}",
  "data": {
    "api": "PutBlockList",
    "clientRequestId": "{guid}",
    "requestId": "{guid}",
    "eTag": "0x8D562831044DDD0",
    "contentType": "application/octet-stream",
    "contentLength": 2248,
    "blobType": "BlockBlob",
    "url": "https://egblobstore.blob.core.windows.net/{containername}/blobname.jpg",
    "sequencer": "000000000000272D000000000003D60F",
    "storageDiagnostics": {
      "batchId": "{guid}"
    }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

المثال المعروض هو صفيف عنصر واحد. ترسل Event Grid صفيفًا دائمًا وقد ترسل أكثر من حدث واحد في الصفيف. يستدعي وقت التشغيل الدالة مرة واحدة لكل عنصر صفيف.

خصائص المستوى الأعلى في بيانات JSON للحدث هي نفسها بين كل أنواع الأحداث، بينما محتويات خاصية data تكون خاصة بكل نوع حدث. المثال الموضح خاص بحدث تخزين كائن ثنائي كبير الحجم.

للحصول على توضيحات للخصائص المشتركة والخاصة بالحدث، راجع خصائص الحدث في وثائق Event Grid.

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

إرسال حدث «شبكة الأحداث»