Powiązania wyjściowe usługi Azure Queue Storage dla usługi Azure Functions

  • Artykuł

Usługa Azure Functions może tworzyć nowe komunikaty usługi Azure Queue Storage, konfigurując powiązanie wyjściowe.

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.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

W poniższym przykładzie pokazano funkcję Języka Java, która tworzy komunikat kolejki dla elementu po wyzwoleniu przez żądanie HTTP.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @QueueOutput adnotacji parametrów, których wartość zostanie zapisana w usłudze Queue Storage. Typ parametru powinien mieć OutputBinding<T>wartość , gdzie T jest dowolnym natywnym typem java poJO.

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalaną przez protokół HTTP, która tworzy element kolejki dla każdego odebranego żądania HTTP.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

W poniższym przykładzie pokazano funkcję JavaScript wyzwalaną przez protokół HTTP, która tworzy element kolejki dla każdego odebranego żądania HTTP.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

W poniższych przykładach kodu pokazano, jak wygenerować komunikat kolejki z funkcji wyzwalanej przez protokół HTTP. Sekcja konfiguracji z typequeue definicją powiązania wyjściowego.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Korzystając z tej konfiguracji powiązania, funkcja programu PowerShell może utworzyć komunikat kolejki przy użyciu polecenia Push-OutputBinding. W tym przykładzie komunikat jest tworzony na podstawie ciągu zapytania lub parametru treści.

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 Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Aby wysyłać wiele komunikatów jednocześnie, zdefiniuj tablicę komunikatów i użyj polecenia Push-OutputBinding do wysyłania komunikatów do powiązania wyjściowego kolejki.

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 = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Poniższy przykład przedstawia sposób wyprowadzania pojedynczych i wielu wartości do kolejek magazynu. Konfiguracja wymagana do function.json jest taka sama. 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="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Atrybuty

Atrybut definiujący powiązanie wyjściowe w bibliotekach języka C# zależy od trybu, w którym jest uruchamiana biblioteka klas języka C#.

Podczas uruchamiania w izolowanym procesie roboczym należy użyć atrybutu QueueOutputAttribute, który przyjmuje nazwę kolejki, jak pokazano w poniższym przykładzie:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Zwracane zmienne są obsługiwane tylko w przypadku uruchamiania w izolowanym procesie roboczym. Nie można używać parametrów wyjściowych.

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

Właściwości opis
arg_name Nazwa zmiennej reprezentującej kolejkę w kodzie funkcji.
queue_name Nazwa kolejki.
connection Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kolejkami platformy Azure. Zobacz Połączenie ions.

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

Adnotacje

Adnotacja QueueOutput umożliwia zapisanie komunikatu jako danych wyjściowych funkcji. W poniższym przykładzie pokazano funkcję wyzwalaną przez protokół HTTP, która tworzy komunikat kolejki.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Właściwości opis
name Deklaruje nazwę parametru w podpisie funkcji. Po wyzwoleniu funkcji wartość tego parametru zawiera zawartość komunikatu kolejki.
queueName Deklaruje nazwę kolejki na koncie magazynu.
connection Wskazuje parametry połączenia konta magazynu.

Parametr skojarzony z adnotacją QueueOutput jest wpisany jako wystąpienie outputBinding<T> .

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.storageQueue() do metody .

Właściwości opis
Queuename Nazwa kolejki.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kolejkami platformy Azure. Zobacz Połączenie ions.

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ść queue. 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 kolejkę w kodzie funkcji. Ustaw wartość na , aby $return odwoływać się do wartości zwracanej przez funkcję.
Queuename Nazwa kolejki.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kolejkami platformy Azure. Zobacz Połączenie ions.

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

Użycie powiązania wyjściowego kolejki zależy od wersji pakietu rozszerzenia i modalności języka C# używanej w aplikacji funkcji, co może być jednym z następujących elementów:

Izolowana biblioteka klas procesów roboczych skompilowana funkcja języka C# jest uruchamiana w procesie odizolowanym od środowiska uruchomieniowego.

Wybierz wersję, aby wyświetlić szczegóły użycia dla trybu i wersji.

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

Type Opis
string Zawartość wiadomości jako ciąg. Użyj polecenia , gdy wiadomość jest prostym tekstem.
byte[] Bajty komunikatu.
Typy serializowalne w formacie JSON Obiekt reprezentujący zawartość komunikatu JSON. 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 kolejki 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 zawartość dla wielu komunikatów. Każdy wpis reprezentuje jeden komunikat.

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

Istnieją dwie opcje zapisywania w kolejce z funkcji przy użyciu adnotacji QueueOutput :

  • Wartość zwracana: stosując adnotację do samej funkcji, zwracana wartość funkcji jest zapisywana w kolejce.

  • Imperatywne: Aby jawnie ustawić wartość komunikatu, zastosuj adnotację do określonego parametru typu OutputBinding<T>, gdzie T jest poJO lub dowolnym natywnym typem języka Java. W przypadku tej konfiguracji przekazanie wartości do setValue metody powoduje zapisanie wartości w kolejce.

Uzyskaj dostęp do elementu kolejki wyjściowej, zwracając wartość bezpośrednio lub przy użyciu polecenia context.extraOutputs.set(). Dla ładunku elementu kolejki można użyć ciągu lub obiektu z możliwością serializacji JSON.

Dane wyjściowe komunikatu kolejki są dostępne za pośrednictwem Push-OutputBinding lokalizacji, w której przekazuje się argumenty zgodne z nazwą wyznaczoną przez parametr powiązania name w pliku function.json .

Istnieją dwie opcje zapisu z funkcji do skonfigurowanej kolejki:

  • Wartość zwracana name : ustaw właściwość w function.json na $returnwartość . W przypadku tej konfiguracji zwracana wartość funkcji jest utrwalana jako komunikat usługi Queue Storage.

  • Imperatywne: przekaż wartość do metody set parametru zadeklarowanego jako typ out . Przekazana wartość jest utrwalana set jako komunikat usługi Queue Storage.

Połączenia

Właściwość connection jest odwołaniem do konfiguracji środowiska, która określa sposób łączenia aplikacji z kolejkami platformy Azure. 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 Zarządzanie kluczami dostępu do konta magazynu.

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 w tym miejscu. Jeśli na przykład ustawiono connection wartość "MyStorage", środowisko uruchomieniowe usługi Functions wyszukuje ustawienie aplikacji o nazwie "AzureWebJobsMyStorage". W przypadku pozostawienia connection pustego środowisko uruchomieniowe usługi Functions używa domyślnej parametry połączenia Storage w ustawieniu aplikacji o nazwie AzureWebJobsStorage.

Połączenia oparte na tożsamościach

Jeśli używasz wersji 5.x lub nowszej rozszerzenia (pakietu 3.x lub nowszego dla stosów języka non-.NET), zamiast używać parametry połączenia z wpisem tajnym, możesz mieć aplikację korzystającą z tożsamości Microsoft Entra. Aby użyć tożsamości, należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na connection właściwość w konfiguracji wyzwalacza i powiązania.

Jeśli ustawisz wartość connection "AzureWebJobsStorage", zobacz Połączenie do hostowania magazynu z tożsamością. W przypadku wszystkich innych połączeń rozszerzenie wymaga następujących właściwości:

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
Identyfikator URI usługi kolejki <CONNECTION_NAME_PREFIX>__queueServiceUri1 Identyfikator URI płaszczyzny danych usługi kolejki, z którą nawiązujesz połączenie, przy użyciu schematu HTTPS. <https:// storage_account_name.queue.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri może służyć jako alias. Jeśli podano oba formularze, queueServiceUri zostanie użyty formularz. Nie serviceUri można użyć formularza, gdy ogólna konfiguracja połączenia ma być używana w obiektach blob, kolejkach i/lub tabelach.

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

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 kolejki 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 Queue Storage w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe role wbudowane
Wyzwalacz Czytelnik danych kolejki usługi Storage, procesor komunikatów kolejki magazynu
Powiązanie wyjściowe Współautor danych kolejki usługi Storage, nadawca komunikatów dotyczących kolejki magazynu

Wyjątki i kody powrotne

Wiązanie Odwołanie
Queue Kody błędów kolejki
Obiekt blob, tabela, kolejka Kody błędów magazynu
Obiekt blob, tabela, kolejka Rozwiązywanie problemów

Następne kroki