Azure Functions에 대한 Azure Blob Storage 트리거

아티클
05/14/2024

Blob Storage 트리거는 새 Blob 또는 업데이트된 Blob이 검색되면 함수를 시작합니다. Blob 콘텐츠는 함수의 입력으로 제공됩니다.

팁

스토리지 컨테이너의 Blob에 대한 변경 내용에 따라 함수 코드를 실행하는 여러 방법이 있습니다. Blob Storage 트리거를 사용하도록 선택하는 경우 폴링 기반 구현(이 문서에서 참조)과 이벤트 기반 구현의 두 가지 구현이 제공됩니다. 다른 구현보다 대기 시간이 짧기 때문에 이벤트 기반 구현을 사용하는 것이 좋습니다. 또한 Flex Consumption 계획은 이벤트 기반 Blob Storage 트리거만 지원합니다.

Blob Storage 트리거의 두 구현 간의 차이점과 다른 트리거 옵션에 대한 자세한 내용은 Blob 작업(Working with Blob)을 참조 하세요.

설정 및 구성 세부 정보에 대한 자세한 내용은 개요를 참조하세요.

Important

이 문서에서는 탭을 사용하여 여러 버전의 Node.js 프로그래밍 모델을 지원합니다. v4 모델은 일반적으로 사용 가능하며 JavaScript 및 TypeScript 개발자를 위해 보다 유연하고 직관적인 환경을 제공하도록 설계되었습니다. v4 모델의 작동 방식에 대한 자세한 내용은 Azure Functions Node.js 개발자 가이드를 참조하세요. v3과 v4의 차이점에 대해 자세히 알아보려면 마이그레이션 가이드를 참조하세요.

Azure Functions는 Python에 대해 두 가지 프로그래밍 모델을 지원합니다. 바인딩을 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python v2 프로그래밍 모델을 사용하면 Python 함수 코드에서 직접 데코레이터를 사용하여 바인딩을 정의할 수 있습니다. 자세한 내용은 Python 개발자 가이드를 참조하세요.

이 문서에서는 두 프로그래밍 모델을 모두 지원합니다.

예시

C# 함수는 다음 C# 모드 중 하나를 사용하여 만들 수 있습니다.

격리된 작업자 모델: 런타임에서 격리된 작업자 프로세스에서 실행되는 컴파일된 C# 함수입니다. LTS 및 비 LTS 버전 .NET 및 .NET Framework에서 실행되는 C# 함수를 지원하려면 격리된 작업자 프로세스가 필요합니다. 격리된 작업자 프로세스 함수에 대한 확장은 Microsoft.Azure.Functions.Worker.Extensions.* 네임스페이스를 사용합니다.
In Process 모델: Functions 런타임과 동일한 프로세스에서 실행되는 컴파일된 C# 함수입니다. 이 모델의 변형에서는 주로 C# 포털 편집에 지원되는 C# 스크립팅을 사용하여 Functions를 실행할 수 있습니다. In Process 함수에 대한 확장은 Microsoft.Azure.WebJobs.Extensions.* 네임스페이스를 사용합니다.

Important

In Process 모델에 대한 지원은 2026년 11월 10일에 종료됩니다. 전체 지원을 위해 앱을 격리된 작업자 모델로 마이그레이션하는 것이 좋습니다.

격리된 작업자 모델
In Process 모델

다음 예는 격리된 작업자 프로세스에서 실행되고 blob 입력 및 blob 출력 blob 바인딩과 함께 blob 트리거를 사용하는 C# 함수입니다. 함수는 test-samples-trigger 컨테이너에서 blob을 만들어 트리거됩니다. test-samples-input 컨테이너에서 텍스트 파일을 읽고 트리거된 파일의 이름을 기반으로 출력 컨테이너에 새 텍스트 파일을 만듭니다.

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

다음 예제에서는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 작성하는 C# 함수 를 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");
}

blob 트리거 경로 samples-workitems/{name}의 문자열 {name}은 함수 코드에서 사용할 수 있는 바인딩 식을 만들어 트리거 blob의 파일 이름에 액세스합니다. 자세한 내용은 이 문서의 뒷부분에 있는 Blob 이름 패턴을 참조하세요.

BlobTrigger 특성에 대한 자세한 내용은 특성을 참조하세요.

이 함수는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 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");
}

모델 v4
모델 v3

다음 예제에서는 BLOB 트리거 TypeScript 코드를 보여줍니다. 이 함수는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 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,
});

모델 v4
모델 v3

다음 예제에서는 BLOB 트리거 JavaScript 코드를 보여줍니다. 이 함수는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 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`
        );
    },
});

다음 예제에서는 function.json 파일의 Blob 트리거 바인딩 및 바인딩을 사용하는 JavaScript 코드를 보여줍니다. 이 함수는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 samples-workitems 작성합니다.

function.json 파일은 다음과 같습니다.

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

function.json 파일 속성에 대한 자세한 내용은 이러한 속성을 설명하는 구성 섹션을 참조하세요.

JavaScript 코드는 다음과 같습니다.

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

다음 예제에서는 Blob Storage 컨테이너에 파일을 추가할 때 실행되는 함수를 source 만드는 방법을 보여 줍니다.

함수 구성 파일(function.json)에는 로 blobTrigger direction 설정된 in바인딩이 type 포함됩니다.

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

run.ps1 파일에 대한 연결된 코드는 다음과 같습니다.

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

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

이 예제에서는 SDK 형식을 사용하여 Blob Storage 트리거에서 제공하는 기본 BlobClient 개체에 직접 액세스합니다.

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

다른 SDK 형식을 사용하는 예제는 및 StorageStreamDownloader 샘플을 참조 ContainerClient 하세요.

프로젝트에서 SDK 형식 바인딩을 사용하도록 설정하는 방법을 포함하여 자세한 내용은 SDK 형식 바인딩을 참조 하세요.

이 예제에서는 들어오는 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")

이 함수는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 samples-workitems 작성합니다. function.json 파일은 다음과 같습니다.

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

function.json 파일 속성에 대한 자세한 내용은 이러한 속성을 설명하는 구성 섹션을 참조하세요.

다음은 Python 코드입니다.

import logging
import azure.functions as func


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

특성

In Process 및 격리된 작업자 프로세스 C# 라이브러리는 모두 BlobAttribute 특성을 사용하여 함수를 정의합니다. 대신 C# 스크립트는 C# 스크립팅 가이드에 설명된 대로 function.json 구성 파일을 사용합니다.

특성의 생성자는 다음 매개 변수를 사용합니다.

매개 변수	설명
BlobPath	Blob에 대한 경로입니다.
Connection	Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.
액세스	읽기 또는 쓰기를 나타냅니다.
Source	트리거 이벤트의 원본을 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 `BlobTriggerSource.EventGrid`를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 `BlobTriggerSource.LogsAndContainerScan`입니다.

격리된 작업자 모델
In Process 모델

다음은 메서드 서명의 BlobTrigger 특성입니다.

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

C# 클래스 라이브러리에서 특성의 생성자는 관찰할 컨테이너와 선택적으로 Blob 이름 패턴을 나타내는 경로 문자열을 사용합니다. 예를 들어 다음과 같습니다.

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

특성은 Connection 특성을 사용하지만 StorageAccountAttribute를 사용하여 스토리지 계정 연결을 지정할 수도 있습니다. 라이브러리의 다른 함수와 다른 스토리지 계정을 사용해야 하는 경우 이 작업을 수행할 수 있습니다. 생성자는 스토리지 연결 문자열 포함하는 앱 설정의 이름을 사용합니다. 매개 변수, 메서드 또는 클래스 수준에서 특성을 적용할 수 있습니다. 다음 예제에서는 클래스 수준 및 메서드 수준을 보여줍니다.

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

사용할 스토리지 계정은 다음 순서로 결정됩니다.

트리거 또는 바인딩 특성의 Connection 특성입니다.
StorageAccount 특성이 트리거 또는 바인딩 특성과 동일한 매개 변수에 적용되었습니다.
StorageAccount 함수에 적용된 특성입니다.
StorageAccount 클래스에 적용된 특성입니다.
AzureWebJobsStorage 애플리케이션 설정에 정의된 함수 앱의 기본 스토리지 계정입니다.

로컬에서 개발하는 경우 Values 컬렉션의 local.settings.json 파일에 애플리케이션 설정을 추가합니다.

데코레이터

Python v2 프로그래밍 모델에만 적용됩니다.

데코레이터를 사용하여 정의된 Python v2 함수의 경우 데코레이터의 다음 속성은 blob_trigger Blob Storage 트리거를 정의합니다.

속성	설명
`arg_name`	함수 서명에서 매개 변수 이름을 선언합니다. 함수가 트리거되면 해당 매개 변수의 값이 큐 메시지의 내용을 포함합니다.
`path`	모니터링할 컨테이너입니다. Blob 이름 패턴일 수 있습니다.
`connection`	스토리지 계정 연결 문자열.
`source`	트리거 이벤트의 원본을 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 `EventGrid`를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 `LogsAndContainerScan`입니다.

function.json 사용하여 정의된 Python 함수는 구성 섹션을 참조하세요.

주석

이 @BlobTrigger 특성은 함수를 트리거한 Blob에 대한 액세스를 제공하는 데 사용됩니다. 자세한 내용은 트리거 예제를 참조하세요. source 속성을 사용하여 트리거 이벤트의 소스를 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 EventGrid를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 LogsAndContainerScan입니다. |

구성

Python v1 프로그래밍 모델에만 적용됩니다.

모델 v4
모델 v3

다음 표에서는 app.storageBlob() 메서드에 전달된 options 개체에 설정할 수 있는 속성에 대해 설명합니다.

속성	설명
path	모니터링할 컨테이너입니다. Blob 이름 패턴일 수 있습니다.
connection	Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.
source	트리거 이벤트의 원본을 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 `EventGrid`를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 `LogsAndContainerScan`입니다.

다음 표에서는 function.json 파일에 설정된 바인딩 구성 속성을 설명합니다.

속성	설명
type	`blobTrigger`로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.
direction	`in`로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다. 예외는 사용 섹션에 나와 있습니다.
이름	함수 코드에서 Blob을 나타내는 변수의 이름입니다.
path	모니터링할 컨테이너입니다. Blob 이름 패턴일 수 있습니다.
connection	Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.
source	트리거 이벤트의 원본을 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 `EventGrid`를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 `LogsAndContainerScan`입니다.

다음 표에서는 function.json 파일에 설정된 바인딩 구성 속성을 설명합니다.

function.json 속성	설명
type	`blobTrigger`로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.
direction	`in`로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다. 예외는 사용 섹션에 나와 있습니다.
이름	함수 코드에서 Blob을 나타내는 변수의 이름입니다.
path	모니터링할 컨테이너입니다. Blob 이름 패턴일 수 있습니다.
connection	Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.
source	트리거 이벤트의 원본을 설정합니다. 훨씬 짧은 대기 시간을 제공하는 Event Grid 기반 Blob 트리거에 `EventGrid`를 사용합니다. 기본값은 표준 폴링 메커니즘을 사용하여 컨테이너의 변경 내용을 검색하는 `LogsAndContainerScan`입니다.

전체 예제는 예제 섹션을 참조하세요.

메타데이터

Blob 트리거는 여러 메타데이터 속성을 제공합니다. 이러한 속성을 다른 바인딩에서 바인딩 식의 일부로 사용하거나 코드에서 매개 변수로 사용할 수 있습니다. 이러한 값은 CloudBlob 형식과 의미 체계가 동일합니다.

속성	Type	설명
`BlobTrigger`	`string`	Blob을 트리거하는 경로입니다.
`Uri`	`System.Uri`	기본 위치에 대한 Blob의 URI입니다.
`Properties`	BlobProperties	Blob의 시스템 속성입니다.
`Metadata`	`IDictionary<string,string>`	Blob에 대한 사용자 정의 메타데이터입니다.

다음 예제에서는 컨테이너를 포함하여 트리거하는 Blob에 대한 경로를 기록합니다.

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

메타데이터

Blob 트리거는 여러 메타데이터 속성을 제공합니다. 이러한 속성을 다른 바인딩에서 바인딩 식의 일부로 사용하거나 코드에서 매개 변수로 사용할 수 있습니다.

속성	설명
`blobTrigger`	Blob을 트리거하는 경로입니다.
`uri`	기본 위치에 대한 Blob의 URI입니다.
`properties`	Blob의 시스템 속성입니다.
`metadata`	Blob에 대한 사용자 정의 메타데이터입니다.

모델 v4
모델 v3

컨테이너를 포함하여 트리거 Blob(blobTrigger)에 대한 경로를 기록하는 다음 예제와 같이 제공된 context 개체의 triggerMetadata 속성에서 메타데이터를 얻을 수 있습니다.

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

컨테이너를 포함하여 트리거 Blob(blobTrigger)에 대한 경로를 기록하는 다음 예제와 같이 제공된 context 개체의 bindingData 속성에서 메타데이터를 얻을 수 있습니다.

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

메타데이터

메타데이터는 매개 변수를 $TriggerMetadata 통해 사용할 수 있습니다.

사용

Blob 트리거에서 지원하는 바인딩 형식은 함수 앱에서 사용되는 확장 패키지 버전 및 C# 형식에 따라 달라집니다.

격리된 작업자 모델
In Process 모델

Blob 트리거는 다음 형식에 바인딩될 수 있습니다.

Type	설명
`string`	Blob 콘텐츠를 문자열로 지정입니다. Blob 콘텐츠가 간단한 텍스트인 경우에 사용합니다.
`byte[]`	Blob 콘텐츠의 바이트입니다.
JSON 직렬화 가능 형식	Blob에 JSON 데이터가 포함된 경우 Functions는 JSON 데이터를 POCO(일반 CLR 개체) 형식으로 역직렬화하려고 합니다.
스트림¹	Blob 콘텐츠의 입력 스트림입니다.
BlobClient¹, BlockBlobClient¹, PageBlobClient¹, AppendBlobClient¹, BlobBaseClient¹	Blob에 연결된 클라이언트입니다. 이 형식 집합은 Blob 처리에 대한 대부분의 제어를 제공하며 연결에 충분한 권한이 있는 경우 Blob에 다시 쓰는 데 사용할 수 있습니다.

¹ 이러한 형식을 사용하려면 Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 이상 및 SDK 형식 바인딩에 대한 일반적인 종속성을 참조해야 합니다.

Blob 크기가 작은 경우에만 string 또는 Byte[]에 바인딩하는 것이 좋습니다. 전체 Blob 콘텐츠가 메모리에 로드되기 때문에 권장됩니다. 대부분의 Blob에는 Stream 또는 BlobClient 형식을 사용합니다. 자세한 내용은 동시성 및 메모리 사용량을 참조하세요.

Storage SDK 형식 중 하나에 바인딩하려고 할 때 발생하는 오류 메시지가 표시되면 올바른 Storage SDK 버전에 대한 참조가 있는지 확인합니다.

StorageAccountAttribute를 사용하여 사용할 스토리지 계정을 지정할 수도 있습니다. 라이브러리의 다른 함수와 다른 스토리지 계정을 사용해야 하는 경우 이 작업을 수행할 수 있습니다. 생성자는 스토리지 연결 문자열 포함하는 앱 설정의 이름을 사용합니다. 매개 변수, 메서드 또는 클래스 수준에서 특성을 적용할 수 있습니다. 다음 예제에서는 클래스 수준 및 메서드 수준을 보여줍니다.

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

사용할 스토리지 계정은 다음 순서로 결정됩니다.

BlobTrigger 특성의 속성입니다Connection.
BlobTrigger 특성과 동일한 매개 변수에 적용된 StorageAccount 특성
StorageAccount 함수에 적용된 특성입니다.
StorageAccount 클래스에 적용된 특성입니다.
AzureWebJobsStorage 애플리케이션 설정에 정의된 함수 앱의 기본 스토리지 계정입니다.

이 @BlobTrigger 특성은 함수를 트리거한 Blob에 대한 액세스를 제공하는 데 사용됩니다. 자세한 내용은 트리거 예제를 참조하세요.

모델 v4
모델 v3

함수에 대한 첫 번째 인수로 Blob 데이터에 액세스합니다.

function.json 파일에서 바인딩의 이름 매개 변수로 지정된 이름과 일치하는 매개 변수를 통해 Blob 데이터에 액세스합니다.

InputStream으로 형식화된 매개 변수를 통해 Blob 데이터에 액세스합니다. 자세한 내용은 트리거 예제를 참조하세요.

또한 Functions는 Azure Blob Storage에 대한 Python SDK 형식 바인딩을 지원하므로 다음과 같은 기본 SDK 형식을 사용하여 Blob 데이터를 사용할 수 있습니다.

Important

Python에 대한 SDK 형식 지원은 현재 미리 보기로 제공되며 Python v2 프로그래밍 모델에서만 지원됩니다. 자세한 내용은 Python의 SDK 형식을 참조 하세요.

연결

connection 속성은 앱이 Azure Blob에 연결해야 하는 방법을 지정하는 환경 구성에 대한 참조입니다. 다음을 지정할 수 있습니다.

연결 문자열이 포함된 애플리케이션 설정의 이름
함께 ID 기반 연결을 정의하는 여러 애플리케이션 설정에 대한 공유 접두사의 이름입니다.

구성된 값이 단일 설정에 대해 정확히 일치하고 다른 설정에 대해 접두사가 일치하는 경우 정확한 일치가 사용됩니다.

연결 문자열

연결 문자열을 가져오려면 스토리지 계정 액세스 키 관리에 표시된 단계를 따릅니다. 연결 문자열 Blob Storage 계정이 아닌 범용 스토리지 계정용이어야 합니다.

이 연결 문자열은 바인딩 구성의 connection 속성에 지정된 값과 일치하는 이름으로 애플리케이션 설정에 저장해야 합니다.

앱 설정 이름이 "AzureWebJobs"로 시작하는 경우 여기서 이름의 나머지만 지정할 수 있습니다. 예를 들어 connection을 “MyStorage”로 설정한 경우 함수 런타임 기능은 “AzureWebJobsMyStorage”라는 앱 설정을 찾습니다. connection을 비워 두면 함수 런타임 기능은 AzureWebJobsStorage라는 앱 설정에서 기본 스토리지 연결 문자열을 사용합니다.

ID 기반 연결

버전 5.x 이상(non-.NET 언어 스택의 경우 번들 3.x 이상)을 사용하는 경우 비밀과 함께 연결 문자열 사용하는 대신 앱에서 Microsoft Entra ID를 사용하도록 할 수 있습니다. ID를 사용하려면 트리거 및 바인딩 구성의 connection 속성에 매핑되는 공통 접두사 아래에 설정을 정의합니다.

connection을 "AzureWebJobsStorage"로 설정하는 경우 ID로 호스트 스토리지에 연결을 참조하세요. 다른 모든 연결의 경우 확장에는 다음 속성이 필요합니다.

속성	환경 변수 템플릿	설명	예제 값
Blob service URI	`<CONNECTION_NAME_PREFIX>__serviceUri`¹	HTTPS 체계를 사용하여 연결 중인 Blob 서비스의 데이터 평면 URI입니다.	https://<storage_account_name>.blob.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__blobServiceUri 은 별칭으로 사용할 수 있습니다. Blob 트리거에서 연결 구성을 사용하는 경우 blobServiceUri도 queueServiceUri와 함께 사용해야 합니다. 아래 참조

전체 연결 구성이 Blob, 큐 및/또는 테이블에서 사용되는 경우 serviceUri 형식을 사용할 수 없습니다. URI는 Blob 서비스만 지정할 수 있습니다. 대안으로 각 서비스에 대해 특별히 URI를 제공하여 단일 연결을 사용할 수 있습니다. 두 버전이 모두 제공되는 경우 다중 서비스 양식이 사용됩니다. 여러 서비스에 대한 연결을 구성하려면 <CONNECTION_NAME_PREFIX>__serviceUri 대신 다음을 설정합니다.

속성	환경 변수 템플릿	설명	예제 값
Blob service URI	`<CONNECTION_NAME_PREFIX>__blobServiceUri`	HTTPS 체계를 사용하여 연결 중인 Blob 서비스의 데이터 평면 URI입니다.	https://<storage_account_name>.blob.core.windows.net
큐 서비스 URI(BLOB 트리거에 필요²)	`<CONNECTION_NAME_PREFIX>__queueServiceUri`	HTTPS 체계를 사용하는 큐 서비스의 데이터 평면 URI입니다. 이 값은 Blob 트리거에만 필요합니다.	https://<storage_account_name>.queue.core.windows.net

² Blob 트리거는 포이즌 Blob을 큐에 작성하여 여러 다시 시도에서 실패를 처리합니다. serviceUri 형식에서는 AzureWebJobsStorage 연결이 사용됩니다. 그러나 blobServiceUri를 지정할 때 큐 서비스 URI도 queueServiceUri와 함께 제공되어야 합니다. Blob 서비스와 동일한 스토리지 계정의 서비스를 사용하는 것이 좋습니다. 또한 Storage 큐 데이터 기여자와 같은 역할을 할당하여 트리거가 구성된 큐 서비스에서 메시지를 읽고 쓸 수 있는지 확인해야 합니다.

연결을 사용자 지정하기 위해 다른 속성을 설정할 수 있습니다. ID 기반 연결의 공통 속성을 참조하세요.

Azure Functions 서비스에서 호스트되는 경우 ID 기반 연결에 관리 ID가 사용됩니다. 사용자가 할당한 ID는 credential 및 clientID 속성을 사용하여 지정할 수 있지만 기본적으로 시스템 할당 ID가 사용됩니다. 리소스 ID를 사용하여 사용자가 할당한 ID를 구성하는 것은 지원되지 않습니다. 로컬 개발과 같은 다른 컨텍스트에서 실행할 때 사용자 지정할 수 있지만 대신 개발자 ID가 사용됩니다. ID 기반 연결을 사용하여 로컬 개발을 참조하세요.

ID에 권한 부여

사용되는 모든 ID에는 의도한 작업을 수행할 수 있는 권한이 있어야 합니다. 대부분 Azure 서비스의 경우 이는 해당 권한을 제공하는 기본 제공 또는 사용자 지정 역할을 사용하여 Azure RBAC에서 역할을 할당해야 함을 의미합니다.

Important

일부 사용 권한은 모든 컨텍스트에 필요하지 않은 대상 서비스에 의해 노출될 수 있습니다. 가능한 경우 최소 권한 원칙을 준수하여 ID에 필요한 권한만 부여하세요. 예를 들어 앱이 데이터 원본에서 읽을 수만 있으면 되는 경우 읽기 권한만 있는 역할을 사용합니다. 읽기 작업에 대한 과도한 권한이 될 수 있으므로 해당 서비스에 쓰기도 허용하는 역할을 할당하는 것은 부적절합니다. 마찬가지로 역할 할당이 읽어야 하는 리소스에 대해서만 범위가 할당되도록 할 수 있습니다.

런타임에 Blob 컨테이너에 대한 액세스를 제공하는 역할 할당을 만들어야 합니다. 소유자와 같은 관리 역할로는 충분하지 않습니다. 다음 표는 정상 작동에서 Blob Storage 확장을 사용할 때 권장되는 기본 제공 역할을 보여 줍니다. 작성하는 코드에 따라 애플리케이션에 추가 권한이 필요할 수 있습니다.

바인딩 유형	기본 제공 역할 예
트리거	Storage Blob 데이터 소유자 및 스토리지 큐 데이터 기여자¹ AzureWebJobsStorage 연결에도 추가 권한을 부여해야 합니다.²
입력 바인딩	Storage Blob 데이터 읽기 권한자
출력 바인딩	Storage Blob 데이터 소유자

¹ Blob 트리거는 연결에 의해 지정된 스토리지 계정의 큐에 포이즌 Blob을 작성하여 여러 다시 시도에서 실패를 처리합니다.

² AzureWebJobsStorage 연결은 트리거를 사용하도록 설정하는 Blob 및 큐에 내부적으로 사용됩니다. ID 기반 연결을 사용하도록 구성된 경우 기본 요구 사항 이상의 추가 권한이 필요합니다. 필요한 권한은 Storage Blob 데이터 소유자, Storage 큐 데이터 기여자 및 Storage 계정 기여자 역할에서 다룹니다. 자세한 내용은 ID로 호스트 스토리지에 연결을 참조하세요.

Blob 이름 패턴

속성의 function.json 또는 특성 생성자에서 BlobTrigger Blob 이름 패턴을 path 지정할 수 있습니다. 이름 패턴은 필터 또는 바인딩 식일 수 있습니다. 다음 섹션에서는 예시를 제공합니다.

팁

컨테이너 이름은 이름 패턴에 확인자를 포함할 수 없습니다.

파일 이름 및 확장명 가져오기

다음 예제에서는 Blob 파일 이름과 확장명을 별도로 바인딩하는 방법을 보여 있습니다.

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

blob의 이름이 original-Blob1.txt 경우 함수 코드의 blobname 변수 및 blobextension 값은 original-Blob1 및 txt입니다.

Blob 이름 필터링

다음 예제는 "original-" 문자열로 시작하는 input 컨테이너에 있는 Blob에서만 트리거됩니다.

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

Blob 이름이 original-Blob1.txt 경우 함수 코드의 name 변수 값은 .입니다 Blob1.txt.

파일 형식에 대한 필터링

다음 예제에서는 .png 파일에서만 트리거합니다.

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

파일 이름에서 중괄호 필터링

파일 이름에서 중괄호를 찾으려면 두 개의 중괄호를 사용하여 중괄호를 이스케이프합니다. 다음 예제에서는 이름에 중괄호가 있는 Blob을 필터링합니다.

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

blob {20140101}이름이 -soundfile.mp3name 경우 함수 코드의 변수 값은 soundfile.mp3.

폴링 및 대기 시간

폴링은 로그 검사와 정기적인 컨테이너 검색 실행 간의 하이브리드로 작동합니다. Blob은 간격 간에 사용되는 연속 토큰을 사용하여 한 번에 1만 개 그룹으로 스캔됩니다. 함수 앱이 소비 계획에 있는 경우 함수 앱이 유휴 상태인 경우 새 Blob 처리가 최대 10분 지연될 수 있습니다.

Warning

스토리지 로그는 "최상의 결과"를 기준으로 만들어집니다. 모든 이벤트가 캡처된다는 보장은 없습니다. 일부 조건에서는 로그가 누락될 수 있습니다.

더 빠르고 신뢰할 수 있는 Blob 처리가 필요한 경우 Always On을 사용하도록 설정된 App Service 계획을 사용하도록 호스팅을 전환하는 것이 좋습니다. 이로 인해 비용이 증가할 수 있습니다. 클래식 폴링 Blob 트리거 이외의 트리거를 사용하는 것도 고려할 수 있습니다. Blob Storage 컨테이너에 대한 다양한 트리거 옵션에 대한 자세한 내용과 비교는 Blob 컨테이너의 트리거를 참조 하세요.

Blob 영수증

Azure Functions 런타임은 동일한 새 Blob 또는 업데이트된 Blob에 대해 Blob 트리거 함수가 두 번 이상 호출되지 않도록 합니다. 지정된 Blob 버전이 처리되었는지 확인하려면 Blob 수신 확인을 유지 관리합니다.

Azure Functions는 함수 앱(앱 설정AzureWebJobsStorage에 의해 정의됨)에 대한 Azure Storage 계정의 azure-webjobs-hosts라는 컨테이너에 Blob 영수증을 저장합니다. Blob 영수증에는 다음 정보가 있습니다.

트리거된 함수(<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>예제:MyFunctionApp.Functions.CopyBlob)
컨테이너 이름
Blob 형식(BlockBlob 또는 PageBlob)
Blob 이름
ETag(Blob 버전 식별자, 예제:0x8D1DC6E70A277EF)

Blob을 강제로 다시 처리하려면 azure-webjobs-hosts 컨테이너에서 해당 Blob에 대한 Blob 수신을 수동으로 삭제합니다 . 재처리는 즉시 발생하지 않을 수 있지만 나중에 발생하도록 보장됩니다. 즉시 다시 처리하려면 azure-webjobs-hosts/blobscaninfo의 scaninfo Blob을 업데이트할 수 있습니다. 속성 이후에 마지막으로 수정된 타임스탬프가 있는 LatestScan 모든 Blob은 다시 검사됩니다.

포이즌 Blob

지정된 Blob에 대한 Blob 트리거 함수가 실패한 경우 Azure Functions는 기본적으로 총 5번 해당 함수를 다시 시도합니다.

5번 모두 실패하면 Azure Functions는 webjobs-blobtrigger-poison이라는 Storage 큐에 메시지를 추가합니다. 최대 재시도 횟수는 구성할 수 있습니다. 동일한 MaxDequeueCount 설정은 포이즌 Blob 처리 및 포이즌 큐 메시지 처리에 사용됩니다. 포이즌 Blob에 대한 큐 메시지는 다음 속성을 포함하는 JSON 개체입니다.

FunctionId(형식 <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
BlobType(BlockBlob 또는 PageBlob)
ContainerName
BlobName
ETag(Blob 버전 식별자( 예: 0x8D1DC6E70A277EF)

메모리 사용량 및 동시성

스트리밍(예: stringByte[]또는)을 지원하지 않는 출력 형식에 바인딩하는 경우 런타임은 처리 중에 전체 Blob을 메모리에 두 번 이상 로드해야 합니다. 이로 인해 Blob을 처리할 때 예상보다 높은 메모리 사용량이 발생할 수 있습니다. 가능하면 스트림 지원 형식을 사용합니다. 형식 지원은 C# 모드 및 확장 버전에 따라 달라집니다. 자세한 내용은 바인딩 형식을 참조 하세요.

이때 런타임은 처리 중에 전체 Blob을 메모리에 두 번 이상 로드해야 합니다. 이로 인해 Blob을 처리할 때 예상보다 높은 메모리 사용량이 발생할 수 있습니다.

여러 함수 인스턴스가 동시에 Blob 데이터를 처리하는 경우 메모리 사용량에 더 큰 영향을 미칠 수 있습니다. Blob 트리거를 사용하여 메모리 문제가 발생하는 경우 허용되는 동시 실행 수를 줄이는 것이 좋습니다. 물론 동시성을 줄이면 처리되기를 기다리는 Blob의 백로그를 늘리는 부작용이 발생할 수 있습니다. 함수 앱의 메모리 제한은 계획에 따라 달라집니다. 자세한 내용은 서비스 제한을 참조하세요.

동시 실행 수를 제어할 수 있는 방법은 사용 중인 Storage 확장의 버전에 따라 달라집니다.

확장 5.x 이상
사전 확장 5.x

스토리지 확장 버전 5.0.0 이상을 사용하는 경우 host.json Blob 구성의 설정을 사용하여 maxDegreeOfParallelism 트리거 동시성을 제어합니다.

제한은 Blob 트리거를 사용하는 각 함수에 개별적으로 적용됩니다.

host.json 속성

host.json 파일에는 Blob 트리거 동작을 제어하는 설정이 포함됩니다. 사용 가능한 설정에 대한 자세한 내용은 host.json 설정 섹션을 참조하세요.

다음을 통해 공유

Azure Functions에 대한 Azure Blob Storage 트리거

예시

특성

데코레이터

주석

구성

메타데이터

메타데이터

메타데이터

사용

연결

연결 문자열

ID 기반 연결

ID에 권한 부여

Blob 이름 패턴

파일 이름 및 확장명 가져오기

Blob 이름 필터링

파일 형식에 대한 필터링

파일 이름에서 중괄호 필터링

폴링 및 대기 시간

Blob 영수증

포이즌 Blob

메모리 사용량 및 동시성

host.json 속성

다음 단계

피드백

추가 리소스