Powiązanie wyjściowe usługi Azure Event Grid dla usługi Azure Functions

  • Artykuł

Użyj powiązania danych wyjściowych usługi Event Grid, aby zapisywać zdarzenia w temacie niestandardowym. Musisz mieć prawidłowy klucz dostępu dla tematu niestandardowego. Powiązanie wyjściowe usługi Event Grid nie obsługuje tokenów sygnatury dostępu współdzielonego (SAS).

Aby uzyskać informacje na temat konfiguracji i szczegółów konfiguracji, zobacz Jak pracować z wyzwalaczami i powiązaniami usługi Event Grid w usłudze Azure Functions.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Usługa Azure Functions obsługuje dwa modele programowania dla języka Python. Sposób definiowania powiązań zależy od wybranego modelu programowania.

Model programowania w języku Python w wersji 2 umożliwia definiowanie powiązań przy użyciu dekoratorów bezpośrednio w kodzie funkcji języka Python. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów języka Python.

Ten artykuł obsługuje oba modele programowania.

Ważne

Powiązanie wyjściowe usługi Event Grid jest dostępne tylko dla funkcji 2.x i nowszych.

Przykład

Typ parametru wyjściowego używanego z powiązaniem danych wyjściowych usługi Event Grid zależy od wersji środowiska uruchomieniowego usługi Functions, wersji rozszerzenia powiązania i modalności funkcji języka C#. Funkcję języka C# można utworzyć przy użyciu jednego z następujących trybów języka C#:

  • Biblioteka klas procesu: skompilowana funkcja języka C#, która działa w tym samym procesie co środowisko uruchomieniowe usługi Functions.
  • Izolowana biblioteka klas procesów roboczych: skompilowana funkcja języka C#, która jest uruchamiana w procesie roboczym izolowanym od środowiska uruchomieniowego.

W poniższym przykładzie pokazano, jak typ niestandardowy jest używany zarówno w wyzwalaczu, jak i powiązaniu danych wyjściowych usługi 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; }
    }
}

W poniższym przykładzie przedstawiono funkcję Języka Java, która zapisuje komunikat w niestandardowym temacie usługi Event Grid. Funkcja używa metody powiązania setValue do wyprowadzania ciągu.

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

Możesz również użyć klasy POJO do wysyłania komunikatów usługi 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;
    }  
}

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalaną przez czasomierz, która generuje pojedyncze zdarzenie:

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

Aby wygenerować wiele zdarzeń, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

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

W poniższym przykładzie przedstawiono funkcję javaScript wyzwalaną przez czasomierz, która generuje pojedyncze zdarzenie:

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

Aby wygenerować wiele zdarzeń, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

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

W poniższym przykładzie pokazano, jak skonfigurować funkcję w celu wyprowadzenia komunikatu zdarzenia usługi Event Grid. Sekcja, w której type jest ustawiona wartość eventGrid , umożliwia skonfigurowanie wartości wymaganych do ustanowienia powiązania wyjściowego usługi 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"
    }
  ]
}

W funkcji użyj polecenia , Push-OutputBinding aby wysłać zdarzenie do tematu niestandardowego za pomocą powiązania wyjściowego usługi 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"
})

W poniższym przykładzie przedstawiono powiązanie wyzwalacza i funkcję języka Python, która używa powiązania. Następnie wysyła zdarzenie do tematu niestandardowego zgodnie z parametrem topicEndpointUri. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

Oto funkcja w pliku 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"))

Atrybuty

Zarówno w procesie, jak i izolowanym procesie roboczym biblioteki języka C# używają atrybutu do konfigurowania powiązania. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

Konstruktor atrybutu przyjmuje nazwę ustawienia aplikacji zawierającego nazwę tematu niestandardowego oraz nazwę ustawienia aplikacji zawierającego klucz tematu.

W poniższej tabeli opisano parametry dla elementu EventGridOutputAttribute.

Parametr Opis
IdentyfikatorUri punktu końcowego tematu Nazwa ustawienia aplikacji zawierającego identyfikator URI tematu niestandardowego, na przykład MyTopicEndpointUri.
TopicKeySetting Nazwa ustawienia aplikacji zawierającego klucz dostępu dla tematu niestandardowego.
Połączenia* Wartość wspólnego prefiksu ustawienia zawierającego identyfikator URI punktu końcowego tematu. Aby uzyskać więcej informacji na temat formatu nazewnictwa tego ustawienia aplikacji, zobacz Uwierzytelnianie oparte na tożsamościach.

Adnotacje

W przypadku klas języka Java użyj atrybutu EventGridAttribute .

Konstruktor atrybutu przyjmuje nazwę ustawienia aplikacji zawierającego nazwę tematu niestandardowego oraz nazwę ustawienia aplikacji zawierającego klucz tematu. Aby uzyskać więcej informacji na temat tych ustawień, zobacz Dane wyjściowe — konfiguracja. Oto przykład atrybutu 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) {
            ...
    }
}

Konfigurowanie

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego output.eventGrid() do metody .

Właściwości opis
topicEndpointUri Nazwa ustawienia aplikacji zawierającego identyfikator URI tematu niestandardowego, na przykład MyTopicEndpointUri.
topicKeySetting Nazwa ustawienia aplikacji zawierającego klucz dostępu dla tematu niestandardowego.
Połączenia* Wartość wspólnego prefiksu ustawienia zawierającego identyfikator URI punktu końcowego tematu. Podczas ustawiania connection właściwości topicEndpointUri właściwości i topicKeySetting nie należy ustawiać. Aby uzyskać więcej informacji na temat formatu nazewnictwa tego ustawienia aplikacji, zobacz Uwierzytelnianie oparte na tożsamościach.

Konfigurowanie

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json .

właściwość function.json opis
type Musi być ustawiona wartość eventGrid.
direction Musi być ustawiona wartość out. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w witrynie Azure Portal.
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje zdarzenie.
topicEndpointUri Nazwa ustawienia aplikacji zawierającego identyfikator URI tematu niestandardowego, na przykład MyTopicEndpointUri.
topicKeySetting Nazwa ustawienia aplikacji zawierającego klucz dostępu dla tematu niestandardowego.
Połączenia* Wartość wspólnego prefiksu ustawienia zawierającego identyfikator URI punktu końcowego tematu. Aby uzyskać więcej informacji na temat formatu nazewnictwa tego ustawienia aplikacji, zobacz Uwierzytelnianie oparte na tożsamościach.

*Obsługa połączeń opartych na tożsamościach wymaga wersji 3.3.x lub nowszej rozszerzenia.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Ważne

Upewnij się, że ustawiono wartość TopicEndpointUri na nazwę ustawienia aplikacji zawierającego identyfikator URI tematu niestandardowego. Nie określaj identyfikatora URI tematu niestandardowego bezpośrednio w tej właściwości. To samo ma zastosowanie w przypadku używania polecenia Connection.

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Użycie

Typ parametru obsługiwany przez powiązanie wyjściowe usługi Event Grid zależy od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Jeśli chcesz, aby funkcja zapisywała pojedyncze zdarzenie, powiązanie danych wyjściowych usługi Event Grid może wiązać się z następującymi typami:

Type Opis
string Zdarzenie jako ciąg.
byte[] Bajty komunikatu zdarzenia.
Typy serializowalne w formacie JSON Obiekt reprezentujący zdarzenie JSON. Funkcje próbują serializować zwykły typ obiektu CLR (POCO) do danych JSON.

Jeśli chcesz, aby funkcja zapisywała wiele zdarzeń, powiązanie danych wyjściowych usługi Event Grid może wiązać się z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów zdarzeń Tablica zawierająca wiele zdarzeń. Każdy wpis reprezentuje jedno zdarzenie.

W przypadku innych scenariuszy wyjściowych utwórz typy i użyj ich bezpośrednio z witryny Azure.Messaging.EventGrid .

Wysyłaj poszczególne komunikaty, wywołując parametr metody, taki jak out EventGridOutput paramName, i zapisując wiele komunikatów za pomocą polecenia ICollector<EventGridOutput>.

Uzyskaj dostęp do komunikatu wyjściowego, zwracając wartość bezpośrednio lub przy użyciu polecenia context.extraOutputs.set().

Uzyskaj dostęp do zdarzenia wyjściowego Push-OutputBinding przy użyciu polecenia cmdlet , aby wysłać zdarzenie do powiązania wyjściowego usługi Event Grid.

Istnieją dwie opcje wyprowadzania komunikatu usługi Event Grid z funkcji:

  • Wartość zwracana name : ustaw właściwość w function.json na $returnwartość . W przypadku tej konfiguracji wartość zwracana funkcji jest utrwalana jako komunikat usługi Event Grid.
  • Imperatywne: przekaż wartość do metody set parametru zadeklarowanego jako typ out . Przekazana wartość jest utrwalana set jako komunikat usługi Event Grid.

Połączenia

Istnieją dwa sposoby uwierzytelniania w temacie usługi Event Grid podczas korzystania z powiązania wyjściowego usługi Event Grid:

Metoda uwierzytelniania opis
Używanie klucza tematu TopicEndpointUri Ustaw właściwości i TopicKeySetting zgodnie z opisem w temacie Używanie klucza tematu.
Korzystanie z tożsamości Connection Ustaw właściwość na nazwę udostępnionego prefiksu dla wielu ustawień aplikacji, definiując uwierzytelnianie oparte na tożsamościach. Ta metoda jest obsługiwana w przypadku używania wersji 3.3.x lub nowszej rozszerzenia.

Używanie klucza tematu

Aby skonfigurować klucz tematu, wykonaj następujące czynności:

  1. Wykonaj kroki opisane w temacie Uzyskiwanie kluczy dostępu, aby uzyskać klucz tematu dla tematu usługi Event Grid.

  2. W ustawieniach aplikacji utwórz ustawienie definiujące wartość klucza tematu. Użyj nazwy tego ustawienia dla TopicKeySetting właściwości powiązania.

  3. W ustawieniach aplikacji utwórz ustawienie definiujące punkt końcowy tematu. Użyj nazwy tego ustawienia dla TopicEndpointUri właściwości powiązania.

Uwierzytelnianie na podstawie tożsamości

W przypadku korzystania z rozszerzenia w wersji 3.3.x lub nowszej można nawiązać połączenie z tematem usługi Event Grid przy użyciu tożsamości entra firmy Microsoft, aby uniknąć konieczności uzyskiwania kluczy tematów i pracy z nimi.

Musisz utworzyć ustawienie aplikacji zwracające identyfikator URI punktu końcowego tematu. Nazwa ustawienia powinna łączyć unikatowy wspólny prefiks (na przykład myawesometopic) z wartością __topicEndpointUri. Następnie należy użyć tego wspólnego prefiksu (w tym przypadku myawesometopic) podczas definiowania Connection właściwości w powiązaniu.

W tym trybie rozszerzenie wymaga następujących właściwości:

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
Identyfikator URI punktu końcowego tematu <CONNECTION_NAME_PREFIX>__topicEndpointUri Punkt końcowy tematu. https://<topic-name>.centralus-1.eventgrid.azure.net/api/events

Aby dostosować połączenie, można użyć większej liczby właściwości. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

Uwaga

W przypadku korzystania z usługi aplikacja systemu Azure Configuration lub Key Vault w celu zapewnienia ustawień dla połączeń opartych na tożsamości zarządzanej nazwy powinny używać prawidłowego separatora kluczy, takiego jak : lub / zamiast __ niego, aby upewnić się, że nazwy są poprawnie rozpoznawane.

Na przykład <CONNECTION_NAME_PREFIX>:topicEndpointUri.

W przypadku hostowania w usłudze Azure Functions połączenia oparte na tożsamościach używają tożsamości zarządzanej. Tożsamość przypisana przez system jest używana domyślnie, chociaż tożsamości przypisanej przez użytkownika można określić za credential pomocą właściwości i clientID . Należy pamiętać, że konfigurowanie tożsamości przypisanej przez użytkownika przy użyciu identyfikatora zasobu nie jest obsługiwane. W przypadku uruchamiania w innych kontekstach, takich jak programowanie lokalne, tożsamość dewelopera jest używana, chociaż można to dostosować. Zobacz Programowanie lokalne z połączeniami opartymi na tożsamościach.

Udzielanie uprawnień tożsamości

Niezależnie od używanej tożsamości musi mieć uprawnienia do wykonywania zamierzonych akcji. W przypadku większości usług platformy Azure oznacza to, że musisz przypisać rolę w kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych ról, które zapewniają te uprawnienia.

Ważne

Niektóre uprawnienia mogą być uwidocznione przez usługę docelową, które nie są niezbędne dla wszystkich kontekstów. Jeśli to możliwe, przestrzegaj zasady najniższych uprawnień, udzielając tożsamości tylko wymaganych uprawnień. Jeśli na przykład aplikacja musi mieć możliwość odczytu tylko ze źródła danych, użyj roli, która ma uprawnienia tylko do odczytu. Niewłaściwe byłoby przypisanie roli, która umożliwia również zapisywanie w tej usłudze, ponieważ byłoby to nadmierne uprawnienie do operacji odczytu. Podobnie należy upewnić się, że przypisanie roli jest ograniczone tylko do zasobów, które należy odczytać.

Musisz utworzyć przypisanie roli, które zapewnia dostęp do tematu usługi Event Grid w czasie wykonywania. Role zarządzania, takie jak Właściciel , nie są wystarczające. W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z rozszerzenia usługi Event Hubs w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe role wbudowane
Powiązanie wyjściowe EventGrid — współautor, nadawca danych usługi EventGrid

Następne kroki