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

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

Wsparcie Go nie jest obecnie dostępne dla tego przypisania.

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(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([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}"};

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

    // Queue Output messages
    return messages;
}

Aby zapoznać się z kompleksowego przykładu konfigurowania powiązania wyjściowego z usługą Queue Storage, zobacz jeden z następujących artykułów:

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

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.

Aby zapoznać się z kompleksowego przykładu konfigurowania powiązania wyjściowego z usługą Queue Storage, zobacz jeden z następujących artykułów:

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']);

Aby zapoznać się z kompleksowego przykładu konfigurowania powiązania wyjściowego z usługą Queue Storage, zobacz jeden z następujących artykułów:

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

Aby zapoznać się z kompleksowego przykładu konfigurowania powiązania wyjściowego z usługą Queue Storage, zobacz jeden z następujących artykułów:

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'

Aby zapoznać się z kompleksowego przykładu konfigurowania powiązania wyjściowego z usługą Queue Storage, zobacz jeden z następujących artykułów:

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(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([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łączenia.

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łączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kolejkami platformy Azure. 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 .

właściwość function.json opis
typ Musi być ustawiona wartość queue. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
kierunek Musi być ustawiona wartość out. Ta właściwość jest ustawiana automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
nazwa 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łączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kolejkami platformy Azure. Zobacz Połączenia.

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:

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

Typ 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 obiekt QueueClient i użyj go bezpośrednio z innymi typami z witryny Azure.Storage.Queues. 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.

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.

Parametr funkcji wyjściowej musi być zdefiniowany jako func.Out[func.QueueMessage], func.Out[str]lub func.Out[bytes]. Szczegółowe informacje można znaleźć w przykładzie danych wyjściowych .

Połączenia

Właściwość jest connection ustawiona na klucz w ustawieniach aplikacji, który zwraca wartość używaną przez środowisko wykonawcze Functions do połączenia z kontem pamięci masowej używanym przez rozszerzenie. Wartość ustawienia właściwości połączenia zależy od typu połączenia:

  • Połączenie zarządzanej tożsamości: Właściwość connection jest współdzielona <CONNECTION_NAME_PREFIX> przez grupę ustawień, które razem definiują połączenie oparte na tożsamości z kontem pamięci masowej. Więcej informacji można znaleźć w artykule Definiuj powiązania tożsamości.
  • Key Vault reference: Ustawienie connection właściwości zwraca referencję Azure Key Vault do miejsca, gdzie centralnie utrzymywany jest parametry połączenia. Więcej informacji można znaleźć w artykule Definiuj połączenia Key Vault.
  • Referencja konfiguracji aplikacji: Ustawienie connection właściwości zwraca referencję Azure App Configuration, która zwraca parametry połączenia lub referencję Key Vault. Więcej informacji można znaleźć w artykule o połączeniach w sekcji Azure App Configuration.
  • Connection string: Ustawienie connection właściwości zwraca rzeczywisty parametry połączenia konta pamięci. Ponieważ parametry połączenia zawiera wspólne klucze tajne, warto rozważyć użycie połączenia z zarządzaną tożsamością, jeśli to możliwe. Więcej informacji można znaleźć w artykule Definiuj połączenia.

Aby dowiedzieć się więcej o powiązaniach wiązanych, zobacz Zarządzanie połączeniem w Azure Functions. Aby uzyskać parametry połączenia, wykonaj kroki opisane w temacie Zarządzanie kluczami dostępu do konta magazynu.

Gdy ustawisz connection klucz lub prefiks klucza o nazwie AzureWebJobsStorage albo pusty ciąg znaków, rozszerzenie wiązania korzysta z domyślnego konta hosta. Więcej informacji można znaleźć w artykule Optymalizacja wydajności pamięci masowej.

Wyjątki i kody powrotne

Wiązanie Odwołanie
Kolejka 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

  • Last updated on