Pengikatan output Azure Event Grid untuk Azure Functions

  • Artikel

Gunakan pengikatan output Azure Event Grid untuk menulis kejadian ke topik kustom. Anda harus memiliki kunci akses yang valid untuk topik kustom. Pengikatan output Event Grid tidak mendukung token tanda tangan akses bersama (SAS).

Untuk informasi tentang detail penyiapan dan konfigurasi, lihat Cara menggunakan pemicu dan pengikatan Event Grid di Azure Functions.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

Penting

Pengikatan output Azure Event Grid hanya tersedia untuk Functions 2.x dan yang lebih tinggi.

Contoh

Jenis parameter output yang digunakan dengan pengikatan output Event Grid bergantung pada versi runtime Functions, versi ekstensi pengikatan, dan modalitas fungsi C#. Fungsi C# dapat dibuat menggunakan salah satu mode C# berikut:

Contoh berikut menunjukkan cara penggunaan jenis kustom dalam pemicu dan pengikatan output Event Grid:

using System;
using System.Collections.Generic;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public static class EventGridFunction
    {
        [Function(nameof(EventGridFunction))]
        [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
        public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
        {
            var logger = context.GetLogger(nameof(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;
        }
    }

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

Contoh berikut menunjukkan fungsi Java yang menulis pesan ke topik kustom Event Grid. Fungsi menggunakan metode pengikatan setValue untuk menghasilkan string.

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

Anda juga dapat menggunakan kelas POJO untuk mengirim pesan Event Grid.

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

Contoh berikut menunjukkan fungsi TypeScript yang dipicu timer yang menghasilkan satu peristiwa:

import { app, EventGridPartialEvent, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<EventGridPartialEvent> {
    const timeStamp = new Date().toISOString();
    return {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    };
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventGrid({
        topicEndpointUri: 'MyEventGridTopicUriSetting',
        topicKeySetting: 'MyEventGridTopicKeySetting',
    }),
    handler: timerTrigger1,
});

Untuk menghasilkan beberapa peristiwa, kembalikan array alih-alih satu objek. Contohnya:

const timeStamp = new Date().toISOString();
return [
    {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    },
    {
        id: 'message-id-2',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Doe',
        },
        eventTime: timeStamp,
    },
];

Contoh berikut menunjukkan fungsi JavaScript yang dipicu timer yang menghasilkan satu peristiwa:

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

const eventGridOutput = output.eventGrid({
    topicEndpointUri: 'MyEventGridTopicUriSetting',
    topicKeySetting: 'MyEventGridTopicKeySetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventGridOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return {
            id: 'message-id',
            subject: 'subject-name',
            dataVersion: '1.0',
            eventType: 'event-type',
            data: {
                name: 'John Henry',
            },
            eventTime: timeStamp,
        };
    },
});

Untuk menghasilkan beberapa peristiwa, kembalikan array alih-alih satu objek. Contohnya:

const timeStamp = new Date().toISOString();
return [
    {
        id: 'message-id',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Henry',
        },
        eventTime: timeStamp,
    },
    {
        id: 'message-id-2',
        subject: 'subject-name',
        dataVersion: '1.0',
        eventType: 'event-type',
        data: {
            name: 'John Doe',
        },
        eventTime: timeStamp,
    },
];

Contoh berikut menunjukkan cara mengonfigurasi fungsi untuk menghasilkan pesan kejadian Azure Event Grid. Bagian tempat type diatur untuk eventGrid mengonfigurasi nilai yang diperlukan untuk membuat pengikatan output Azure Event Grid.

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

Dalam fungsi Anda, gunakan Push-OutputBinding untuk mengirim kejadian ke topik kustom melalui pengikatan output Azure Event Grid.

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

Contoh berikut menunjukkan pengikatan pemicu dan fungsi Python yang menggunakan pengikatan. Kemudian mengirim kejadian ke topik kustom, seperti yang ditentukan oleh topicEndpointUri. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

Berikut adalah fungsi dalam file function_app.py:

import logging
import azure.functions as func
import datetime

app = func.FunctionApp()

@app.function_name(name="eventgrid_output")
@app.event_grid_trigger(arg_name="eventGridEvent")
@app.event_grid_output(
    arg_name="outputEvent",
    topic_endpoint_uri="MyEventGridTopicUriSetting",
    topic_key_setting="MyEventGridTopicKeySetting")
def eventgrid_output(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"))

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk mengonfigurasi pengikatan. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.

Konstruktor atribut mengambil nama pengaturan aplikasi yang berisi nama topik kustom, dan nama pengaturan aplikasi yang berisi kunci topik.

Tabel berikut menjelaskan parameter untuk EventGridOutputAttribute.

Parameter Deskripsi
TopicEndpointUri Nama pengaturan aplikasi yang berisi URI untuk topik kustom, seperti MyTopicEndpointUri.
TopikKeySetting Nama setelan aplikasi yang berisi kunci akses untuk topik kustom.
koneksi* Nilai awalan umum untuk pengaturan yang berisi URI titik akhir topik. Untuk informasi selengkapnya tentang format penamaan pengaturan aplikasi ini, lihat Autentikasi berbasis identitas.

Anotasi

Untuk kelas Java, gunakan atribut EventGridAttribute.

Konstruktor atribut mengambil nama pengaturan aplikasi yang berisi nama topik kustom, dan nama pengaturan aplikasi yang berisi kunci topik. Untuk informasi selengkapnya tentang pengaturan ini, lihat Output - konfigurasi. Berikut contoh atributnya 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) {
            ...
    }
}

Konfigurasi

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke output.eventGrid() metode .

Properti Deskripsi
topicEndpointUri Nama pengaturan aplikasi yang berisi URI untuk topik kustom, seperti MyTopicEndpointUri.
topikKeySetting Nama setelan aplikasi yang berisi kunci akses untuk topik kustom.
koneksi* Nilai awalan umum untuk pengaturan yang berisi URI titik akhir topik. Saat mengatur connection properti, topicEndpointUri properti dan topicKeySetting tidak boleh diatur. Untuk informasi selengkapnya tentang format penamaan pengaturan aplikasi ini, lihat Autentikasi berbasis identitas.

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json Deskripsi
jenis Harus diatur ke eventGrid.
arah Harus diatur ke out. Parameter ini diatur secara otomatis saat Anda membuat pengikatan di portal Azure.
nama Nama variabel yang digunakan dalam kode fungsi yang mewakili acara.
topicEndpointUri Nama pengaturan aplikasi yang berisi URI untuk topik kustom, seperti MyTopicEndpointUri.
topikKeySetting Nama setelan aplikasi yang berisi kunci akses untuk topik kustom.
koneksi* Nilai awalan umum untuk pengaturan yang berisi URI titik akhir topik. Untuk informasi selengkapnya tentang format penamaan pengaturan aplikasi ini, lihat Autentikasi berbasis identitas.

*Dukungan untuk koneksi berbasis identitas memerlukan ekstensi versi 3.3.x atau yang lebih tinggi.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Penting

Pastikan Anda mengatur nilai TopicEndpointUri ke nama pengaturan aplikasi yang berisi URI topik kustom. Jangan tentukan URI topik kustom secara langsung di properti ini. Hal yang sama berlaku saat menggunakan Connection.

Lihat Bagian contoh untuk contoh lengkapnya.

Penggunaan

Jenis parameter yang didukung oleh pengikatan output Event Grid bergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.

Saat Anda ingin fungsi menulis satu peristiwa, pengikatan output Event Grid dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Peristiwa sebagai string.
byte[] Byte pesan peristiwa.
Jenis yang bisa diserialisasikan JSON Objek yang mewakili peristiwa JSON. Functions mencoba menserialisasikan jenis objek CLR (POCO) lama biasa ke dalam data JSON.

Saat Anda ingin fungsi menulis beberapa peristiwa, pengikatan output Event Grid dapat mengikat ke jenis berikut:

Tipe Deskripsi
T[] di mana T adalah salah satu jenis peristiwa tunggal Array yang berisi beberapa peristiwa. Setiap entri mewakili satu peristiwa.

Untuk skenario output lainnya, buat dan gunakan jenis dari Azure.Messaging.EventGrid secara langsung.

Kirim pesan individual dengan memanggil parameter metode seperti out EventGridOutput paramName, dan tulis beberapa pesan dengan ICollector<EventGridOutput>.

Akses pesan output dengan mengembalikan nilai secara langsung atau menggunakan context.extraOutputs.set().

Akses peristiwa output dengan menggunakan cmdlet Push-OutputBinding untuk mengirim peristiwa ke pengikatan output Azure Event Grid.

Ada dua opsi untuk mengeluarkan pesan Event Grid dari suatu fungsi:

  • Nilai hasil : Mengatur properti name di function.json ke $return. Dengan konfigurasi ini, nilai pengembalian fungsi dipertahankan sebagai pesan Event Grid.
  • Imperatif: Meneruskan nilai ke metode set parameter yang dinyatakan sebagai jenis Keluar. Nilai yang diteruskan ke set dipertahankan sebagai pesan Event Grid.

Koneksi

Ada dua cara untuk mengautentikasi ke topik Event Grid saat menggunakan pengikatan output Event Grid:

Metode autentikasi Deskripsi
Menggunakan kunci topik Atur TopicEndpointUri properti dan TopicKeySetting , seperti yang dijelaskan dalam Menggunakan kunci topik.
Menggunakan identitas Atur Connection properti ke nama awalan bersama untuk beberapa pengaturan aplikasi, bersama-sama menentukan autentikasi berbasis identitas. Metode ini didukung saat menggunakan ekstensi versi 3.3.x atau yang lebih tinggi.

Menggunakan kunci topik

Gunakan langkah-langkah berikut untuk mengonfigurasi kunci topik:

  1. Ikuti langkah-langkah dalam Mendapatkan kunci akses untuk mendapatkan kunci topik untuk topik Event Grid Anda.

  2. Di pengaturan aplikasi Anda, buat pengaturan yang menentukan nilai kunci topik. Gunakan nama pengaturan ini untuk TopicKeySetting properti pengikatan.

  3. Di pengaturan aplikasi Anda, buat pengaturan yang menentukan titik akhir topik. Gunakan nama pengaturan ini untuk TopicEndpointUri properti pengikatan.

Autentikasi berbasis identitas

Saat menggunakan ekstensi versi 3.3.x atau yang lebih tinggi, Anda dapat terhubung ke topik Event Grid menggunakan identitas Microsoft Entra untuk menghindari harus mendapatkan dan bekerja dengan kunci topik.

Anda perlu membuat pengaturan aplikasi yang mengembalikan URI titik akhir topik. Nama pengaturan harus menggabungkan awalan umum yang unik (misalnya, myawesometopic) dengan nilai __topicEndpointUri. Kemudian, Anda harus menggunakan awalan umum itu (dalam hal ini, myawesometopic) ketika Anda menentukan Connection properti dalam pengikatan.

Dalam mode ini, ekstensi tersebut memerlukan properti berikut:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
URI Titik Akhir Topik <CONNECTION_NAME_PREFIX>__topicEndpointUri Titik akhir topik. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

Properti lainnya dapat digunakan untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

Catatan

Saat menggunakan Azure App Configuration atau Key Vault untuk menyediakan pengaturan untuk koneksi berbasis identitas terkelola, nama pengaturan harus menggunakan pemisah kunci yang valid seperti : atau / sebagai ganti __ untuk memastikan nama diselesaikan dengan benar.

Contohnya,<CONNECTION_NAME_PREFIX>:topicEndpointUri.

Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential dan clientID properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan oleh pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.

Memberikan izin kepada identitas

Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.

Anda harus membuat penetapan peran yang menyediakan akses ke topik Event Grid Anda saat runtime. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Azure Event Hubs dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

Jenis pengikatan Peran bawaan contoh
Pengikatan output Kontributor EventGrid, Pengirim Data EventGrid

Langkah berikutnya