Azure Functions에 대 한 Azure Blob storage 트리거Azure Blob storage trigger for Azure Functions

Blob Storage 트리거는 신규 또는 업데이트된 Blob를 검색할 때 함수를 시작합니다.The Blob storage trigger starts a function when a new or updated blob is detected. Blob 콘텐츠는 함수에 대 한 입력으로 제공 됩니다.The blob contents are provided as input to the function.

Azure Blob storage 트리거에는 범용 저장소 계정이 필요 합니다.The Azure Blob storage trigger require a general-purpose storage account. Blob 전용 계정을 사용 하거나 응용 프로그램에 특수 한 요구 사항이 있는 경우이 트리거 사용에 대 한 대안을 검토 합니다.To use a blob-only account, or if your application has specialized needs, review the alternatives to using this trigger.

설정 및 구성 세부 정보에 대 한 자세한 내용은 개요를 참조 하세요.For information on setup and configuration details, see the overview.

대안Alternatives

Event Grid 트리거Event Grid trigger

또한 Event Grid 트리거blob 이벤트를 기본적으로 지원 합니다.The Event Grid trigger also has built-in support for blob events. 다음과 같은 시나리오에 대해 Blob Storage 트리거 대신 Event Grid를 사용합니다.Use Event Grid instead of the Blob storage trigger for the following scenarios:

  • Blob 전용 저장소 계정: blob 전용 저장소 계정은 blob 입력 및 출력 바인딩에 대해서는 지원 되지만 blob 트리거에는 지원 되지 않습니다.Blob-only storage accounts: Blob-only storage accounts are supported for blob input and output bindings but not for blob triggers.

  • 높은 규모: 높은 배율은 10만 개 이상의 blob이 포함 된 컨테이너 또는 초당 blob 업데이트가 100 개 이상인 저장소 계정으로 느슨하게 정의 될 수 있습니다.High-scale: High scale can be loosely defined as containers that have more than 100,000 blobs in them or storage accounts that have more than 100 blob updates per second.

  • 대기 시간 최소화: 함수 앱이 소비 계획에 있는 경우 함수 앱이 유휴 상태가 되는 경우 새 blob을 처리 하는 데 최대 10 분까지 지연 될 수 있습니다.Minimizing latency: If your function app is on the Consumption plan, there can be up to a 10-minute delay in processing new blobs if a function app has gone idle. 이 대기 시간을 방지하려면 Always On을 사용하도록 설정한 App Service 계획으로 전환하면 됩니다.To avoid this latency, you can switch to an App Service plan with Always On enabled. Blob Storage 계정으로 Event Grid 트리거를 사용할 수도 있습니다.You can also use an Event Grid trigger with your Blob storage account. 예를 들어 Event Grid 자습서를 참조하세요.For an example, see the Event Grid tutorial.

Event Grid 예제의 이미지 크기 조정 Event Grid 자습서를 참조 하세요.See the Image resize with Event Grid tutorial of an Event Grid example.

Queue Storage 트리거Queue storage trigger

Blob을 처리 하는 또 다른 방법은 만들어지거나 수정 되는 blob에 해당 하는 큐 메시지를 작성 한 다음 queue storage 트리거 를 사용 하 여 처리를 시작 하는 것입니다.Another approach to processing blobs is to write queue messages that correspond to blobs being created or modified and then use a Queue storage trigger to begin processing.

예제Example

다음 예제에서는 컨테이너에서 Blob을 추가하거나 업데이트할 때 로그를 기록하는 C# 함수samples-workitems를 보여줍니다.The following example shows a C# function that writes a log when a blob is added or updated in the samples-workitems container.

[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 트리거 경로 {name}의 문자열 samples-workitems/{name}은 함수 코드에서 사용할 수 있는 바인딩 식을 만들어 트리거 blob의 파일 이름에 액세스합니다.The string {name} in the blob trigger path samples-workitems/{name} creates a binding expression that you can use in function code to access the file name of the triggering blob. 자세한 내용은 이 문서의 뒷부분에 나오는 Blob 이름 패턴을 참조하세요.For more information, see Blob name patterns later in this article.

BlobTrigger 특성에 대 한 자세한 내용은 특성 및 주석을 참조 하세요.For more information about the BlobTrigger attribute, see attributes and annotations.

특성 및 주석Attributes and annotations

C# 클래스 라이브러리에서 다음 특성을 사용하여 Blob 트리거를 구성합니다.In C# class libraries, use the following attributes to configure a blob trigger:

  • BlobTriggerAttributeBlobTriggerAttribute

    특성의 생성자는 조사할 컨테이너 및 선택적으로 Blob 이름 패턴을 나타내는 경로 문자열을 사용합니다.The attribute's constructor takes a path string that indicates the container to watch and optionally a blob name pattern. 예를 들면 다음과 같습니다.Here's an example:

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

    다음 예와 같이 사용할 스토리지 계정을 지정하도록 Connection 속성을 설정할 수 있습니다.You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    전체 예제는 트리거 예를 참조 하세요.For a complete example, see Trigger example.

  • StorageAccountAttributeStorageAccountAttribute

    사용할 스토리지 계정을 지정하는 다른 방법을 제공합니다.Provides another way to specify the storage account to use. 생성자는 스토리지 연결 문자열을 포함하는 앱 설정의 이름을 사용합니다.The constructor takes the name of an app setting that contains a storage connection string. 매개 변수, 메서드 또는 클래스 수준에서 특성을 적용할 수 있습니다.The attribute can be applied at the parameter, method, or class level. 다음 예제에서는 클래스 수준 및 메서드 수준을 보여줍니다.The following example shows class level and method level:

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

사용할 스토리지 계정은 다음과 같은 순서로 결정됩니다.The storage account to use is determined in the following order:

  • BlobTrigger 특성의 Connection 속성The BlobTrigger attribute's Connection property.
  • StorageAccount 특성과 동일한 매개 변수에 적용된 BlobTrigger 특성The StorageAccount attribute applied to the same parameter as the BlobTrigger attribute.
  • 함수에 적용된 StorageAccount 특성The StorageAccount attribute applied to the function.
  • 클래스에 적용된 StorageAccount 특성The StorageAccount attribute applied to the class.
  • 함수 앱의 기본 스토리지 계정("AzureWebJobsStorage" 앱 설정)The default storage account for the function app ("AzureWebJobsStorage" app setting).

구성Configuration

다음 표에서는 function.json 파일 및 BlobTrigger 특성에 설정된 바인딩 구성 속성을 설명합니다.The following table explains the binding configuration properties that you set in the function.json file and the BlobTrigger attribute.

function.json 속성function.json property 특성 속성Attribute property DescriptionDescription
typetype 해당 없음n/a blobTrigger로 설정해야 합니다.Must be set to blobTrigger. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.This property is set automatically when you create the trigger in the Azure portal.
directiondirection 해당 없음n/a in로 설정해야 합니다.Must be set to in. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.This property is set automatically when you create the trigger in the Azure portal. 예외는 사용 섹션에서 표시됩니다.Exceptions are noted in the usage section.
namename 해당 없음n/a 함수 코드에서 Blob을 나타내는 변수의 이름입니다.The name of the variable that represents the blob in function code.
pathpath BlobPathBlobPath 모니터링할 컨테이너입니다.The container to monitor. Blob 이름 패턴일 수 있습니다.May be a blob name pattern.
연결connection 연결Connection 이 바인딩에 사용할 스토리지 연결 문자열을 포함하는 앱 설정의 이름입니다.The name of an app setting that contains the Storage connection string to use for this binding. 앱 설정 이름이 "AzureWebJobs"로 시작하는 경우 여기에서 이름의 나머지만을 지정할 수 있습니다.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. 예를 들어 connection을 "MyStorage"로 설정한 경우 함수 런타임 기능은 "AzureWebJobsMyStorage"라는 앱 설정을 찾습니다.For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." connection을 비워 두면 함수 런타임 기능은 AzureWebJobsStorage라는 앱 설정에서 기본 스토리지 연결 문자열을 사용합니다.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

연결 문자열은 Blob Storage 계정이 아닌 범용 스토리지 계정의 문자열이어야 합니다.The connection string must be for a general-purpose storage account, not a Blob storage account.

로컬로 개발하는 경우 앱 설정은 local.settings.json 파일로 이동합니다.When you're developing locally, app settings go into the local.settings.json file.

사용Usage

트리거Blob에 다음 매개 변수 형식을 사용할 수 있습니다.You can use the following parameter types for the triggering blob:

  • Stream
  • TextReader
  • string
  • Byte[]
  • JSON으로 직렬화 가능한 POCOA POCO serializable as JSON
  • ICloudBlob1ICloudBlob1
  • CloudBlockBlob1CloudBlockBlob1
  • CloudPageBlob1CloudPageBlob1
  • CloudAppendBlob1CloudAppendBlob1

1function.json에서 direction 또는 C# 클래스 라이브러리에서 FileAccess.ReadWrite의 “inout” 바인딩이 필요합니다.1 Requires "inout" binding direction in function.json or FileAccess.ReadWrite in a C# class library.

스토리지 SDK 형식 중 하나에 바인딩하려고 하면 오류 메시지가 표시되는 경우 올바른 Storage SDK 버전에 대한 참조가 있는지 확인합니다.If you try to bind to one of the Storage SDK types and get an error message, make sure that you have a reference to the correct Storage SDK version.

string, Byte[] 또는 POCO에 바인딩하는 방식은 전체 Blob 내용이 메모리에 로드되므로 Blob 크기가 작은 경우에만 권장됩니다.Binding to string, Byte[], or POCO is only recommended if the blob size is small, as the entire blob contents are loaded into memory. 일반적으로 Stream 또는 CloudBlockBlob 형식을 사용하는 것이 좋습니다.Generally, it is preferable to use a Stream or CloudBlockBlob type. 자세한 내용은 이 문서의 뒷부분에 나오는 동시성 및 메모리 사용량을 참조하세요.For more information, see Concurrency and memory usage later in this article.

Blob 이름 패턴Blob name patterns

pathfunction.json 속성 또는 BlobTrigger 특성 생성자에서 Blob 이름 패턴을 지정할 수 있습니다.You can specify a blob name pattern in the path property in function.json or in the BlobTrigger attribute constructor. 이름 패턴은 필터 또는 바인딩 식일 수 있습니다.The name pattern can be a filter or binding expression. 다음 섹션에서는 예제를 제공합니다.The following sections provide examples.

파일 이름 및 확장명 가져오기Get file name and extension

다음 예제에서는 Blob 파일 이름 및 확장명에 별도로 바인딩하는 방법을 보여줍니다.The following example shows how to bind to the blob file name and extension separately:

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

Blob이 original-Blob1.txt인 경우 함수 코드에 있는 blobnameblobextension 변수의 값은 original-Blob1txt입니다.If the blob is named original-Blob1.txt, the values of the blobname and blobextension variables in function code are original-Blob1 and txt.

Blob 이름에 대한 필터링Filter on blob name

다음 예제는 "original-" 문자열로 시작하는 input 컨테이너에 있는 Blob에서만 트리거됩니다.The following example triggers only on blobs in the input container that start with the string "original-":

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

Blob 이름이 original-Blob1.txt인 경우 함수 코드에 있는 name 변수의 값은 Blob1입니다.If the blob name is original-Blob1.txt, the value of the name variable in function code is Blob1.

파일 형식에 대한 필터링Filter on file type

다음 예제는 .png 파일에서만 트리거됩니다.The following example triggers only on .png files:

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

파일 이름에서 중괄호에 대한 필터링Filter on curly braces in file names

파일 이름에서 중괄호를 찾으려면 2개의 중괄호를 사용하여 중괄호를 이스케이프합니다.To look for curly braces in file names, escape the braces by using two braces. 다음 예제는 중괄호가 이름에 포함된 Blob에 대해서만 필터링됩니다.The following example filters for blobs that have curly braces in the name:

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

Blob의 이름이 {20140101}-soundfile.mp3인 경우 함수 코드에서 name 변수 값은 soundfile.mp3입니다.If the blob is named {20140101}-soundfile.mp3, the name variable value in the function code is soundfile.mp3.

메타데이터Metadata

Blob 트리거는 몇 가지 메타데이터 속성을 제공합니다.The blob trigger provides several metadata properties. 이러한 속성을 다른 바인딩에서 바인딩 식의 일부로 사용하거나 코드에서 매개 변수로 사용할 수 있습니다.These properties can be used as part of binding expressions in other bindings or as parameters in your code. 이러한 값은 CloudBlob 형식과 동일한 의미 체계를 가집니다.These values have the same semantics as the CloudBlob type.

속성Property TypeType DescriptionDescription
BlobTrigger string Blob을 트리거하는 경로입니다.The path to the triggering blob.
Uri System.Uri 기본 위치에 대한 Blob의 URI입니다.The blob's URI for the primary location.
Properties BlobPropertiesBlobProperties Blob의 시스템 속성입니다.The blob's system properties.
Metadata IDictionary<string,string> Blob에 대한 사용자 정의 메타데이터입니다.The user-defined metadata for the blob.

예를 들어, 다음 C# 스크립트 및 JavaScript 예제는 컨테이너를 포함하는 트리거 Blob의 경로를 로깅합니다.For example, the following C# script and JavaScript examples log the path to the triggering blob, including the container:

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

Blob 수신 확인Blob receipts

Azure Functions 런타임은 동일한 새 Blob 또는 업데이트된 Blob에 대해 Blob 트리거 함수가 두 번 이상 호출되지 않도록 합니다.The Azure Functions runtime ensures that no blob trigger function gets called more than once for the same new or updated blob. 지정된 Blob 버전이 처리되었는지 확인하려면 Blob 수신 확인을 유지 관리합니다.To determine if a given blob version has been processed, it maintains blob receipts.

Azure Functions는 사용자 함수 앱에서 사용하는(앱 설정에서 지정됨) Azure Storage 계정의azure-webjobs-hostsAzureWebJobsStorage라는 컨테이너에 Blob 수신 확인을 저장합니다.Azure Functions stores blob receipts in a container named azure-webjobs-hosts in the Azure storage account for your function app (defined by the app setting AzureWebJobsStorage). Blob 수신 확인에는 다음 정보가 포함됩니다.A blob receipt has the following information:

  • 트리거된 함수(" <함수 앱 이름> .Functions. <함수 이름> ", 예: "MyFunctionApp.Functions.CopyBlob")The triggered function ("<function app name>.Functions.<function name>", for example: "MyFunctionApp.Functions.CopyBlob")
  • 컨테이너 이름The container name
  • Blob 유형("BlockBlob" 또는 "PageBlob")The blob type ("BlockBlob" or "PageBlob")
  • Blob 이름The blob name
  • ETag(Blob 버전 식별자, 예: "0x8D1DC6E70A277EF")The ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Blob을 강제로 처리하려면 azure-webjobs-hosts 컨테이너에서 해당 Blob에 대한 Blob 수신 확인을 수동으로 삭제하면 됩니다.To force reprocessing of a blob, delete the blob receipt for that blob from the azure-webjobs-hosts container manually. 다시 처리는 즉시 발생 하지 않을 수 있지만 나중에 발생 하는 것이 보장 됩니다.While reprocessing might not occur immediately, it's guaranteed to occur at a later point in time.

포이즌 blobPoison blobs

지정된 Blob에 대한 Blob 트리거 함수가 실패한 경우 Azure Functions는 기본적으로 총 5번 해당 함수를 다시 시도합니다.When a blob trigger function fails for a given blob, Azure Functions retries that function a total of 5 times by default.

5번 모두 실패한 경우 Azure Functions는 webjobs-blobtrigger-poison이라는 스토리지 큐에 메시지를 추가합니다.If all 5 tries fail, Azure Functions adds a message to a Storage queue named webjobs-blobtrigger-poison. 포이즌 Blob에 대한 큐 메시지는 다음 속성을 포함하는 JSON 개체입니다.The queue message for poison blobs is a JSON object that contains the following properties:

  • FunctionId(형식에서 <함수 앱 이름> .Functions. <함수 이름> )FunctionId (in the format <function app name>.Functions.<function name>)
  • BlobType("BlockBlob" 또는 "PageBlob")BlobType ("BlockBlob" or "PageBlob")
  • ContainerNameContainerName
  • BlobNameBlobName
  • ETag(Blob 버전 식별자, 예: "0x8D1DC6E70A277EF")ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

동시성 및 메모리 사용량Concurrency and memory usage

Blob 트리거는 큐를 내부적으로 사용하므로 동시 함수 호출의 최대 수는 host.json의 큐 구성에 의해 제어됩니다.The blob trigger uses a queue internally, so the maximum number of concurrent function invocations is controlled by the queues configuration in host.json. 기본 설정은 동시성을 24 호출로 제한합니다.The default settings limit concurrency to 24 invocations. 이 제한은 Blob 트리거를 사용하는 각 함수에 개별적으로 적용됩니다.This limit applies separately to each function that uses a blob trigger.

소비 계획은 하나의 VM (가상 머신)에서 1.5 GB의 메모리로 함수 앱을 제한 합니다.The Consumption plan limits a function app on one virtual machine (VM) to 1.5 GB of memory. 메모리는 각각 동시에 함수 인스턴스를 실행하여 함수 런타임 자체에서 사용됩니다.Memory is used by each concurrently executing function instance and by the Functions runtime itself. Blob 트리거된 함수에서 전체 Blob을 메모리로 로드하는 경우 Blob에 대해 해당 함수에서 사용되는 최대 메모리는 24 * 최대 Blob 크기입니다.If a blob-triggered function loads the entire blob into memory, the maximum memory used by that function just for blobs is 24 * maximum blob size. 예를 들어 세 개의 Blob 트리거된 함수 및 기본 설정이 있는 함수 앱은 3*24 = 72 함수 호출의 최대 VM당 동시성을 갖습니다.For example, a function app with three blob-triggered functions and the default settings would have a maximum per-VM concurrency of 3*24 = 72 function invocations.

JavaScript 및 Java 함수는 전체 Blob을 메모리에 로드하고 C# 함수는 string, Byte[] 또는 POCO로 바인딩하는 경우 로드합니다.JavaScript and Java functions load the entire blob into memory, and C# functions do that if you bind to string, Byte[], or POCO.

폴링Polling

폴링은 로그 검사와 정기적인 컨테이너 검색 실행 간의 하이브리드 방식으로 작동 합니다.Polling works as a hybrid between inspecting logs and running periodic container scans. Blob은 간격 간에 사용 되는 연속 토큰을 사용 하 여 한 번에 1만 그룹으로 스캔 됩니다.Blobs are scanned in groups of 10,000 at a time with a continuation token used between intervals.

경고

또한 스토리지 로그는 "최선을 다해" 생성됩니다.In addition, storage logs are created on a "best effort" basis. 하지만 모든 이벤트가 캡처되는 것은 아닙니다.There's no guarantee that all events are captured. 경우에 따라 로그가 누락될 수 있습니다.Under some conditions, logs may be missed.

더 빠르거나 안정적인 Blob 처리가 필요한 경우 Blob을 만들 때 큐 메시지를 만드는 것이 좋습니다.If you require faster or more reliable blob processing, consider creating a queue message when you create the blob. 그런 다음 Blob 트리거 대신 큐 트리거를 사용하여 Blob을 처리합니다.Then use a queue trigger instead of a blob trigger to process the blob. 다른 옵션은 Event Grid를 사용하는 겻입니다. Event Grid를 사용하여 업로드된 이미지 크기 자동 조정 자습서를 참조하세요.Another option is to use Event Grid; see the tutorial Automate resizing uploaded images using Event Grid.

다음 단계Next steps