Azure Blob Storage bemeneti kötés az Azure Functionshez

  • Cikk

A bemeneti kötés lehetővé teszi a Blob Storage-adatok beolvasását egy Azure-függvény bemeneteként.

A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.

Fontos

Ez a cikk lapokat használ a Node.js programozási modell több verziójának támogatásához. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további információkért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.

Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.

A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.

Ez a cikk mindkét programozási modellt támogatja.

Példa

A C#-függvények a következő C#-módok egyikével hozhatók létre:

  • Izolált feldolgozómodell: Lefordított C# függvény, amely a futtatókörnyezettől elkülönített feldolgozói folyamatban fut. Izolált feldolgozói folyamat szükséges az LTS- és nem LTS-verziókon futó C#-függvények támogatásához .NET és .NET-keretrendszer. Az izolált feldolgozói folyamatfüggvények bővítményei névtereket használnak Microsoft.Azure.Functions.Worker.Extensions.* .
  • Folyamaton belüli modell: Lefordított C# függvény, amely ugyanabban a folyamatban fut, mint a Functions-futtatókörnyezet. A modell egy változatában a Functions C#-szkriptekkel futtatható, amely elsősorban a C#-portál szerkesztéséhez támogatott. A folyamaton belüli függvények bővítményei névtereket használnak Microsoft.Azure.WebJobs.Extensions.* .

Fontos

A folyamaton belüli modell támogatása 2026. november 10-én megszűnik. Erősen javasoljuk, hogy az alkalmazásokat az elkülönített feldolgozói modellbe migrálja a teljes támogatás érdekében.

Az alábbi példa egy C# függvény , amely egy izolált feldolgozófolyamatban fut, és blob-eseményindítót használ blobbemenettel és blobkimeneti blobkötésekkel. A függvényt egy blob létrehozása váltja ki a test-samples-trigger tárolóban. Beolvassa a szövegfájlt a test-samples-input tárolóból, és létrehoz egy új szövegfájlt egy kimeneti tárolóban az aktivált fájl neve alapján.

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

Ez a szakasz a következő példákat tartalmazza:

HTTP-eseményindító, blobnév keresése lekérdezési sztringből

Az alábbi példa egy Java-függvényt mutat be, amely a HttpTrigger széljegyzet használatával egy blobtárolóban lévő fájl nevét tartalmazó paramétert fogad. A BlobInput széljegyzet ezután felolvassa a fájlt, és továbbítja annak tartalmát a függvénynek 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();
  }

Üzenetsor-eseményindító, blobnév fogadása üzenetsorból

Az alábbi példa egy Java-függvényt mutat be, amely a QueueTrigger széljegyzetet használja egy blobtárolóban lévő fájl nevét tartalmazó üzenet fogadásához. A BlobInput széljegyzet ezután felolvassa a fájlt, és továbbítja annak tartalmát a függvénynek 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");
  }

A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet olyan @BlobInput paramétereken, amelyek értéke egy blobból származna. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>.

Az alábbi példa egy üzenetsor által aktivált TypeScript-függvényt mutat be, amely egy blob másolatát készíti. A függvényt egy üzenetsor-üzenet aktiválja, amely tartalmazza a másolandó blob nevét. Az új blob neve {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,
});

Az alábbi példa egy üzenetsor által aktivált JavaScript-függvényt mutat be, amely egy blob másolatát készíti. A függvényt egy üzenetsor-üzenet aktiválja, amely tartalmazza a másolandó blob nevét. Az új blob neve {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);
    },
});

Az alábbi példa egy, a function.json fájlban definiált blobbemeneti kötést mutat be, amely elérhetővé teszi a bejövő blobadatokat a PowerShell-függvény számára.

A json-konfiguráció a következő:

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

A függvény kódja a következő:

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

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

Az alábbi példa blobbemeneteket és kimeneti kötéseket mutat be. A példa attól függ, hogy a v1 vagy v2 Python programozási modellt használja-e.

A kód létrehoz egy blob másolatát.

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"

Attribútumok

A folyamaton belüli és az izolált feldolgozói folyamat C# kódtárai attribútumokkal határozzák meg a függvényt. A C#-szkript ehelyett egy function.json konfigurációs fájlt használ a C#-szkriptelési útmutatóban leírtak szerint.

Az izolált feldolgozói folyamat egy attribútum használatával BlobInputAttribute definiál egy bemeneti kötést, amely a következő paramétereket veszi igénybe:

Paraméter Leírás
BlobPath A blob elérési útja.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Blobshoz. Lásd: Csatlakozás ions.

Helyi fejlesztéskor adja hozzá az alkalmazásbeállításokat a gyűjtemény local.settings.json fájljáhozValues.

Dekorátorok

Csak a Python v2 programozási modellre vonatkozik.

A dekorátorokkal definiált Python v2-függvények esetében a következő tulajdonságok határozzák meg a blob_inputblob_output Blob Storage-eseményindítókat:

Tulajdonság Leírás
arg_name Annak a változónak a neve, amely a függvénykódban a blobot jelöli.
path A dekoratőr blobjának blob_input elérési útja a blob olvasása. blob_output A dekorátor esetében ez a bemeneti blob kimenete vagy másolata.
connection A tárfiók kapcsolati sztringjét.
data_type A dinamikusan beírt nyelvek esetében a mögöttes adattípust adja meg. A lehetséges értékek a következők string: , binaryvagy stream. További részletekért tekintse meg az eseményindítók és kötések fogalmait.

A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.

Jegyzetek

Az @BlobInput attribútum hozzáférést biztosít a függvényt aktiváló blobhoz. Ha bájttömböt használ az attribútummal, állítsa a következőre dataTypebinary: . Részletekért tekintse meg a bemeneti példát .

Konfiguráció

Csak a Python v1 programozási modellre vonatkozik.

Az alábbi táblázat a metódusnak input.storageBlob() átadott objektumon options beállítható tulajdonságokat ismerteti.

Tulajdonság Leírás
ösvény A blob elérési útja.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Blobshoz. Lásd: Csatlakozás ions.

Az alábbi táblázat a function.json fájlban beállított kötéskonfigurációs tulajdonságokat ismerteti.

function.json tulajdonság Leírás
type A beállításnak a blobkövetkezőnek kell lennie: .
direction A beállításnak a inkövetkezőnek kell lennie: . A használati szakaszban kivételeket jegyezünk fel.
név Annak a változónak a neve, amely a függvénykódban a blobot jelöli.
ösvény A blob elérési útja.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Blobshoz. Lásd: Csatlakozás ions.
Adattípus A dinamikusan beírt nyelvek esetében a mögöttes adattípust adja meg. A lehetséges értékek a következők string: , binaryvagy stream. További részletekért tekintse meg az eseményindítók és kötések fogalmait.

A teljes példákért tekintse meg a Példa szakaszt .

Használat

A Blob-bemenet által támogatott kötéstípusok a bővítménycsomag verziójától és a függvényalkalmazásban használt C# módtól függnek.

Ha azt szeretné, hogy a függvény egyetlen blobot dolgozzon fel, a blob bemeneti kötése a következő típusokhoz kapcsolódhat:

Típus Leírás
string A blob tartalma sztringként. Akkor használható, ha a blob tartalma egyszerű szöveg.
byte[] A blobtartalom bájtja.
JSON szerializálható típusok Ha egy blob JSON-adatokat tartalmaz, a Functions megpróbálja deszerializálni a JSON-adatokat egy egyszerű régi CLR-objektum (POCO) típusba.
Stream1 A blobtartalom bemeneti adatfolyama.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 A blobhoz csatlakoztatott ügyfél. Ez a típuskészlet biztosítja a blob feldolgozásának legkonfigurálását, és visszaírható, ha a kapcsolat megfelelő engedéllyel rendelkezik.

Ha azt szeretné, hogy a függvény több blobot dolgozzon fel egy tárolóból, a blob bemeneti kötése a következő típusokhoz kapcsolódhat:

Típus Leírás
T[] vagy List<T> hol T található az egyetlen blob bemeneti kötéstípusa Több blob tömbje vagy listája. Minden bejegyzés egy blobot jelöl a tárolóból. Az ilyen típusok által implementált felületekhez is csatlakozhat, például IEnumerable<T>.
BlobContainerClient1 A tárolóhoz csatlakoztatott ügyfél. Ez a típus biztosítja a tároló feldolgozásának legnagyobb vezérlését, és írásra is használható, ha a kapcsolat megfelelő engedéllyel rendelkezik.

1 Ezeknek a típusoknak a használatához hivatkoznia kell a Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0-s vagy újabb verziójára, valamint az SDK-típuskötések gyakori függőségeire.

Kötés a stringblob méretéhez, vagy Byte[] csak akkor ajánlott, ha a blob mérete kicsi. Ez azért ajánlott, mert a blob teljes tartalma betöltődik a memóriába. A legtöbb blobhoz használjon vagy írjon be egy típust StreamBlobClient . További információ: Egyidejűség és memóriahasználat.

Ha hibaüzenet jelenik meg a Storage SDK-típusok egyikéhez való kötéskor, győződjön meg arról, hogy rendelkezik a megfelelő Storage SDK-verzióra mutató hivatkozással.

A StorageAccountAttribute használatával is megadhatja a használni kívánt tárfiókot. Ezt akkor teheti meg, ha más tárfiókot kell használnia, mint a tár más funkcióit. A konstruktor egy tárolási kapcsolati sztring tartalmazó alkalmazásbeállítás nevét veszi fel. Az attribútum a paraméter, a metódus vagy az osztály szintjén alkalmazható. Az alábbi példa az osztályszintet és a metódusszintet mutatja be:

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

A használni kívánt tárfiók meghatározása a következő sorrendben történik:

  • Az BlobTrigger attribútum tulajdonsága Connection .
  • Az StorageAccount attribútummal azonos paraméterre BlobTrigger alkalmazott attribútum.
  • A StorageAccount függvényre alkalmazott attribútum.
  • Az StorageAccount osztályra alkalmazott attribútum.
  • A függvényalkalmazás alapértelmezett tárfiókja, amely az AzureWebJobsStorage alkalmazásbeállításban van definiálva.

Az @BlobInput attribútum hozzáférést biztosít a függvényt aktiváló blobhoz. Ha bájttömböt használ az attribútummal, állítsa a következőre dataTypebinary: . Részletekért tekintse meg a bemeneti példát .

A blobadatok elérése a következő használatával context.extraInputs.get(): .

A blobadatok elérése egy olyan paraméteren keresztül, amely megfelel a kötés névparamétere által a function.json fájlban megadott névnek.

Blobadatok elérése az InputStreamként beírt paraméteren keresztül. Részletekért tekintse meg a bemeneti példát .

Kapcsolatok

A connection tulajdonság a környezetkonfigurációra mutató hivatkozás, amely meghatározza, hogy az alkalmazásnak hogyan kell csatlakoznia az Azure Blobshoz. A következőt határozhatja meg:

Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.

Kapcsolati sztring

A kapcsolati sztring beszerzéséhez kövesse a tárfiók hozzáférési kulcsainak kezelése című témakörben ismertetett lépéseket. A kapcsolati sztring általános célú tárfióknak kell lennie, nem Blob Storage-fióknak.

Ezt a kapcsolati sztring a kötéskonfiguráció tulajdonsága által connection megadott értéknek megfelelő névvel rendelkező alkalmazásbeállításban kell tárolni.

Ha az alkalmazásbeállítás neve az "AzureWebJobs" névvel kezdődik, itt csak a név fennmaradó részét adhatja meg. Ha például a "MyStorage" értékre van állítva connection , a Functions-futtatókörnyezet egy "AzureWebJobsMyStorage" nevű alkalmazásbeállítást keres. Ha üresen hagyjaconnection, a Functions-futtatókörnyezet az alapértelmezett Storage-kapcsolati sztring használja a névvel ellátott AzureWebJobsStoragealkalmazásbeállításban.

Identitásalapú kapcsolatok

Ha a bővítmény 5.x vagy újabb verzióját használja (a 3.x vagy újabb csomag non-.NET nyelvi veremekhez), ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Identitás használatához olyan beállításokat kell megadnia egy közös előtag alatt, amely leképezi a tulajdonságot az connection eseményindító és a kötés konfigurációjában.

Ha az "AzureWebJobsStorage" értékre van állítvaconnection, tekintse meg Csatlakozás a tároló identitással való üzemeltetését. Az összes többi kapcsolat esetében a bővítményhez a következő tulajdonságok szükségesek:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Blob Service URI <CONNECTION_NAME_PREFIX>__serviceUri1 Annak a blobszolgáltatásnak az adatsíkja, amelyhez csatlakozik, a HTTPS-séma használatával. <https:// storage_account_name.blob.core.windows.net>

Az 1<CONNECTION_NAME_PREFIX>__blobServiceUri aliasként használható. Ha a kapcsolatkonfigurációt egy blob-eseményindító fogja használni, blobServiceUri azt is mellékelnie queueServiceUrikell. Lásd alább.

Az serviceUri űrlap nem használható, ha az általános kapcsolatkonfigurációt blobokon, üzenetsorokon és/vagy táblákon kell használni. Az URI csak a blobszolgáltatást tudja kijelölni. Alternatív megoldásként külön URI-t is megadhat az egyes szolgáltatásokhoz, így egyetlen kapcsolat használható. Ha mindkét verzió meg van adva, a rendszer a többszolgáltatásos űrlapot használja. Több szolgáltatás kapcsolatának konfigurálásához a következő helyett <CONNECTION_NAME_PREFIX>__serviceUriállítsa be a következőt:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Blob Service URI <CONNECTION_NAME_PREFIX>__blobServiceUri Annak a blobszolgáltatásnak az adatsíkja, amelyhez csatlakozik, a HTTPS-séma használatával. <https:// storage_account_name.blob.core.windows.net>
Queue Service URI (a 2. blob triggerekhezszükséges) <CONNECTION_NAME_PREFIX>__queueServiceUri Egy üzenetsor-szolgáltatás adatsíkjának URI-ja a HTTPS-séma használatával. Ez az érték csak a blob-eseményindítókhoz szükséges. <https:// storage_account_name.queue.core.windows.net>

2 A blob-eseményindító több újrapróbálkozási művelet hibáit is kezeli, ha méregblobokat ír egy üzenetsorba. serviceUri Az űrlapon a rendszer a AzureWebJobsStorage kapcsolatot használja. A beállításkor blobServiceUriazonban egy üzenetsor-szolgáltatás URI-jának is meg kell adni.queueServiceUri Javasoljuk, hogy a szolgáltatást a blobszolgáltatással azonos tárfiókból használja. Arról is gondoskodnia kell, hogy az eseményindító képes legyen üzeneteket olvasni és írni a konfigurált üzenetsor-szolgáltatásban egy olyan szerepkör hozzárendelésével, mint a Storage Queue Data Contributor.

Más tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.

Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential tulajdonságokkal együtt clientID . Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.

Engedély megadása az identitáshoz

Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.

Fontos

A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.

Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít a blobtárolóhoz. A tulajdonoshoz hasonló felügyeleti szerepkörök nem elegendőek. Az alábbi táblázat olyan beépített szerepköröket mutat be, amelyek a Blob Storage-bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.

Kötés típusa Példa beépített szerepkörökre
Eseményindító Storage Blob Data OwnerandStorage Queue Data Contributor1

További engedélyeket is meg kell adni az AzureWebJobsStorage-kapcsolatnak.2
Bemeneti kötés Storage-blobadatok olvasója
Kimeneti kötés Storage-blobadatok tulajdonosa

1 A blob-eseményindító több újrapróbálkozás során is kezeli a hibákat, ha méregblobokat ír a kapcsolat által megadott tárfiók egyik üzenetsorába.

2 Az AzureWebJobsStorage kapcsolat belsőleg használatos az eseményindítót engedélyező blobokhoz és üzenetsorokhoz. Ha identitásalapú kapcsolat használatára van konfigurálva, az alapértelmezett követelményen túl további engedélyekre van szüksége. A szükséges engedélyekre a Storage Blob Data Owner, a Storage Queue Data Közreműködő és a Tárfiók közreműködői szerepkörei vonatkoznak. További információ: Csatlakozás tárolók identitással való üzemeltetéséhez.

Következő lépések