ربط إخراج شبكة أحداث Azure لـ Azure Functions

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

استخدم ربط إخراج "شبكة الأحداث" لكتابة الأحداث إلى موضوع مخصص. يجب أن يكون لديك مفتاح اختصار صالح للموضوع المخصص. لا يدعم ربط مخرجات شبكة الأحداث الرموز المميزة لتوقيع الوصول المشترك (SAS).

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع كيفية العمل مع مشغلات شبكة الأحداث وارتباطاتها في وظائف Azure.

هام

ربط إخراج شبكة الأحداث متوفر فقط لـ Functions 2.x وأعلى.

مثال

يعتمد نوع معلمة الإخراج المستخدمة مع ربط إخراج شبكة الأحداث على إصدار وقت تشغيل الدالات وإصدار ملحق الربط وطريقة الدالة C #. يمكن إنشاء الدالة C # باستخدام أحد أوضاع C # التالية:

يوضح المثال التالي دالة C# ترتبط بإصدار CloudEvent 3.x من الملحق الذي يستخدم الإصدار قيد المعاينة:

using System.Threading.Tasks;
using Azure.Messaging;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Extensions.Http;

namespace Azure.Extensions.WebJobs.Sample
{
    public static class CloudEventBindingFunction
    {
        [FunctionName("CloudEventBindingFunction")]
        public static async Task<IActionResult> RunAsync(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
            [EventGrid(TopicEndpointUri = "EventGridEndpoint", TopicKeySetting = "EventGridKey")] IAsyncCollector<CloudEvent> eventCollector)
        {
            CloudEvent e = new CloudEvent("IncomingRequest", "IncomingRequest", await req.ReadAsStringAsync());
            await eventCollector.AddAsync(e);
            return new OkResult();
        }
    }
}

يوضح المثال التالي الدالة C# التي ترتبط بالإصدار EventGridEvent 3.x من الملحق الذي يستخدم الإضافة، وهو قيد المعاينة:

using System.Threading.Tasks;
using Azure.Messaging.EventGrid;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;

namespace Azure.Extensions.WebJobs.Sample
{
    public static class EventGridEventBindingFunction
    {
        [FunctionName("EventGridEventBindingFunction")]
        public static async Task<IActionResult> RunAsync(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
            [EventGrid(TopicEndpointUri = "EventGridEndpoint", TopicKeySetting = "EventGridKey")] IAsyncCollector<EventGridEvent> eventCollector)
        {
            EventGridEvent e = new EventGridEvent(await req.ReadAsStringAsync(), "IncomingRequest", "IncomingRequest", "1.0.0");
            await eventCollector.AddAsync(e);
            return new OkResult();
        }
    }
}

يوضح المثال التالي الدالة C# التي تكتب رسالة Microsoft.Azure.EventGrid.Models.EventGridEvent إلى موضوع مخصص "شبكة الأحداث"، باستخدام قيمة إرجاع الأسلوب كمخرج:

[FunctionName("EventGridOutput")]
[return: EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
public static EventGridEvent Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    return new EventGridEvent("message-id", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
}

يوضح المثال التالي كيفية استخدام واجهة IAsyncCollector لإرسال دفعة من الرسائل.

[FunctionName("EventGridAsyncOutput")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]IAsyncCollector<EventGridEvent> outputEvents,
    ILogger log)
{
    for (var i = 0; i < 3; i++)
    {
        var myEvent = new EventGridEvent("message-id-" + i, "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
        await outputEvents.AddAsync(myEvent);
    }
}

يظهر المثال التالي دالة Java التي تكتب رسالة إلى موضوع مخصص لشبكة الأحداث. تستخدم الدالة أسلوب setValue للربط لإخراج سلسلة.

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<String> outputEvent,
            final ExecutionContext context) {
        context.getLogger().info("Java EventGrid trigger processed a request." + content);
        final String eventGridOutputDocument = "{\"id\": \"1807\", \"eventType\": \"recordInserted\", \"subject\": \"myapp/cars/java\", \"eventTime\":\"2017-08-10T21:03:07+00:00\", \"data\": {\"make\": \"Ducati\",\"model\": \"Monster\"}, \"dataVersion\": \"1.0\"}";
        outputEvent.setValue(eventGridOutputDocument);
    }
}

يمكنك أيضًا استخدام فئة POJO لإرسال رسائل EventGrid.

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<EventGridEvent> outputEvent,
            final ExecutionContext context) {
        context.getLogger().info("Java EventGrid trigger processed a request." + content);

        final EventGridEvent eventGridOutputDocument = new EventGridEvent();
        eventGridOutputDocument.setId("1807");
        eventGridOutputDocument.setEventType("recordInserted");
        eventGridOutputDocument.setEventTime("2017-08-10T21:03:07+00:00");
        eventGridOutputDocument.setDataVersion("1.0");
        eventGridOutputDocument.setSubject("myapp/cars/java");
        eventGridOutputDocument.setData("{\"make\": \"Ducati\",\"model\":\"monster\"");

        outputEvent.setValue(eventGridOutputDocument);
    }
}

class EventGridEvent {
    private String id;
    private String eventType;
    private String subject;
    private String eventTime;
    private String dataVersion;
    private String data;

    public String getId() {
        return id;
    }

    public String getData() {
        return data;
    }

    public void setData(String data) {
        this.data = data;
    }

    public String getDataVersion() {
        return dataVersion;
    }

    public void setDataVersion(String dataVersion) {
        this.dataVersion = dataVersion;
    }

    public String getEventTime() {
        return eventTime;
    }

    public void setEventTime(String eventTime) {
        this.eventTime = eventTime;
    }

    public String getSubject() {
        return subject;
    }

    public void setSubject(String subject) {
        this.subject = subject;
    }

    public String getEventType() {
        return eventType;
    }

    public void setEventType(String eventType) {
        this.eventType = eventType;
    }

    public void setId(String id) {
        this.id = id;
    }  
}

يظهر المثال التالي بيانات ربط إخراج شبكة الأحداث في ملف function.json.

{
    "type": "eventGrid",
    "name": "outputEvent",
    "topicEndpointUri": "MyEventGridTopicUriSetting",
    "topicKeySetting": "MyEventGridTopicKeySetting",
    "direction": "out"
}

فيما يلي التعليمات البرمجية لـ JavaScript التي تنشئ حدثًا واحدًا:

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    context.bindings.outputEvent = {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: "event-data",
        eventTime: timeStamp
    };
};

فيما يلي التعليمات البرمجية لـ JavaScript التي تنشئ أحداث متعددة:

module.exports = async function(context) {
    var timeStamp = new Date().toISOString();

    context.bindings.outputEvent = [];

    context.bindings.outputEvent.push({
        id: 'message-id-1',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: "event-data",
        eventTime: timeStamp
    });
    context.bindings.outputEvent.push({
        id: 'message-id-2',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: "event-data",
        eventTime: timeStamp
    });
};

يوضح المثال التالي كيفية تكوين دالة لإخراج رسالة حدث شبكة الأحداث. القسم حيثما تم تعيين type إلى eventGrid يقوم بتكوين القيم المطلوبة لتأسيس ربط إخراج شبكة الأحداث.

{
  "bindings": [
    {
      "type": "eventGrid",
      "name": "outputEvent",
      "topicEndpointUri": "MyEventGridTopicUriSetting",
      "topicKeySetting": "MyEventGridTopicKeySetting",
      "direction": "out"
    },
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

في الدالة لديك، استخدم Push-OutputBinding لإرسال حدث إلى موضوع مخصص من خلال ربط إخراج "شبكة الأحداث".

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message

Push-OutputBinding -Name outputEvent -Value  @{
    id = "1"
    EventType = "testEvent"
    Subject = "testapp/testPublish"
    EventTime = "2020-08-27T21:03:07+00:00"
    Data = @{
        Message = $message
    }
    DataVersion = "1.0"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

يظهر المثال التالي ربط مشغل في ملف function.json ودالة Python التي تستخدم الربط. ثم يرسل حدثًا إلى الموضوع المخصص، كما هو محدد بواسطة topicEndpointUri.

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

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    },
    {
      "type": "eventGrid",
      "name": "outputEvent",
      "topicEndpointUri": "MyEventGridTopicUriSetting",
      "topicKeySetting": "MyEventGridTopicKeySetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

فيما يلي نموذج Python لإرسال حدث إلى موضوع مخصص عن طريق تعيين EventGridOutputEvent:

import logging
import azure.functions as func
import datetime

def main(eventGridEvent: func.EventGridEvent, 
         outputEvent: func.Out[func.EventGridOutputEvent]) -> None:

    logging.log("eventGridEvent: ", eventGridEvent)

    outputEvent.set(
        func.EventGridOutputEvent(
            id="test-id",
            data={"tag1": "value1", "tag2": "value2"},
            subject="test-subject",
            event_type="test-event-1",
            event_time=datetime.datetime.utcnow(),
            data_version="1.0"))

السمات

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

يأخذ منشئ السمة اسم إعداد تطبيق يحتوي على اسم الموضوع المخصص واسم إعداد تطبيق يحتوي على مفتاح الموضوع.

يشرح الجدول التالي معلمات EventGridAttribute.

المعلمة الوصف
TopicEndpointUri اسم إعداد تطبيق يحتوي على عنوان URI للموضوع المخصص، مثل MyTopicEndpointUri.
TopicKeySetting اسم إعداد تطبيق يحتوي على مفتاح اختصار للموضوع المخصص.

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

بالنسبة لفئات Java، استخدم السمة EventGridAttribute.

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

public class Function {
    @FunctionName("EventGridTriggerTest")
    public void run(@EventGridTrigger(name = "event") String content,
            @EventGridOutput(name = "outputEvent", topicEndpointUri = "MyEventGridTopicUriSetting", topicKeySetting = "MyEventGridTopicKeySetting") OutputBinding<String> outputEvent, final ExecutionContext context) {
            ...
    }
}

التكوين

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

خاصية function.json الوصف
النوع يجب تعيينها إلى eventGrid.
⁧⁩direction⁧⁩ يجب تعيينها إلى out. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم اسم المتغير المستخدم في التعليمات البرمجية للدالة التي تمثل الحدث.
topicEndpointUri اسم إعداد تطبيق يحتوي على عنوان URI للموضوع المخصص، مثل MyTopicEndpointUri.
topicKeySetting اسم إعداد تطبيق يحتوي على مفتاح اختصار للموضوع المخصص.

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

هام

تأكد من تعيين قيمة خاصية التكوين إلى اسم إعداد تطبيق يحتوي على عنوان URI للموضوع المخصص TopicEndpointUri . لا تحدد عنوان URI للموضوع المخصص مباشرة في هذه الخاصية.

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

الاستخدام

يعتمد نوع المعلمة المدعوم من قبل ربط إخراج شبكة الحدث على إصدار وقت تشغيل الدالات وإصدار حزمة الملحقات وطريقة C # المستخدمة.

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

  • Azure.Messaging.CloudEvent
  • [Azure.Messaging.EventGrid] [EventGridEvent2]
  • [Newtonsoft.Json.Linq.JObject] [JObject]
  • [System.String] [سلسلة]

إرسال رسائل باستخدام معلمة أسلوب مثل out EventGridEvent paramName. لكتابة رسائل متعددة، يمكنك بدلا من ذلك استخدام ICollector<EventGridEvent> أو IAsyncCollector<EventGridEvent>.

إرسال رسائل فردية عن طريق استدعاء معلمة أسلوب مثل out EventGridOutput paramName، وكتابة رسائل متعددة باستخدام ICollector<EventGridOutput>.

الوصول إلى حدث الإخراج باستخدام context.bindings.<name> حيث <name> هي القيمة المحددة في name خاصية function.json.

قم بالوصول إلى حدث الإخراج Push-OutputBinding باستخدام cmdlet لإرسال حدث إلى ربط مخرجات شبكة الأحداث.

هناك خياران لإخراج رسالة "شبكة الأحداث" من دالة:

  • قيمة الإرجاع: تعيين الخاصية name في function.json إلى $return. باستخدام هذا التكوين، تستمر قيمة إرجاع الدالة كرسالة "شبكة الأحداث".
  • أمر حتمي: تمرير قيمة إلى الأسلوب المُحدد الخاص بالمعلمة التي أُعلن عنها باعتبارها نوع Out. تستمر القيمة التي تم تمريرها كرسالة set "شبكة الأحداث".

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