Invoerbinding voor Azure Blob Storage voor Azure Functions

Met de invoerbinding kunt u blobopslaggegevens lezen als invoer voor een Azure-functie.

Zie het overzicht voor informatie over het instellen en configureren van details.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

U kunt een C#-functie maken met behulp van een van de volgende C#-modi:

  • Geïsoleerd werkrolmodel: gecompileerde C#-functie die wordt uitgevoerd in een werkproces dat is geïsoleerd van de runtime. Geïsoleerd werkproces is vereist voor de ondersteuning van C#-functies die worden uitgevoerd op LTS- en niet-LTS-versies .NET en .NET Framework. Extensies voor geïsoleerde werkprocesfuncties maken gebruik van Microsoft.Azure.Functions.Worker.Extensions.* naamruimten.
  • In-process model: gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime. In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Extensies voor in-process-functies maken gebruik van Microsoft.Azure.WebJobs.Extensions.* naamruimten.

Het volgende voorbeeld is een C#-functie die wordt uitgevoerd in een geïsoleerd werkproces en een blobtrigger gebruikt met zowel blob-invoer- als blobuitvoer-blobbindingen. De functie wordt geactiveerd door het maken van een blob in de container test-samples-trigger . Het leest een tekstbestand uit de test-samples-invoercontainer en maakt een nieuw tekstbestand in een uitvoercontainer op basis van de naam van het geactiveerde bestand.

    public static class BlobFunction
    {
        [Function(nameof(BlobFunction))]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
            logger.LogInformation("Input Item = {myBlob}", myBlob);

            // Blob Output
            return "blob-output content";
        }
    }
}

Deze sectie bevat de volgende voorbeelden:

HTTP-trigger, blobnaam opzoeken uit querytekenreeks

In het volgende voorbeeld ziet u een Java-functie die gebruikmaakt van de HttpTrigger aantekening om een parameter te ontvangen die de naam van een bestand in een blob-opslagcontainer bevat. De BlobInput aantekening leest vervolgens het bestand en geeft de inhoud door aan de functie als een byte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

Wachtrijtrigger, blobnaam ontvangen van wachtrijbericht

In het volgende voorbeeld ziet u een Java-functie die gebruikmaakt van de QueueTrigger aantekening om een bericht te ontvangen met de naam van een bestand in een blobopslagcontainer. De BlobInput aantekening leest vervolgens het bestand en geeft de inhoud door aan de functie als een byte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

Gebruik in de Runtime-bibliotheek van Java-functies de @BlobInput aantekening voor parameters waarvan de waarde afkomstig is van een blob. Deze aantekening kan worden gebruikt met systeemeigen Java-typen, POJO's of nullbare waarden met Optional<T>.

In het volgende voorbeeld ziet u een door de wachtrij geactiveerde TypeScript-functie waarmee een kopie van een blob wordt gemaakt. De functie wordt geactiveerd door een wachtrijbericht dat de naam van de blob bevat die moet worden gekopieerd. De nieuwe blob heeft de naam {originalblobname}-Copy.

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

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

In het volgende voorbeeld ziet u een door een wachtrij geactiveerde JavaScript-functie waarmee een kopie van een blob wordt gemaakt. De functie wordt geactiveerd door een wachtrijbericht dat de naam van de blob bevat die moet worden gekopieerd. De nieuwe blob heeft de naam {originalblobname}-Copy.

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

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

In het volgende voorbeeld ziet u een blobinvoerbinding die is gedefinieerd in het function.json-bestand , waardoor de binnenkomende blobgegevens beschikbaar zijn voor de PowerShell-functie .

Dit is de json-configuratie:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Dit is de functiecode:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

In het volgende voorbeeld ziet u blobinvoer- en uitvoerbindingen. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

Met de code wordt een kopie van een blob gemaakt.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

Kenmerken

Zowel in-processals geïsoleerde werkproces C#-bibliotheken gebruiken kenmerken om de functie te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

geïsoleerd werkproces definieert een invoerbinding met behulp van een BlobInputAttribute kenmerk, waarbij de volgende parameters worden gebruikt:

Parameter Description
BlobPath Het pad naar de blob.
Verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Blobs. Zie Verbinding maken ions.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met decorators, definiëren de volgende eigenschappen op de blob_input en blob_output decorators de Blob Storage-triggers:

Eigenschappen Beschrijving
arg_name De naam van de variabele die de blob in functiecode vertegenwoordigt.
path Het pad naar de blob voor de blob_input decorator is de blob gelezen. Voor de blob_output decorator is dit de uitvoer of kopie van de invoerblob.
connection De verbindingsreeks van het opslagaccount.
data_type Voor dynamisch getypte talen geeft u het onderliggende gegevenstype op. Mogelijke waarden zijn string, binaryof stream. Raadpleeg de concepten voor triggers en bindingen voor meer informatie.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Het @BlobInput kenmerk geeft u toegang tot de blob die de functie heeft geactiveerd. Als u een bytematrix gebruikt met het kenmerk, stelt u deze in dataType op binary. Raadpleeg het invoervoorbeeld voor meer informatie.

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de input.storageBlob() methode is doorgegeven.

Eigenschappen Beschrijving
path Het pad naar de blob.
verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Blobs. Zie Verbinding maken ions.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op blob.
direction Moet worden ingesteld op in. Uitzonderingen worden vermeld in de sectie Gebruik .
name De naam van de variabele die de blob in functiecode vertegenwoordigt.
path Het pad naar de blob.
verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Blobs. Zie Verbinding maken ions.
Datatype Voor dynamisch getypte talen geeft u het onderliggende gegevenstype op. Mogelijke waarden zijn string, binaryof stream. Raadpleeg de concepten voor triggers en bindingen voor meer informatie.

Zie de sectie Voorbeeld voor volledige voorbeelden.

Gebruik

De bindingstypen die worden ondersteund door Blob-invoer, zijn afhankelijk van de versie van het extensiepakket en de C#-modaliteit die wordt gebruikt in uw functie-app.

Wanneer u wilt dat de functie één blob verwerkt, kan de blob-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
string De blob-inhoud als een tekenreeks. Gebruik deze functie wanneer de blob-inhoud eenvoudige tekst is.
byte[] De bytes van de blob-inhoud.
JSON serialiseerbare typen Wanneer een blob JSON-gegevens bevat, probeert Functions deSerialiseren van de JSON-gegevens in een niet-oud POCO-type (CLR-object).
Stream1 Een invoerstroom van de blob-inhoud.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1
Een client die is verbonden met de blob. Deze set typen biedt de meeste controle voor het verwerken van de blob en kan worden gebruikt om terug te schrijven naar de blob als de verbinding voldoende machtigingen heeft.

Wanneer u wilt dat de functie meerdere blobs uit een container verwerkt, kan de blob-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
T[] of List<T> waar T een van de bindingstypen voor één blob-invoer is Een matrix of lijst met meerdere blobs. Elke vermelding vertegenwoordigt één blob uit de container. U kunt ook verbinding maken met alle interfaces die door deze typen zijn geïmplementeerd, zoals IEnumerable<T>.
BlobContainerClient1 Een client die is verbonden met de container. Dit type biedt het meeste beheer voor het verwerken van de container en kan worden gebruikt om ernaar te schrijven als de verbinding voldoende machtigingen heeft.

1 Als u deze typen wilt gebruiken, moet u verwijzen naar Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 of hoger en de algemene afhankelijkheden voor SDK-typebindingen.

Binden aan stringof Byte[] wordt alleen aanbevolen wanneer de blobgrootte klein is. Dit wordt aanbevolen omdat de volledige blob-inhoud in het geheugen wordt geladen. Gebruik voor de meeste blobs een Stream of BlobClient type. Zie Gelijktijdigheid en geheugengebruik voor meer informatie.

Als u een foutbericht krijgt wanneer u verbinding probeert te maken met een van de Typen Storage SDK, controleert u of u een verwijzing hebt naar de juiste Storage SDK-versie.

U kunt ook StorageAccountAttribute gebruiken om het te gebruiken opslagaccount op te geven. U kunt dit doen wanneer u een ander opslagaccount moet gebruiken dan andere functies in de bibliotheek. De constructor gebruikt de naam van een app-instelling die een opslag-verbindingsreeks bevat. Het kenmerk kan worden toegepast op het niveau van de parameter, methode of klasse. In het volgende voorbeeld ziet u klasseniveau en methodeniveau:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

Het te gebruiken opslagaccount wordt in de volgende volgorde bepaald:

  • De eigenschap van Connection het BlobTrigger kenmerk.
  • Het StorageAccount kenmerk dat is toegepast op dezelfde parameter als het BlobTrigger kenmerk.
  • Het StorageAccount kenmerk dat is toegepast op de functie.
  • Het StorageAccount kenmerk dat is toegepast op de klasse.
  • Het standaardopslagaccount voor de functie-app, dat is gedefinieerd in de AzureWebJobsStorage toepassingsinstelling.

Het @BlobInput kenmerk geeft u toegang tot de blob die de functie heeft geactiveerd. Als u een bytematrix gebruikt met het kenmerk, stelt u deze in dataType op binary. Raadpleeg het invoervoorbeeld voor meer informatie.

Toegang tot de blobgegevens met behulp van context.extraInputs.get().

Open de blobgegevens via een parameter die overeenkomt met de naamparameter van de binding in het function.json-bestand .

Toegang tot blobgegevens via de parameter die is getypt als InputStream. Raadpleeg het invoervoorbeeld voor meer informatie.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Azure Blobs. Het kan het volgende opgeven:

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

Connection string

Als u een verbindingsreeks wilt verkrijgen, volgt u de stappen in Toegangssleutels voor het opslagaccount beheren. De verbindingsreeks moet zijn voor een opslagaccount voor algemeen gebruik, niet voor een Blob Storage-account.

Deze verbindingsreeks moet 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 connection op 'MyStorage', zoekt de Functions-runtime naar een app-instelling met de naam 'AzureWebJobsMyStorage'. Als u leeg laatconnection, gebruikt de Functions-runtime de standaardopslag-verbindingsreeks in de app-instelling met de naamAzureWebJobsStorage.

Op identiteit gebaseerde verbindingen

Als u versie 5.x of hoger van de extensie gebruikt (bundel 3.x of hoger voor non-.NET taalstacks), in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Als u een identiteit wilt gebruiken, definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toegewezen aan de connection eigenschap in de trigger- en bindingsconfiguratie.

Als u 'AzureWebJobsStorage' insteltconnection, raadpleegt u Verbinding maken voor het hosten van opslag met een identiteit. Voor alle andere verbindingen vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Blob Service-URI <CONNECTION_NAME_PREFIX>__serviceUri1 De gegevensvlak-URI van de blobservice waarmee u verbinding maakt, met behulp van het HTTPS-schema. <https:// storage_account_name.blob.core.windows.net>

1<CONNECTION_NAME_PREFIX>__blobServiceUri kan als alias worden gebruikt. Als de verbindingsconfiguratie wordt gebruikt door een blobtrigger, blobServiceUri moet u ook vergezeld gaan van queueServiceUri. Zie hieronder.

Het serviceUri formulier kan niet worden gebruikt wanneer de algemene verbindingsconfiguratie moet worden gebruikt in blobs, wachtrijen en/of tabellen. De URI kan alleen de blobservice aanwijzen. Als alternatief kunt u een URI opgeven die specifiek is bedoeld voor elke service, zodat één verbinding kan worden gebruikt. Als beide versies worden opgegeven, wordt het formulier voor meerdere services gebruikt. Als u de verbinding voor meerdere services wilt configureren in plaats van <CONNECTION_NAME_PREFIX>__serviceUri, stelt u het volgende in:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Blob Service-URI <CONNECTION_NAME_PREFIX>__blobServiceUri De gegevensvlak-URI van de blobservice waarmee u verbinding maakt, met behulp van het HTTPS-schema. <https:// storage_account_name.blob.core.windows.net>
Wachtrijservice-URI (vereist voor blobtriggers2) <CONNECTION_NAME_PREFIX>__queueServiceUri De gegevensvlak-URI van een wachtrijservice met behulp van het HTTPS-schema. Deze waarde is alleen nodig voor blobtriggers. <https:// storage_account_name.queue.core.windows.net>

2 De blobtrigger verwerkt fouten in meerdere nieuwe pogingen door gif-blobs naar een wachtrij te schrijven. In het serviceUri formulier wordt de AzureWebJobsStorage verbinding gebruikt. Bij het opgeven blobServiceUrimoet echter ook een wachtrijservice-URI worden opgegeven queueServiceUri. Het is raadzaam om de service uit hetzelfde opslagaccount als de blobservice te gebruiken. U moet er ook voor zorgen dat de trigger berichten kan lezen en schrijven in de geconfigureerde wachtrijservice door een rol toe te wijzen zoals Inzender voor opslagwachtrijgegevens.

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

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van 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 en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw blobcontainer. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Blob Storage-extensie in normale werking. Uw toepassing vereist mogelijk verdere machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen
Trigger Eigenaarvan opslagblobgegevens enInzendervoor opslagwachtrijgegevens 1

Er moeten ook extra machtigingen worden verleend aan de AzureWebJobsStorage-verbinding.2
Invoerbinding Lezer voor opslagblobgegevens
Uitvoerbinding Eigenaar van opslagblobgegevens

1 De blobtrigger verwerkt fouten in meerdere nieuwe pogingen door gif-blobs naar een wachtrij te schrijven in het opslagaccount dat is opgegeven door de verbinding.

2 De AzureWebJobsStorage-verbinding wordt intern gebruikt voor blobs en wachtrijen die de trigger inschakelen. Als deze is geconfigureerd voor het gebruik van een op identiteit gebaseerde verbinding, heeft deze extra machtigingen nodig dan de standaardvereiste. De vereiste machtigingen vallen onder de rollen Eigenaar van opslagblobgegevens, Inzender voor opslagwachtrijgegevens en Inzender voor opslagaccounts. Zie Verbinding maken voor meer informatie over het hosten van opslag met een identiteit.

Volgende stappen