Wyzwalacz usługi Azure Blob Storage dla usługi Azure Functions

Artykuł
05/21/2024

Wyzwalacz usługi Blob Storage uruchamia funkcję po wykryciu nowego lub zaktualizowanego obiektu blob. Zawartość obiektu blob jest dostarczana jako dane wejściowe funkcji.

Napiwek

Istnieje kilka sposobów wykonywania kodu funkcji na podstawie zmian w obiektach blob w kontenerze magazynu. Jeśli zdecydujesz się użyć wyzwalacza usługi Blob Storage, należy pamiętać, że dostępne są dwie implementacje: oparte na sondowaniu (o których mowa w tym artykule) i oparte na zdarzeniach. Zaleca się użycie implementacji opartej na zdarzeniach, ponieważ ma mniejsze opóźnienie niż inne. Ponadto plan Flex Consumption obsługuje tylko wyzwalacz magazynu obiektów blob opartych na zdarzeniach.

Aby uzyskać szczegółowe informacje o różnicach między dwiema implementacjami wyzwalacza usługi Blob Storage, a także innymi opcjami wyzwalania, zobacz Praca z obiektami blob.

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.

Wersja 2
Wersja 1

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.

Model izolowanego procesu roboczego
Model w procesie

Poniższy przykład to funkcja języka C#, która jest uruchamiana w izolowanym procesie roboczym i używa wyzwalacza obiektu blob z powiązaniami wejściowymi obiektów blob i wyjściowymi obiektów blob. Funkcja jest wyzwalana przez utworzenie obiektu blob w kontenerze test-samples-trigger . Odczytuje on plik tekstowy z kontenera test-samples-input i tworzy nowy plik tekstowy w kontenerze wyjściowym na podstawie nazwy wyzwalanego pliku.

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

W poniższym przykładzie pokazano funkcję języka C#, która zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze samples-workitems .

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

Ciąg {name} w ścieżce samples-workitems/{name} wyzwalacza obiektu blob tworzy wyrażenie powiązania, którego można użyć w kodzie funkcji w celu uzyskania dostępu do nazwy pliku wyzwalającego obiektu blob. Aby uzyskać więcej informacji, zobacz Wzorce nazw obiektów blob w dalszej części tego artykułu.

Aby uzyskać więcej informacji na temat atrybutu BlobTrigger , zobacz Atrybuty.

Ta funkcja zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze myblob .

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

Model w wersji 4
Model w wersji 3

W poniższym przykładzie pokazano kod TypeScript wyzwalacza obiektu blob. Funkcja zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze samples-workitems .

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

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

Model w wersji 4
Model w wersji 3

W poniższym przykładzie pokazano kod JavaScript wyzwalacza obiektu blob. Funkcja zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze samples-workitems .

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

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

W poniższym przykładzie pokazano powiązanie wyzwalacza obiektu blob w pliku function.json i kodzie JavaScript, który używa powiązania. Funkcja zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze samples-workitems .

Oto plik function.json:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

Aby uzyskać więcej informacji na temat function.json właściwości pliku, zobacz sekcję Konfiguracja wyjaśnia te właściwości.

Oto kod JavaScript:

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

W poniższym przykładzie pokazano, jak utworzyć funkcję uruchamianą po dodaniu pliku do source kontenera usługi Blob Storage.

Plik konfiguracji funkcji (function.json) zawiera powiązanie z wartością blobTrigger type i direction ustawioną na in.

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

Oto skojarzony kod pliku run.ps1 .

param([byte[]] $InputBlob, $TriggerMetadata)

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

Wersja 2
Wersja 1

W tym przykładzie użyto typów zestawu SDK do bezpośredniego uzyskiwania dostępu do bazowego BlobClient obiektu udostępnionego przez wyzwalacz usługi Blob Storage:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.blob_trigger(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_trigger(client: blob.BlobClient):
    logging.info(
        f"Python blob trigger function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )

Przykłady użycia innych typów zestawów SDK można znaleźć w artykule i StorageStreamDownloader samples (Przykłady).ContainerClient

Aby dowiedzieć się więcej, w tym jak włączyć powiązania typu zestawu SDK w projekcie, zobacz Powiązania typu zestawu SDK.

W tym przykładzie są dzienniki informacji z przychodzących metadanych obiektu blob.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

Funkcja zapisuje dziennik po dodaniu lub zaktualizowaniu obiektu blob w kontenerze samples-workitems . Oto plik function.json:

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

Aby uzyskać więcej informacji na temat function.json właściwości pliku, zobacz sekcję Konfiguracja wyjaśnia te właściwości.

Oto kod języka Python:

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

Atrybuty

Biblioteki języka C# procesu roboczego w procesie przetwarzania procesów przetwarzania izolowanego używają atrybutu BlobAttribute do zdefiniowania 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#.

Konstruktor atrybutu przyjmuje następujące parametry:

Parametr	Opis
Ścieżka obiektu blob	Ścieżka do obiektu blob.
Połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z obiektami blob platformy Azure. Zobacz Połączenia.
Uzyskaj dostęp	Wskazuje, czy będziesz odczytywać, czy zapisywać.
Source	Ustawia źródło zdarzenia wyzwalającego. Służy `BlobTriggerSource.EventGrid` do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to `BlobTriggerSource.LogsAndContainerScan`, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze.

Model izolowanego procesu roboczego
Model w procesie

BlobTrigger Oto atrybut w podpisie metody:

[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)

W bibliotekach klas języka C# konstruktor atrybutu przyjmuje ciąg ścieżki, który wskazuje kontener do obejrzenia i opcjonalnie wzorzec nazwy obiektu blob. Oto przykład:

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

Atrybut przyjmuje Connection właściwość, ale można również użyć atrybutu StorageAccountAttribute , aby określić połączenie konta magazynu. Można to zrobić, gdy musisz użyć innego konta magazynu niż inne funkcje w bibliotece. Konstruktor przyjmuje nazwę ustawienia aplikacji, które zawiera parametry połączenia magazynu. Atrybut można zastosować na poziomie parametru, metody lub klasy. W poniższym przykładzie przedstawiono poziom klasy i poziom metody:

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

Konto magazynu do użycia jest określane w następującej kolejności:

Właściwość atrybutu Connection wyzwalacza lub powiązania.
Atrybut StorageAccount zastosowany do tego samego parametru co wyzwalacz lub atrybut powiązania.
Atrybut StorageAccount zastosowany do funkcji.
Atrybut StorageAccount zastosowany do klasy.
Domyślne konto magazynu aplikacji funkcji, które jest zdefiniowane w ustawieniu AzureWebJobsStorage aplikacji.

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 dekoratorów następujące właściwości blob_trigger dekoratora definiują wyzwalacz usługi Blob Storage:

Właściwości	opis
`arg_name`	Deklaruje nazwę parametru w podpisie funkcji. Po wyzwoleniu funkcji wartość tego parametru zawiera zawartość komunikatu kolejki.
`path`	Kontener do monitorowania. Może to być wzorzec nazwy obiektu blob.
`connection`	Parametry połączenia konta magazynu.
`source`	Ustawia źródło zdarzenia wyzwalającego. Służy `EventGrid` do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to `LogsAndContainerScan`, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze.

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

Adnotacje

Atrybut @BlobTrigger służy do zapewniania dostępu do obiektu blob, który wyzwolił funkcję. Aby uzyskać szczegółowe informacje, zapoznaj się z przykładem wyzwalacza. source Użyj właściwości , aby ustawić źródło zdarzenia wyzwalającego. Służy EventGrid do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to LogsAndContainerScan, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze. |

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

Model w wersji 4
Model w wersji 3

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego app.storageBlob() do metody .

Właściwości	opis
path	Kontener do monitorowania. Może to być wzorzec nazwy obiektu blob.
połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z obiektami blob platformy Azure. Zobacz Połączenia.
source	Ustawia źródło zdarzenia wyzwalającego. Służy `EventGrid` do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to `LogsAndContainerScan`, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze.

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json .

Właściwości	Opis
type	Musi być ustawiona wartość `blobTrigger`. 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. Wyjątki są zanotowane w sekcji użycia .
name	Nazwa zmiennej reprezentującej obiekt blob w kodzie funkcji.
path	Kontener do monitorowania. Może to być wzorzec nazwy obiektu blob.
połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z obiektami blob platformy Azure. Zobacz Połączenia.
source	Ustawia źródło zdarzenia wyzwalającego. Służy `EventGrid` do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to `LogsAndContainerScan`, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze.

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ść `blobTrigger`. 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. Wyjątki są zanotowane w sekcji użycia .
name	Nazwa zmiennej reprezentującej obiekt blob w kodzie funkcji.
path	Kontener do monitorowania. Może to być wzorzec nazwy obiektu blob.
połączenie	Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z obiektami blob platformy Azure. Zobacz Połączenia.
source	Ustawia źródło zdarzenia wyzwalającego. Służy `EventGrid` do wyzwalacza obiektu blob opartego na usłudze Event Grid, który zapewnia znacznie mniejsze opóźnienie. Wartość domyślna to `LogsAndContainerScan`, która używa standardowego mechanizmu sondowania do wykrywania zmian w kontenerze.

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Metadane

Wyzwalacz obiektu blob zawiera kilka właściwości metadanych. Te właściwości mogą być używane jako część wyrażeń powiązań w innych powiązaniach lub jako parametry w kodzie. Te wartości mają te same semantyki co typ CloudBlob .

Właściwość	Type	Opis
`BlobTrigger`	`string`	Ścieżka do wyzwalającego obiektu blob.
`Uri`	`System.Uri`	Identyfikator URI obiektu blob dla lokalizacji podstawowej.
`Properties`	Właściwości obiektów blob	Właściwości systemowe obiektu blob.
`Metadata`	`IDictionary<string,string>`	Metadane zdefiniowane przez użytkownika dla obiektu blob.

Poniższy przykład rejestruje ścieżkę do wyzwalającego obiektu blob, w tym kontenera:

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
}

Metadane

Wyzwalacz obiektu blob zawiera kilka właściwości metadanych. Te właściwości mogą być używane jako część wyrażeń powiązań w innych powiązaniach lub jako parametry w kodzie.

Właściwości	opis
`blobTrigger`	Ścieżka do wyzwalającego obiektu blob.
`uri`	Identyfikator URI obiektu blob dla lokalizacji podstawowej.
`properties`	Właściwości systemowe obiektu blob.
`metadata`	Metadane zdefiniowane przez użytkownika dla obiektu blob.

Model w wersji 4
Model w wersji 3

Metadane można uzyskać z triggerMetadata właściwości dostarczonego context obiektu, jak pokazano w poniższym przykładzie, który rejestruje ścieżkę do wyzwalającego obiektu blob (blobTrigger), w tym kontenera:

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

Metadane można uzyskać z bindingData właściwości dostarczonego context obiektu, jak pokazano w poniższym przykładzie, który rejestruje ścieżkę do wyzwalającego obiektu blob (blobTrigger), w tym kontenera:

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

Metadane

Metadane są dostępne za pośrednictwem parametru $TriggerMetadata .

Użycie

Typy powiązań obsługiwane przez wyzwalacz obiektu blob zależą od wersji pakietu rozszerzenia i modalności języka C# używanej w aplikacji funkcji.

Model izolowanego procesu roboczego
Model w procesie

Wyzwalacz obiektu blob może być powiązany z następującymi typami:

Type	Opis
`string`	Zawartość obiektu blob jako ciąg. Użyj polecenia , gdy zawartość obiektu blob jest prostym tekstem.
`byte[]`	Bajty zawartości obiektu blob.
Typy serializowalne w formacie JSON	Gdy obiekt blob zawiera dane JSON, usługa Functions próbuje wykonać deserializacji danych JSON w zwykły typ obiektu CLR (POCO).
Strumień¹	Strumień wejściowy zawartości obiektu blob.
BlobClient¹, BlockBlobClient¹, PageBlobClient¹, AppendBlobClient¹, BlobBaseClient¹	Klient połączony z obiektem blob. Ten zestaw typów oferuje największą kontrolę przetwarzania obiektu blob i może służyć do zapisywania z powrotem do obiektu blob, jeśli połączenie ma wystarczające uprawnienia.

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

Powiązanie z elementem stringlub Byte[] jest zalecane tylko wtedy, gdy rozmiar obiektu blob jest niewielki. Jest to zalecane, ponieważ cała zawartość obiektu blob jest ładowana do pamięci. W przypadku większości obiektów blob użyj Stream typu lub BlobClient . Aby uzyskać więcej informacji, zobacz Współbieżność i użycie pamięci.

Jeśli podczas próby powiązania z jednym z typów zestawu STORAGE SDK zostanie wyświetlony komunikat o błędzie, upewnij się, że masz odwołanie do odpowiedniej wersji zestawu SDK usługi Storage.

Możesz również użyć atrybutu StorageAccountAttribute , aby określić konto magazynu do użycia. Można to zrobić, gdy musisz użyć innego konta magazynu niż inne funkcje w bibliotece. Konstruktor przyjmuje nazwę ustawienia aplikacji, które zawiera parametry połączenia magazynu. Atrybut można zastosować na poziomie parametru, metody lub klasy. W poniższym przykładzie przedstawiono poziom klasy i poziom metody:

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

Konto magazynu do użycia jest określane w następującej kolejności:

BlobTrigger Właściwość atrybutuConnection.
Atrybut StorageAccount zastosowany do tego samego parametru BlobTrigger co atrybut.
Atrybut StorageAccount zastosowany do funkcji.
Atrybut StorageAccount zastosowany do klasy.
Domyślne konto magazynu aplikacji funkcji, które jest zdefiniowane w ustawieniu AzureWebJobsStorage aplikacji.

Atrybut @BlobTrigger służy do zapewniania dostępu do obiektu blob, który wyzwolił funkcję. Aby uzyskać szczegółowe informacje, zapoznaj się z przykładem wyzwalacza.

Model w wersji 4
Model w wersji 3

Uzyskaj dostęp do danych obiektu blob jako pierwszego argumentu funkcji.

Uzyskaj dostęp do danych obiektu blob za pośrednictwem parametru zgodnego z nazwą wyznaczoną przez parametr name powiązania w pliku function.json .

Uzyskiwanie dostępu do danych obiektów blob za pośrednictwem parametru wpisanego jako InputStream. Aby uzyskać szczegółowe informacje, zapoznaj się z przykładem wyzwalacza.

Funkcje obsługują również powiązania typu zestawu SDK języka Python dla usługi Azure Blob Storage, co umożliwia pracę z danymi obiektów blob przy użyciu następujących podstawowych typów zestawów SDK:

Ważne

Obsługa typów zestawów SDK dla języka Python jest obecnie dostępna w wersji zapoznawczej i jest obsługiwana tylko dla modelu programowania języka Python w wersji 2. Aby uzyskać więcej informacji, zobacz Typy zestawów SDK w języku Python.

Połączenia

Właściwość connection jest odwołaniem do konfiguracji środowiska, która określa sposób łączenia aplikacji z obiektami blob 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. Parametry połączenia musi być kontem magazynu ogólnego przeznaczenia, a nie kontem usługi Blob Storage.

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 Nawiązywanie połączenia z magazynem hostów przy użyciu 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ść
Blob Service URI	`<CONNECTION_NAME_PREFIX>__serviceUri`¹	Identyfikator URI płaszczyzny danych usługi obiektów blob, z którą nawiązujesz połączenie, przy użyciu schematu HTTPS.	<https:// storage_account_name.blob.core.windows.net>

¹ <CONNECTION_NAME_PREFIX>__blobServiceUri może służyć jako alias. Jeśli konfiguracja połączenia będzie używana przez wyzwalacz obiektu blob, blobServiceUri musi również towarzyszyć queueServiceUrielement . Zobacz poniżej.

Nie serviceUri można użyć formularza, gdy ogólna konfiguracja połączenia ma być używana w obiektach blob, kolejkach i/lub tabelach. Identyfikator URI może wyznaczyć tylko usługę obiektów blob. Alternatywnie możesz podać identyfikator URI przeznaczony specjalnie dla każdej usługi, co pozwala na użycie jednego połączenia. Jeśli podano obie wersje, zostanie użyty formularz z wieloma usługami. Aby skonfigurować połączenie dla wielu usług, zamiast <CONNECTION_NAME_PREFIX>__serviceUri, ustaw:

Właściwości	Szablon zmiennej środowiskowej	opis	Przykładowa wartość
Blob Service URI	`<CONNECTION_NAME_PREFIX>__blobServiceUri`	Identyfikator URI płaszczyzny danych usługi obiektów blob, z którą nawiązujesz połączenie, przy użyciu schematu HTTPS.	<https:// storage_account_name.blob.core.windows.net>
Identyfikator URI usługi Queue Service (wymagany dla wyzwalaczy^{obiektów blob 2})	`<CONNECTION_NAME_PREFIX>__queueServiceUri`	Identyfikator URI płaszczyzny danych usługi kolejki przy użyciu schematu HTTPS. Ta wartość jest wymagana tylko w przypadku wyzwalaczy obiektów blob.	<https:// storage_account_name.queue.core.windows.net>

² Wyzwalacz obiektu blob obsługuje błąd w wielu ponownych próbach, zapisując do kolejki zatrute obiekty blob. W formularzu serviceUri AzureWebJobsStorage jest używane połączenie. Jednak podczas określania blobServiceUriidentyfikatora URI usługi kolejki należy również podać element queueServiceUri. Zaleca się używanie usługi z tego samego konta magazynu co usługa blob. Należy również upewnić się, że wyzwalacz może odczytywać i zapisywać komunikaty w skonfigurowanej usłudze kolejki, przypisując rolę, na przykład Współautor danych kolejki magazynu.

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ć.

Musisz utworzyć przypisanie roli, które zapewnia dostęp do kontenera obiektów blob 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 Blob Storage w normalnej operacji. Aplikacja może wymagać dalszych uprawnień na podstawie zapisanego kodu.

Typ powiązania	Przykładowe role wbudowane
Wyzwalacz	Właściciel danych obiektu blob usługi Storage i współautor^{danych kolejki magazynu 1} Dodatkowe uprawnienia muszą być również przyznane połączeniu AzureWebJobsStorage.²
Powiązanie wejściowe	Czytelnik danych obiektu blob usługi Storage
Powiązanie wyjściowe	Właściciel danych obiektu blob usługi Storage

¹ Wyzwalacz obiektu blob obsługuje błąd w wielu ponownych próbach, zapisując zatrute obiekty blob do kolejki na koncie magazynu określonym przez połączenie.

² Połączenie AzureWebJobsStorage jest używane wewnętrznie dla obiektów blob i kolejek, które umożliwiają wyzwalacz. Jeśli jest skonfigurowany do korzystania z połączenia opartego na tożsamościach, wymaga dodatkowych uprawnień poza domyślnym wymaganiem. Wymagane uprawnienia są objęte rolami Właściciel danych obiektu blob usługi Storage, Współautor danych kolejki usługi Storage i Współautor konta magazynu. Aby dowiedzieć się więcej, zobacz Nawiązywanie połączenia z magazynem hostów przy użyciu tożsamości.

Wzorce nazw obiektów blob

Można określić wzorzec nazwy obiektu blob we path właściwości w function.json lub w konstruktorze atrybutu BlobTrigger . Wzorzec nazwy może być wyrażeniem filtru lub powiązania. Poniższe sekcje zawierają przykłady.

Napiwek

Nazwa kontenera nie może zawierać rozpoznawania nazw we wzorcu nazwy.

Pobieranie nazwy pliku i rozszerzenia

W poniższym przykładzie pokazano, jak powiązać nazwę pliku obiektu blob i rozszerzenie oddzielnie:

"path": "input/{blobname}.{blobextension}",

Jeśli obiekt blob ma nazwę original-Blob1.txt, wartości blobname zmiennych i blobextension w kodzie funkcji to original-Blob1 i txt.

Filtruj według nazwy obiektu blob

W poniższym przykładzie wyzwalane są tylko obiekty blob w input kontenerze rozpoczynającym się ciągiem "original-":

"path": "input/original-{name}",

Jeśli nazwa obiektu blob jest original-Blob1.txt, wartość zmiennej name w kodzie funkcji to Blob1.txt.

Filtruj według typu pliku

Poniższy przykład wyzwala tylko w plikach .png :

"path": "samples/{name}.png",

Filtruj nawiasy klamrowe w nazwach plików

Aby wyszukać nawiasy klamrowe w nazwach plików, należy użyć dwóch nawiasów klamrowych. Poniższy przykład filtruje obiekty blob, które mają nawiasy klamrowe w nazwie:

"path": "images/{{20140101}}-{name}",

Jeśli obiekt blob ma nazwę {20140101}-soundfile.mp3, name wartość zmiennej w kodzie funkcji jest soundfile.mp3.

Sondowanie i opóźnienie

Sondowanie działa jako hybryda między inspekcją dzienników a okresowym skanowaniem kontenerów. Obiekty blob są skanowane w grupach 10 000 jednocześnie z tokenem kontynuacji używanym między interwałami. Jeśli aplikacja funkcji znajduje się w planie Zużycie, może wystąpić do 10-minutowe opóźnienie przetwarzania nowych obiektów blob, jeśli aplikacja funkcji nie będzie bezczynna.

Ostrzeżenie

Dzienniki magazynu są tworzone w oparciu o "najlepsze wysiłki". Nie ma gwarancji, że wszystkie zdarzenia są przechwytywane. W niektórych warunkach dzienniki mogą zostać pominięte.

Jeśli potrzebujesz szybszego lub bardziej niezawodnego przetwarzania obiektów blob, rozważ przełączenie hostingu w celu korzystania z planu usługi App Service z włączonym zawsze włączonym włączeniem, co może spowodować zwiększenie kosztów. Możesz również rozważyć użycie wyzwalacza innego niż klasyczny wyzwalacz sondowania obiektu blob. Aby uzyskać więcej informacji i porównanie różnych opcji wyzwalania dla kontenerów magazynu obiektów blob, zobacz Wyzwalanie w kontenerze obiektów blob.

Potwierdzenia dotyczące obiektów blob

Środowisko uruchomieniowe usługi Azure Functions zapewnia, że żadna funkcja wyzwalacza obiektu blob nie jest wywoływana więcej niż raz dla tego samego nowego lub zaktualizowanego obiektu blob. Aby określić, czy dana wersja obiektu blob została przetworzona, utrzymuje paragony obiektów blob.

Usługa Azure Functions przechowuje paragony obiektów blob w kontenerze o nazwie azure-webjobs-hosts na koncie usługi Azure Storage dla aplikacji funkcji (zdefiniowanej przez ustawienie AzureWebJobsStorageaplikacji). Potwierdzenie obiektu blob zawiera następujące informacje:

Wyzwolona funkcja (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>na przykład: MyFunctionApp.Functions.CopyBlob)
Nazwa kontenera
Typ obiektu blob (BlockBlob lub PageBlob)
Nazwa obiektu blob
Element ETag (identyfikator wersji obiektu blob, na przykład: 0x8D1DC6E70A277EF)

Aby wymusić ponowne przetwarzanie obiektu blob, usuń potwierdzenie obiektu blob dla tego obiektu blob z kontenera azure-webjobs-hosts ręcznie. Podczas ponownego przetwarzania może nie nastąpić natychmiast, gwarantowane jest wystąpienie w późniejszym momencie. Aby natychmiast ponownie przetworzyć obiekt blob scaninfo w usłudze azure-webjobs-hosts/blobscaninfo , można zaktualizować. Wszystkie obiekty blob z znacznikiem czasu ostatniej modyfikacji po LatestScan ponownym skanowaniu właściwości.

Zatrute obiekty blob

Gdy funkcja wyzwalacza obiektu blob zakończy się niepowodzeniem dla danego obiektu blob, usługa Azure Functions ponawia próbę, która domyślnie działa łącznie pięć razy.

Jeśli wszystkie 5 spróbuje zakończyć się niepowodzeniem, usługa Azure Functions doda komunikat do kolejki usługi Storage o nazwie webjobs-blobtrigger-poison. Maksymalna liczba ponownych prób jest konfigurowalna. To samo ustawienie MaxDequeueCount jest używane do obsługi zatrutych obiektów blob i obsługi komunikatów w kolejce trucizny. Komunikat kolejki dla zatrutych obiektów blob jest obiektem JSON zawierającym następujące właściwości:

FunctionId (w formacie <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
BlobType (BlockBlob lub PageBlob)
NazwaKontenera
Nazwa obiektu blob
ETag (identyfikator wersji obiektu blob, na przykład: 0x8D1DC6E70A277EF)

Użycie pamięci i współbieżność

W przypadku powiązania z typem danych wyjściowych, który nie obsługuje przesyłania strumieniowego, takiego jak string, lub Byte[], środowisko uruchomieniowe musi załadować cały obiekt blob do pamięci więcej niż jeden raz podczas przetwarzania. Może to spowodować wyższe niż oczekiwane użycie pamięci podczas przetwarzania obiektów blob. Jeśli to możliwe, użyj typu obsługującego strumień. Obsługa typów zależy od trybu i wersji rozszerzenia języka C#. Aby uzyskać więcej informacji, zobacz Typy powiązań.

W tej chwili środowisko uruchomieniowe musi załadować cały obiekt blob do pamięci więcej niż jeden raz podczas przetwarzania. Może to spowodować wyższe niż oczekiwane użycie pamięci podczas przetwarzania obiektów blob.

Użycie pamięci może mieć dalszy wpływ, gdy wiele wystąpień funkcji współbieżnie przetwarza dane obiektów blob. Jeśli masz problemy z pamięcią przy użyciu wyzwalacza obiektu blob, rozważ zmniejszenie liczby dozwolonych współbieżnych wykonań. Oczywiście zmniejszenie współbieżności może mieć wpływ uboczny na zwiększenie listy prac obiektów blob oczekujących na przetworzenie. Limity pamięci aplikacji funkcji zależą od planu. Aby uzyskać więcej informacji, zobacz Limity usługi.

Sposób kontrolowania liczby współbieżnych wykonań zależy od używanej wersji rozszerzenia magazynu.

Rozszerzenie 5.x i nowsze
Rozszerzenie wstępne 5.x

W przypadku korzystania z wersji 5.0.0 rozszerzenia magazynu lub nowszej wersji można kontrolować współbieżność wyzwalacza przy użyciu maxDegreeOfParallelism ustawienia w konfiguracji obiektów blob w host.json.

Limity mają zastosowanie oddzielnie do każdej funkcji, która używa wyzwalacza obiektu blob.

host.json właściwości

Plik host.json zawiera ustawienia kontrolujące zachowanie wyzwalacza obiektu blob. Aby uzyskać szczegółowe informacje dotyczące dostępnych ustawień, zobacz sekcję host.json settings (Ustawienia host.json).

Udostępnij za pośrednictwem

Wyzwalacz usługi Azure Blob Storage dla usługi Azure Functions

Przykład

Atrybuty

Dekoratory

Adnotacje

Konfigurowanie

Metadane

Metadane

Metadane

Użycie

Połączenia

Connection string

Połączenia oparte na tożsamościach

Udzielanie uprawnień tożsamości

Wzorce nazw obiektów blob

Pobieranie nazwy pliku i rozszerzenia

Filtruj według nazwy obiektu blob

Filtruj według typu pliku

Filtruj nawiasy klamrowe w nazwach plików

Sondowanie i opóźnienie

Potwierdzenia dotyczące obiektów blob

Zatrute obiekty blob

Użycie pamięci i współbieżność

host.json właściwości

Następne kroki

Opinia

Dodatkowe zasoby