Udostępnij za pośrednictwem

Powiązanie wyjściowe usługi Azure Service Bus dla usługi Azure Functions

  • Artykuł

Użyj powiązania wyjściowego usługi Azure Service Bus, aby wysyłać komunikaty dotyczące kolejki lub tematu.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

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.

Przykład

Funkcję języka C# można utworzyć przy użyciu jednego z następujących trybów języka C#:

  • Model izolowanego procesu roboczego: skompilowana funkcja języka C#, która jest uruchamiana w procesie roboczym izolowanym od środowiska uruchomieniowego. Proces izolowanego procesu roboczego jest wymagany do obsługi funkcji języka C# uruchomionych w wersjach LTS i innych niż LTS platformy .NET oraz programu .NET Framework. Rozszerzenia dla izolowanych funkcji procesu roboczego używają Microsoft.Azure.Functions.Worker.Extensions.* przestrzeni nazw.
  • Model przetwarzania: skompilowana funkcja języka C#, która działa w tym samym procesie co środowisko uruchomieniowe usługi Functions. W odmianie tego modelu funkcje można uruchamiać przy użyciu skryptów języka C#, które są obsługiwane głównie w przypadku edytowania portalu języka C#. Rozszerzenia dla funkcji przetwarzania używają Microsoft.Azure.WebJobs.Extensions.* przestrzeni nazw.

Ważne

Wsparcie zostanie zakończone dla modelu procesu 10 listopada 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do izolowanego modelu procesu roboczego w celu uzyskania pełnej obsługi.

Ten kod definiuje i inicjuje element ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

W tym przykładzie pokazano funkcję języka C#, która odbiera komunikat i zapisuje ją w drugiej kolejce:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

 

W tym przykładzie użyto wyzwalacza HTTP z obiektem OutputType w celu wysłania odpowiedzi HTTP i zapisania komunikatu wyjściowego.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Ten kod definiuje wiele typów OutputTypedanych wyjściowych, który zawiera definicję powiązania wyjściowego usługi Service Bus w pliku OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

W poniższym przykładzie pokazano funkcję Języka Java, która wysyła komunikat do kolejki myqueue usługi Service Bus po wyzwoleniu przez żądanie HTTP.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @QueueOutput adnotacji parametrów funkcji, których wartość zostanie zapisana w kolejce usługi Service Bus. Typ parametru powinien mieć OutputBinding<T>wartość , gdzie T jest dowolnym natywnym typem języka Java starego obiektu Java (POJO).

Funkcje języka Java mogą również zapisywać w temacie usługi Service Bus. W poniższym przykładzie użyto @ServiceBusTopicOutput adnotacji do opisania konfiguracji powiązania wyjściowego.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalaną przez czasomierz, która wysyła komunikat kolejki co 5 minut.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

Aby wyświetlić wiele komunikatów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

W poniższym przykładzie przedstawiono funkcję wyzwalaną przez czasomierz javaScript , która wysyła komunikat kolejki co 5 minut.

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Aby wyświetlić wiele komunikatów, zwróć tablicę zamiast pojedynczego obiektu. Na przykład:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

W poniższym przykładzie przedstawiono powiązanie wyjściowe usługi Service Bus w pliku function.json i funkcję programu PowerShell, która używa powiązania.

Oto dane powiązania w pliku function.json :

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Oto program PowerShell, który tworzy komunikat jako dane wyjściowe funkcji.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

W poniższym przykładzie pokazano, jak zapisywać dane w kolejce usługi Service Bus w języku Python. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Atrybuty

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

W bibliotekach klas języka C# użyj atrybutu ServiceBusOutputAttribute , aby zdefiniować kolejkę lub temat zapisany przez dane wyjściowe.

W poniższej tabeli opisano właściwości, które można ustawić przy użyciu atrybutu :

Właściwości opis
Typ jednostki Ustawia typ jednostki jako Queue na potrzeby wysyłania komunikatów do kolejki lub Topic podczas wysyłania komunikatów do tematu.
QueueOrTopicName Nazwa tematu lub kolejki do wysyłania komunikatów. Użyj EntityType polecenia , aby ustawić typ docelowy.
Połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Service Bus. Zobacz Połączenia.

Dekoratory

Dotyczy tylko modelu programowania w wersji 2 języka Python.

W przypadku funkcji języka Python w wersji 2 zdefiniowanych przy użyciu dekoratora następujące właściwości w pliku service_bus_topic_output:

Właściwości opis
arg_name Nazwa zmiennej reprezentującej komunikat kolejki lub tematu w kodzie funkcji.
queue_name Nazwa kolejki. Ustaw tylko w przypadku wysyłania komunikatów w kolejce, a nie tematu.
topic_name Nazwa tematu. Ustaw tylko w przypadku wysyłania komunikatów tematu, a nie dla kolejki.
connection Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Service Bus. Zobacz Połączenia.

Aby zapoznać się z funkcjami języka Python zdefiniowanymi przy użyciu function.json, zobacz sekcję Konfiguracja .

Adnotacje

ServiceBusQueueOutput Adnotacje i ServiceBusTopicOutput są dostępne do zapisania komunikatu jako danych wyjściowych funkcji. Parametr ozdobiony tymi adnotacjami musi być zadeklarowany jako typ , gdzie OutputBinding<T> T odpowiada typowi komunikatu.

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

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

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

Właściwości opis
queueName Nazwa kolejki.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Service Bus. Zobacz Połączenia.

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

Właściwości opis
nazwa tematu Nazwa tematu.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Service Bus. Zobacz Połączenia.

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

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

właściwość function.json opis
type Musi być ustawiona wartość serviceBus. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
direction Musi być ustawiona wartość out. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
name Nazwa zmiennej reprezentującej komunikat kolejki lub tematu w kodzie funkcji. Ustaw wartość "$return", aby odwołać się do wartości zwracanej przez funkcję.
queueName Nazwa kolejki. Ustaw tylko w przypadku wysyłania komunikatów w kolejce, a nie tematu.
nazwa tematu Nazwa tematu. Ustaw tylko w przypadku wysyłania komunikatów tematu, a nie dla kolejki.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą Service Bus. Zobacz Połączenia.
accessRights (tylko wersja 1) Prawa dostępu do parametry połączenia. Dostępne wartości to manage i listen. Wartość domyślna to manage, która wskazuje, że connection właściwość ma uprawnienie Zarządzaj . Jeśli używasz parametry połączenia, który nie ma uprawnienia Zarządzanie, ustaw wartość accessRights "nasłuchiwanie". W przeciwnym razie środowisko uruchomieniowe usługi Functions może nie próbować wykonywać operacji wymagających praw zarządzania. W usłudze Azure Functions w wersji 2.x lub nowszej ta właściwość nie jest dostępna, ponieważ najnowsza wersja zestawu SDK usługi Service Bus nie obsługuje operacji zarządzania.

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

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

Użycie

Wszystkie modalności i wersje rozszerzeń języka C# obsługują następujące typy parametrów wyjściowych:

Type Opis
System.String Użyj polecenia , gdy wiadomość do zapisu jest prostym tekstem. Gdy wartość parametru ma wartość null, gdy funkcja zakończy działanie, usługa Functions nie tworzy komunikatu.
byte[] Służy do pisania binarnych komunikatów o danych. Gdy wartość parametru ma wartość null, gdy funkcja zakończy działanie, usługa Functions nie tworzy komunikatu.
Obiekt Gdy komunikat zawiera kod JSON, usługa Functions serializuje obiekt do ładunku komunikatu JSON. Gdy wartość parametru ma wartość null, gdy funkcja zakończy działanie, usługa Functions tworzy komunikat z obiektem o wartości null.

Typy parametrów specyficznych dla komunikatów zawierają dodatkowe metadane komunikatów i nie są zgodne z serializacji JSON. W związku z tym nie można użyć ServiceBusMesage powiązania wyjściowego w modelu izolowanym. Określone typy obsługiwane przez powiązanie wyjściowe zależą od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Jeśli chcesz, aby funkcja mogła napisać pojedynczy komunikat, powiązanie danych wyjściowych usługi Service Bus może wiązać się z następującymi typami:

Type Opis
string Komunikat jako ciąg. Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Bajty komunikatu.
Typy serializowalne w formacie JSON Obiekt reprezentujący komunikat. Funkcje próbują serializować zwykły typ obiektu CLR (POCO) do danych JSON.

Jeśli chcesz, aby funkcja zapisywała wiele komunikatów, powiązanie danych wyjściowych usługi Service Bus może wiązać się z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów pojedynczych komunikatów Tablica zawierająca wiele komunikatów. Każdy wpis reprezentuje jeden komunikat.

W przypadku innych scenariuszy wyjściowych utwórz obiekt ServiceBusClient i użyj go bezpośrednio z poziomu klasy Azure.Messaging.ServiceBus. Zobacz Rejestrowanie klientów platformy Azure, aby zapoznać się z przykładem użycia wstrzykiwania zależności w celu utworzenia typu klienta z zestawu Azure SDK.

W usłudze Azure Functions 1.x środowisko uruchomieniowe tworzy kolejkę, jeśli nie istnieje i ustawiono wartość accessRights manage. W usłudze Azure Functions w wersji 2.x lub nowszej kolejka lub temat muszą już istnieć; Jeśli określisz kolejkę lub temat, który nie istnieje, funkcja zakończy się niepowodzeniem.

Użyj zestawu SDK usługi Azure Service Bus, a nie wbudowanego powiązania wyjściowego.

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

Dane wyjściowe do usługi Service Bus są dostępne za pośrednictwem Push-OutputBinding polecenia cmdlet, w którym przekazujesz argumenty zgodne z nazwą wyznaczoną przez parametr nazwy powiązania w pliku function.json .

Użyj zestawu SDK usługi Azure Service Bus, a nie wbudowanego powiązania wyjściowego.

Pełny przykład można znaleźć w sekcji przykłady.

Połączenia

Właściwość connection jest odwołaniem do konfiguracji środowiska, która określa sposób łączenia aplikacji z usługą Service Bus. Może to określać:

  • Nazwa ustawienia aplikacji zawierającego parametry połączenia
  • Nazwa udostępnionego prefiksu dla wielu ustawień aplikacji, definiująca połączenie oparte na tożsamościach.

Jeśli skonfigurowana wartość jest dokładnie zgodna z pojedynczym ustawieniem i dopasowaniem prefiksu dla innych ustawień, zostanie użyte dokładne dopasowanie.

Connection string

Aby uzyskać parametry połączenia, wykonaj kroki opisane w temacie Uzyskiwanie poświadczeń zarządzania. Parametry połączenia musi dotyczyć przestrzeni nazw usługi Service Bus, a nie tylko określonej kolejki lub tematu.

Ta parametry połączenia powinna być przechowywana w ustawieniu aplikacji z nazwą zgodną z wartością określoną przez connection właściwość konfiguracji powiązania.

Jeśli nazwa ustawienia aplikacji zaczyna się od "AzureWebJobs", możesz określić tylko pozostałą część nazwy. Jeśli na przykład ustawiono connection wartość "MyServiceBus", środowisko uruchomieniowe usługi Functions szuka ustawienia aplikacji o nazwie "AzureWebJobsMyServiceBus". W przypadku pozostawienia connection pustego środowisko uruchomieniowe usługi Functions używa domyślnej parametry połączenia usługi Service Bus w ustawieniu aplikacji o nazwie "AzureWebJobsServiceBus".

Połączenia oparte na tożsamościach

Jeśli używasz rozszerzenia w wersji 5.x lub nowszej, zamiast używać parametry połączenia z wpisem tajnym, możesz mieć aplikację korzystającą z tożsamości Microsoft Entra. W tym celu należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na connection właściwość w konfiguracji wyzwalacza i powiązania.

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

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
W pełni kwalifikowana przestrzeń nazw <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace W pełni kwalifikowana przestrzeń nazw usługi Service Bus. <>service_bus_namespace.servicebus.windows.net

Aby dostosować połączenie, można ustawić dodatkowe właściwości. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

Uwaga

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

Na przykład <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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ć.

Należy utworzyć przypisanie roli, które zapewnia dostęp do tematów i kolejek 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 Service Bus w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe role wbudowane
Wyzwalacz1 Odbiornik danych usługi Azure Service Bus, właściciel danych usługi Azure Service Bus
Powiązanie wyjściowe Nadawca danych usługi Azure Service Bus

1 W przypadku wyzwalania z tematów usługi Service Bus przypisanie roli musi mieć skuteczny zakres dla zasobu subskrypcji usługi Service Bus. Jeśli zostanie uwzględniony tylko temat, wystąpi błąd. Niektóre klienty, takie jak witryna Azure Portal, nie ujawniają zasobu subskrypcji usługi Service Bus jako zakresu dla przypisania roli. W takich przypadkach można użyć interfejsu wiersza polecenia platformy Azure. Aby dowiedzieć się więcej, zobacz Wbudowane role platformy Azure dla usługi Azure Service Bus.

Wyjątki i kody powrotne

Wiązanie Odwołanie
Service Bus Kody błędów usługi Service Bus
Service Bus Limity usługi Service Bus

Następne kroki