Azure Queue Storage-uitvoerbindingen voor Azure Functions

Artikel
10/14/2021
11 minuten om te lezen

Azure Functions kunt nieuwe Azure Queue Storage-berichten maken door een uitvoerbinding in te stellen.

Zie het overzicht voor meer informatie over de installatie- en configuratiegegevens.

Voorbeeld

In het volgende voorbeeld ziet u een C#-functie die een wachtrijbericht maakt voor elke ontvangen HTTP-aanvraag.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

In het volgende voorbeeld ziet u een HTTP-triggerbinding in een function.json-bestand en C#-scriptcode (.csx) die gebruikmaakt van de binding. De functie maakt een wachtrij-item met een CustomQueueMessage-objectnlading voor elke ontvangen HTTP-aanvraag.

Dit is het bestand function.json:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

In de configuratiesectie worden deze eigenschappen uitgelegd.

Dit is de C#-scriptcode die één wachtrijbericht maakt:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

U kunt meerdere berichten tegelijk verzenden met behulp van een ICollector parameter of IAsyncCollector . Hier is een C#-scriptcode die meerdere berichten verzendt, één met de HTTP-aanvraaggegevens en één met in code gecodeerde waarden:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

In het volgende voorbeeld ziet u een Java-functie die een wachtrijbericht maakt voor wanneer deze wordt geactiveerd door een HTTP-aanvraag.

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

Gebruik in de Java Functions-runtimebibliotheekde aantekening voor parameters waarvan de waarde @QueueOutput naar Queue Storage wordt geschreven. Het parametertype moet OutputBinding<T> zijn, waarbij T elk native Java-type van een POJO is.

In het volgende voorbeeld ziet u een HTTP-triggerbinding in een function.json-bestand en een JavaScript-functie die gebruikmaakt van de binding. De functie maakt een wachtrij-item voor elke ontvangen HTTP-aanvraag.

Dit is het bestand function.json:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

In de configuratiesectie worden deze eigenschappen uitgelegd.

Dit is de JavaScript-code:

module.exports = function (context, input) {
    context.bindings.myQueueItem = input.body;
    context.done();
};

U kunt meerdere berichten tegelijk verzenden door een berichten array voor de myQueueItem uitvoerbinding te definiëren. Met de volgende JavaScript-code worden twee wachtrijberichten met in code gecodeerde waarden verzonden voor elke ontvangen HTTP-aanvraag.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

In de volgende codevoorbeelden wordt gedemonstreerd hoe u een wachtrijbericht uit een door HTTP geactiveerde functie kunt uitvoeren. De configuratiesectie met de type van queue definieert de uitvoerbinding.

{
  "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"
    }
  ]
}

Met behulp van deze bindingsconfiguratie kan een PowerShell-functie een wachtrijbericht maken met behulp van Push-OutputBinding . In dit voorbeeld wordt een bericht gemaakt van een queryreeks of bodyparameter.

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

Als u meerdere berichten tegelijk wilt verzenden, definieert u een berichten array en gebruikt u om Push-OutputBinding berichten te verzenden naar de queue-uitvoerbinding.

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

In het volgende voorbeeld wordt gedemonstreerd hoe u enkele en meerdere waarden naar opslagwachtrijen kunt uitvoer. De configuratie die nodig is voor function.json, is in beide beide kanten hetzelfde.

Een Storage wachtrijbinding wordt gedefinieerd in function.json, waarbij type is ingesteld op queue .

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Als u een afzonderlijk bericht in de wachtrij wilt instellen, moet u één waarde doorgeven aan de set methode .

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Als u meerdere berichten in de wachtrij wilt maken, declareert u een parameter als het juiste lijsttype en geeft u een matrix met waarden (die overeenkomen met het lijsttype) door aan de set methode .

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Kenmerken en aantekeningen

Gebruik in C#-klassebibliotheken queueAttribute.

Het kenmerk is van toepassing op out een parameter of de retourwaarde van de functie. De constructor van het kenmerk neemt de naam van de wachtrij, zoals wordt weergegeven in het volgende voorbeeld:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

U kunt de eigenschap instellen om het opslagaccount op te geven dat moet worden Connection gebruikt, zoals wordt weergegeven in het volgende voorbeeld:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Zie Uitvoervoorbeeld voor een volledig voorbeeld.

U kunt het kenmerk StorageAccount gebruiken om het opslagaccount op klasse-, methode- of parameterniveau op te geven. Zie Trigger - kenmerken voor meer informatie.

Met QueueOutput de aantekening kunt u een bericht schrijven als uitvoer van een functie. In het volgende voorbeeld ziet u een http-geactiveerde functie die een wachtrijbericht maakt.

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

Eigenschap	Beschrijving
`name`	Declareer de parameternaam in de functiehandtekening. Wanneer de functie wordt geactiveerd, bevat de waarde van deze parameter de inhoud van het wachtrijbericht.
`queueName`	Declareer de naam van de wachtrij in het opslagaccount.
`connection`	Wijst naar het opslagaccount connection string.

De parameter die is gekoppeld aan QueueOutput de aantekening, wordt getypt als een <T> OutputBinding-exemplaar.

Configuratie

De volgende tabel bevat informatie over de bindingsconfiguratie-eigenschappen die u instelt in het bestand function.json en het kenmerk Queue.

function.json-eigenschap	Kenmerkeigenschap	Beschrijving
type	N.v.t.	Moet worden ingesteld op `queue`. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
direction	N.v.t.	Moet worden ingesteld op `out`. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
name	N.v.t.	De naam van de variabele die de wachtrij in functiecode vertegenwoordigt. Stel in op `$return` om te verwijzen naar de retourwaarde van de functie.
queueName	QueueName	De naam van de wachtrij.
connection	Verbinding	De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden maken met Azure Queues. Zie Verbindingen.

Wanneer u lokaal ontwikkelt, gaan app-instellingen in het bestand local.settings.json.

Verbindingen

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Azure Queues. Er kan het volgende worden opgegeven:

De naam van een toepassingsinstelling met een connection string
De naam van een gedeeld voorvoegsel voor meerdere toepassingsinstellingen, samen met het definiëren van een verbinding op basis van identiteit.

Als de geconfigureerde waarde zowel een exacte overeenkomst voor één instelling als een overeenkomend voorvoegsel voor andere instellingen is, wordt de exacte overeenkomst gebruikt.

Verbindingsreeks

Als u een connection string, volgt u de stappen in Toegangssleutels voor opslagaccount beheren.

Deze connection string moeten worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de connection eigenschap van de bindingsconfiguratie.

Als de naam van de app-instelling begint met 'AzureWebJobs', kunt u hier alleen de rest van de naam opgeven. Als u bijvoorbeeld instelt op 'MyStorage', zoekt de Functions-runtime naar een app-instelling met de naam connection 'AzureWebJobsMyStorage'. Als u leeg connection laat, gebruikt de Functions-runtime de standaardinstelling Storage connection string in de app-instelling met de naam AzureWebJobsStorage .

Op identiteit gebaseerde verbindingen

Als u versie 5.x ofhoger van de extensie gebruikt in plaats van een connection string met een geheim, kunt u de app een Azure Active Directory laten gebruiken. Hiervoor definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toe te staan aan de eigenschap in de connection trigger en bindingsconfiguratie.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschap	Sjabloon voor omgevingsvariabelen	Beschrijving	Voorbeeldwaarde
Queue Service URI	`<CONNECTION_NAME_PREFIX>__queueServiceUri`¹	De gegevensvlak-URI van de wachtrijservice waarmee u verbinding maakt, met behulp van het HTTPS-schema.	https://<storage_account_name>.queue.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__serviceUri kan worden gebruikt als alias. Als beide formulieren worden opgegeven, queueServiceUri wordt het formulier gebruikt. Het serviceUri formulier kan niet worden gebruikt wanneer de algehele verbindingsconfiguratie moet worden gebruikt in blobs, wachtrijen en/of tabellen.

Er kunnen extra eigenschappen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Wanneer deze worden gehost in Azure Functions-service, gebruiken identiteitsgebaseerde verbindingen een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential eigenschappen clientID en . Wanneer deze wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw identiteit van de ontwikkelaar gebruikt, hoewel dit kan worden aangepast. Zie Local development with identity-based connections(Lokale ontwikkeling met op identiteit gebaseerde verbindingen).

Machtiging verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. U moet een rol toewijzen in Azure RBACmet behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen kunnen worden blootgesteld door de doelservice die niet nodig zijn voor alle contexten. Waar mogelijk moet u zich houden aan het principe van de minste bevoegdheden en de identiteit alleen bevoegdheden verlenen. Als de app bijvoorbeeld alleen gegevens uit een gegevensbron hoeft te kunnen lezen, gebruikt u een rol die alleen machtigingen heeft om te lezen. Het zou ongepast zijn om een rol toe te wijzen waarmee ook naar die service kan worden geschreven, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u er zeker van zijn dat de roltoewijzing alleen wordt beperkt tot de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw wachtrij. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen wanneer u de Queue Storage-extensie in normale werking gebruikt. Uw toepassing heeft mogelijk extra machtigingen nodig op basis van de code die u schrijft.

Bindingstype	Voorbeeld van ingebouwde rollen
Trigger	[Storage Queue Data Reader ,]Storage Queue Data Message [Processor]
Uitvoerbinding	[Storage Inzender voor wachtrijgegevens,] [Storage afzender van wachtrijgegevens]

Gebruik

Standaard

Schrijf één wachtrijbericht met behulp van een methodeparameter zoals out T paramName . U kunt het retourtype van de methode gebruiken in plaats van een out parameter en kan een van de volgende typen T zijn:

Een object dat kan worden geser serializeerbaar als JSON
string
byte[]
CloudQueueMessage

Als u probeert te verbinden met en een foutbericht krijgt, zorg er dan voor dat u een verwijzing hebt naar de CloudQueueMessage juiste Storage SDK-versie.

In C# en C#-script schrijft u meerdere wachtrijberichten met behulp van een van de volgende typen:

ICollector<T> of IAsyncCollector<T>
CloudQueue

Aanvullende typen

Apps met de versie 5.0.0 of hoger van de Storage-extensie kunnen ook typen uit de Azure SDK voor .NET gebruiken. Met deze versie wordt de ondersteuning voor de verouderde CloudQueue en typen in de voorkeur van de volgende typen CloudQueueMessage wegvalt:

QueueMessage
QueueClient voor het schrijven van meerdere wachtrijberichten

Zie de opslagplaats GitHub voor de extensie voor voorbeelden van deze typen.

Standaard

Schrijf één wachtrijbericht met behulp van een methodeparameter zoals out T paramName . De paramName is de waarde die is opgegeven in de eigenschap van name function.json. U kunt het retourtype van de methode gebruiken in plaats van een out parameter en kan een van de volgende typen T zijn:

Een object dat kan worden geser serializeerbaar als JSON
string
byte[]
CloudQueueMessage

Als u probeert te binden aan en een foutbericht krijgt, zorg er dan voor dat u een verwijzing hebt naar de CloudQueueMessage juiste Storage SDK-versie.

In C# en C#-script schrijft u meerdere wachtrijberichten met behulp van een van de volgende typen:

ICollector<T> of IAsyncCollector<T>
CloudQueue

Aanvullende typen

QueueMessage
QueueClient voor het schrijven van meerdere wachtrijberichten

Zie de opslagplaats GitHub voor de extensie voor voorbeelden van deze typen.

Er zijn twee opties voor het uitvoeren van een wachtrijbericht van een functie met behulp van de aantekening QueueOutput:

Retourwaarde: door de aantekening toe te passen op de functie zelf, wordt de retourwaarde van de functie persistent gemaakt als een wachtrijbericht.
Imperatief: Als u de berichtwaarde expliciet wilt instellen, past u de aantekening toe op een specifieke parameter van het type OutputBinding<T>, waarbij T een POJO of een systeemeigen Java-type is. Met deze configuratie wordt de waarde als wachtrijbericht persistent door een waarde setValue door te geven aan de methode.

Er zijn twee opties voor het uitvoeren van een wachtrijbericht van een functie:

Retourwaarde: stel de eigenschap name in function. json in op $return. Met deze configuratie wordt de retourwaarde van de functie persistent als een Queue Storage-bericht.
Imperatief: geef een waarde door aan de methode set voor de parameter die is gedeclareerd als een type Out. De waarde die wordt doorgegeven set aan wordt persistent als een Queue Storage-bericht.

Uitzonderingen en retourcodes

Binding	Referentie
Wachtrij	Wachtrijfoutcodes
Blob, Tabel, Wachtrij	Storage Foutcodes
Blob, Tabel, Wachtrij	Problemen oplossen

Volgende stappen

Een functie uitvoeren als gegevenswijzigingen in de wachtrijopslag (trigger)

Azure Queue Storage-uitvoerbindingen voor Azure Functions

Beoordeel uw ervaring

Voorbeeld

Kenmerken en aantekeningen

Configuratie

Verbindingen

Verbindingsreeks

Op identiteit gebaseerde verbindingen

Machtiging verlenen aan de identiteit

Gebruik

Standaard

Aanvullende typen

Uitzonderingen en retourcodes

Volgende stappen