Udostępnij za pośrednictwem


Wyzwalacz usługi Azure Service Bus dla usługi Azure Functions

Użyj wyzwalacza usługi Service Bus, aby odpowiedzieć na komunikaty z kolejki lub tematu usługi Service Bus. Począwszy od rozszerzenia w wersji 3.1.0, można wyzwolić w kolejce lub temacie z włączoną sesją.

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

Decyzje dotyczące skalowania usługi Service Bus dla planów Zużycie i Premium są podejmowane na podstawie skalowania na podstawie celu. Aby uzyskać więcej informacji, zobacz Skalowanie na podstawie celu.

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 pojedynczy komunikat kolejki usługi Service Bus i zapisuje go w dziennikach:

[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 pokazano funkcję języka C#, która odbiera wiele komunikatów kolejki usługi Service Bus w jednej partii i zapisuje je w dziennikach:

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

W tym przykładzie pokazano funkcję języka C#, która odbiera wiele komunikatów kolejki usługi Service Bus, zapisuje je w dziennikach, a następnie rozlicza komunikat zgodnie z ukończeniem:

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

Poniższa funkcja Języka Java używa @ServiceBusQueueTrigger adnotacji z biblioteki środowiska uruchomieniowego funkcji Języka Java do opisania konfiguracji wyzwalacza kolejki usługi Service Bus. Funkcja pobiera komunikat umieszczony w kolejce i dodaje go do dzienników.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

Funkcje języka Java można również wyzwalać po dodaniu komunikatu do tematu usługi Service Bus. W poniższym przykładzie użyto @ServiceBusTopicTrigger adnotacji do opisania konfiguracji wyzwalacza.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalacza usługi Service Bus. Funkcja odczytuje metadane komunikatów i rejestruje komunikat kolejki usługi Service Bus.

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

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

W poniższym przykładzie przedstawiono funkcję JavaScript wyzwalacza usługi Service Bus. Funkcja odczytuje metadane komunikatów i rejestruje komunikat kolejki usługi Service Bus.

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

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

W poniższym przykładzie pokazano powiązanie wyzwalacza 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": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Oto funkcja uruchamiana po wysłaniu komunikatu usługi Service Bus.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

W poniższym przykładzie pokazano, jak odczytywać komunikat kolejki usługi Service Bus za pośrednictwem wyzwalacza. 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.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

W poniższym przykładzie pokazano, jak odczytać temat kolejki usługi Service Bus za pośrednictwem wyzwalacza.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

Atrybuty

Biblioteki języka C# procesu roboczego zarówno w procesie przetwarzania procesów procesowych, jak i izolowanych, używają atrybutu ServiceBusTriggerAttribute do zdefiniowania wyzwalacza funkcji. 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 poniższej tabeli opisano właściwości, które można ustawić przy użyciu tego atrybutu wyzwalacza:

Właściwości opis
QueueName Nazwa kolejki do monitorowania. Ustaw tylko wtedy, gdy monitorowanie kolejki, a nie tematu.
Nazwa tematu Nazwa tematu do monitorowania. Ustaw tylko wtedy, gdy monitorowanie tematu, a nie dla kolejki.
Nazwa subskrypcji Nazwa subskrypcji do monitorowania. Ustaw tylko wtedy, gdy monitorowanie 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.
IsBatched Komunikaty są dostarczane w partiach. Wymaga tablicy lub typu kolekcji.
IsSessionsEnabled truew przypadku nawiązywania połączenia z kolejką lub subskrypcją z obsługą sesji. false w przeciwnym razie jest to wartość domyślna.
AutouzupełnianieKomunikaty true jeśli wyzwalacz powinien automatycznie zakończyć komunikat po pomyślnym wywołaniu. false jeśli nie powinna, na przykład w przypadku obsługi rozliczenia komunikatów w kodzie. Jeśli nie zostanie jawnie ustawiona, zachowanie będzie oparte na konfiguracji w programie host.json.autoCompleteMessages

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

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_queue_trigger:

Właściwości opis
arg_name Nazwa zmiennej reprezentującej komunikat kolejki lub tematu w kodzie funkcji.
queue_name Nazwa kolejki do monitorowania. Ustaw tylko wtedy, gdy monitorowanie kolejki, a nie tematu.
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

Adnotacja ServiceBusQueueTrigger umożliwia utworzenie funkcji uruchamianej po utworzeniu komunikatu kolejki usługi Service Bus. Dostępne opcje konfiguracji obejmują następujące właściwości:

Właściwości Opis
name Nazwa zmiennej reprezentującej komunikat kolejki lub tematu w kodzie funkcji.
queueName Nazwa kolejki do monitorowania. Ustaw tylko wtedy, gdy monitorowanie kolejki, a nie tematu.
nazwa tematu Nazwa tematu do monitorowania. Ustaw tylko wtedy, gdy monitorowanie tematu, a nie dla kolejki.
subscriptionName Nazwa subskrypcji do monitorowania. Ustaw tylko wtedy, gdy monitorowanie 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.

Adnotacja ServiceBusTopicTrigger umożliwia wyznaczenie tematu i subskrypcji w celu określenia, które dane wyzwalają funkcję.

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

Zobacz przykład wyzwalacza, aby uzyskać więcej szczegółów.

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 app.serviceBusQueue() do metod lub app.serviceBusTopic() .

Właściwości opis
queueName Nazwa kolejki do monitorowania. Ustaw tylko wtedy, gdy monitorowanie kolejki, a nie tematu.
nazwa tematu Nazwa tematu do monitorowania. Ustaw tylko wtedy, gdy monitorowanie tematu, a nie dla kolejki.
subscriptionName Nazwa subskrypcji do monitorowania. Ustaw tylko wtedy, gdy monitorowanie 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 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.
isSessionsEnabled truew przypadku nawiązywania połączenia z kolejką lub subskrypcją z obsługą sesji. false w przeciwnym razie jest to wartość domyślna.
autouzupełnianie Musi być true w przypadku funkcji innych niż C#, co oznacza, że wyzwalacz powinien zostać automatycznie wywołany po zakończeniu przetwarzania lub ręcznie wywołania kodu funkcji.

Po ustawieniu truewartości wyzwalacz automatycznie kończy komunikat, jeśli wykonanie funkcji zakończy się pomyślnie i porzuci komunikat w przeciwnym razie.

Wyjątki w funkcji powoduje wywołania abandonAsync środowiska uruchomieniowego w tle. Jeśli nie wystąpi wyjątek, completeAsync wywołana jest w tle. Ta właściwość jest dostępna tylko w usłudze Azure Functions 2.x i nowszych.

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 .

właściwość function.json opis
type Musi być ustawiona wartość serviceBusTrigger. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
direction Musi być ustawiona wartość "in". 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.
queueName Nazwa kolejki do monitorowania. Ustaw tylko wtedy, gdy monitorowanie kolejki, a nie tematu.
nazwa tematu Nazwa tematu do monitorowania. Ustaw tylko wtedy, gdy monitorowanie tematu, a nie dla kolejki.
subscriptionName Nazwa subskrypcji do monitorowania. Ustaw tylko wtedy, gdy monitorowanie 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 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.
isSessionsEnabled truew przypadku nawiązywania połączenia z kolejką lub subskrypcją z obsługą sesji. false w przeciwnym razie jest to wartość domyślna.
autouzupełnianie Musi być true w przypadku funkcji innych niż C#, co oznacza, że wyzwalacz powinien zostać automatycznie wywołany po zakończeniu przetwarzania lub ręcznie wywołania kodu funkcji.

Po ustawieniu truewartości wyzwalacz automatycznie kończy komunikat, jeśli wykonanie funkcji zakończy się pomyślnie i porzuci komunikat w przeciwnym razie.

Wyjątki w funkcji powoduje wywołania abandonAsync środowiska uruchomieniowego w tle. Jeśli nie wystąpi wyjątek, completeAsync wywołana jest w tle. Ta właściwość jest dostępna tylko w usłudze Azure Functions 2.x i nowszych.

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

Następujące typy parametrów są obsługiwane przez wszystkie modalności i wersje rozszerzeń języka C#:

Type Opis
System.String Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Służy do obsługi komunikatów danych binarnych.
Obiekt Gdy komunikat zawiera kod JSON, usługa Functions próbuje wykonać deserializacji danych JSON do znanego zwykłego typu obiektu CLR.

Typy parametrów specyficznych dla komunikatów zawierają dodatkowe metadane komunikatów. Określone typy obsługiwane przez wyzwalacz usługi Service Bus zależą od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Jeśli chcesz, aby funkcja przetwarzała pojedynczy komunikat, wyzwalacz usługi Service Bus może powiązać 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 Gdy zdarzenie zawiera dane JSON, usługa Functions próbuje wykonać deserializacji danych JSON w zwykły typ obiektu CLR (POCO).
ServiceBusReceivedMessage1 Obiekt komunikatu.

W przypadku powiązania z ServiceBusReceivedMessageusługą można również opcjonalnie dołączyć parametr typu ServiceBusMessageActions 1,2, aby wykonać akcje rozliczenia komunikatów.

Jeśli chcesz, aby funkcja przetwarzała partię komunikatów, wyzwalacz usługi Service Bus może powiązać z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów pojedynczych komunikatów Tablica zdarzeń z partii. Każdy wpis reprezentuje jedno zdarzenie.

W przypadku powiązania z ServiceBusReceivedMessage[]usługą można również opcjonalnie dołączyć parametr typu ServiceBusMessageActions 1,2, aby wykonać akcje rozliczenia komunikatów.

1 Aby użyć tych typów, należy odwołać się do elementów Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 lub nowszych oraz typowych zależności dla powiązań typu zestawu SDK.

2 W przypadku używania ServiceBusMessageActionsparametru ustaw AutoCompleteMessages właściwość atrybutu wyzwalacza na falsewartość . Zapobiega to próbie ukończenia komunikatów przez środowisko uruchomieniowe po pomyślnym wywołaniu funkcji.

Connection Gdy właściwość nie jest zdefiniowana, usługa Functions szuka ustawienia aplikacji o nazwie AzureWebJobsServiceBus, które jest domyślną nazwą parametry połączenia usługi Service Bus. Można również ustawić Connection właściwość , aby określić nazwę ustawienia aplikacji, które zawiera parametry połączenia usługi Service Bus.

Przychodzący komunikat usługi Service Bus jest dostępny za pośrednictwem parametru ServiceBusQueueMessage lub ServiceBusTopicMessage .

Uzyskaj dostęp do komunikatu kolejki lub tematu jako pierwszego argumentu funkcji. Komunikat usługi Service Bus jest przekazywany do funkcji jako ciąg lub obiekt JSON.

Wystąpienie usługi Service Bus jest dostępne za pośrednictwem parametru skonfigurowanego we właściwości nazwy pliku function.json .

Komunikat kolejki jest dostępny dla funkcji za pośrednictwem parametru wpisanego jako func.ServiceBusMessage. Komunikat usługi Service Bus jest przekazywany do funkcji jako ciąg lub obiekt JSON.

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.

Komunikaty o truciznach

Nie można kontrolować ani konfigurować obsługi komunikatów zatrutych w usłudze Azure Functions. Usługa Service Bus obsługuje same komunikaty zatrute.

Zachowanie PeekLock

Środowisko uruchomieniowe usługi Functions odbiera komunikat w trybie PeekLock.

Domyślnie środowisko uruchomieniowe wywołuje Complete komunikat, jeśli funkcja zakończy się pomyślnie lub wywołuje Abandon funkcję, jeśli funkcja zakończy się niepowodzeniem. Automatyczne uzupełnianie można wyłączyć za autoCompleteMessages pomocą właściwości w pliku host.json.

Domyślnie środowisko uruchomieniowe wywołuje Complete komunikat, jeśli funkcja zakończy się pomyślnie lub wywołuje Abandon funkcję, jeśli funkcja zakończy się niepowodzeniem. Automatyczne uzupełnianie można wyłączyć za pomocą autoCompleteMessages właściwości w host.json obiekcie lub za pomocą właściwości w atrybucie wyzwalacza. Jeśli kod funkcji obsługuje rozliczenia komunikatów, należy wyłączyć automatyczne uzupełnianie.

Jeśli funkcja działa dłużej niż PeekLock limit czasu, blokada zostanie automatycznie odnowiona, o ile funkcja jest uruchomiona. Element maxAutoRenewDuration jest konfigurowalny w host.json, który jest mapowany na serviceBusProcessor.MaxAutoLockRenewalDuration. Wartość domyślna tego ustawienia to 5 minut.

Metadane komunikatu

Typy specyficzne dla komunikatów umożliwiają łatwe pobieranie metadanych jako właściwości obiektu. Te właściwości zależą od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Te właściwości są elementami członkowskimi klasy ServiceBusReceivedMessage .

Właściwość Type Opis
ApplicationProperties ApplicationProperties Właściwości ustawione przez nadawcę.
ContentType string Identyfikator typu zawartości używany przez nadawcę i odbiorcę dla logiki specyficznej dla aplikacji.
CorrelationId string Identyfikator korelacji.
DeliveryCount Int32 Liczba dostaw.
EnqueuedTime DateTime Czas w kolejce w formacie UTC.
ScheduledEnqueueTimeUtc DateTime Zaplanowany czas w kolejce w formacie UTC.
ExpiresAt DateTime Czas wygaśnięcia w formacie UTC.
MessageId string Wartość zdefiniowana przez użytkownika, która może być używana przez usługę Service Bus do identyfikowania zduplikowanych komunikatów, jeśli jest włączona.
ReplyTo string Odpowiedź na adres kolejki.
Subject string Etykieta specyficzna dla aplikacji, która może być używana zamiast Label właściwości metadanych.
To string Adres wysyłania.

Następne kroki