Azure Functions에 대한 Azure Blob Storage 출력 바인딩
출력 바인딩을 사용하면 Azure Function에서 Blob Storage 데이터를 수정하고 삭제할 수 있습니다.
설정 및 구성 세부 정보에 대한 자세한 내용은 개요를 참조하세요.
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일에 종료됩니다. 전체 지원을 위해 앱을 격리된 작업자 모델로 마이그레이션하는 것이 좋습니다.
다음 예는 격리된 작업자 프로세스에서 실행되고 blob 입력 및 blob 출력 blob 바인딩과 함께 blob 트리거를 사용하는 C# 함수입니다. 함수는 test-samples-trigger 컨테이너에서 blob을 만들어 트리거됩니다. test-samples-input 컨테이너에서 텍스트 파일을 읽고 트리거된 파일의 이름을 기반으로 출력 컨테이너에 새 텍스트 파일을 만듭니다.
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
namespace SampleApp
{
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";
}
}
}
이 섹션에는 다음 예제가 포함되어 있습니다.
HTTP 트리거, OutputBinding 사용(Java)
다음 예제에서는 주석을 사용하여 HttpTrigger
Blob Storage 컨테이너에 있는 파일의 이름을 포함하는 매개 변수를 수신하는 Java 함수를 보여 줍니다. 그런 다음 주석은 BlobInput
파일을 읽고 해당 내용을 함수에 로 byte[]
전달합니다. 주석은 BlobOutput
바인딩 OutputBinding outputItem
됩니다. 그러면 함수에서 입력 Blob의 내용을 구성된 스토리지 컨테이너에 쓰는 데 사용됩니다.
@FunctionName("copyBlobHttp")
@StorageAccount("Storage_Account_Connection_String")
public HttpResponseMessage copyBlobHttp(
@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,
@BlobOutput(
name = "target",
path = "myblob/{Query.file}-CopyViaHttp")
OutputBinding<String> outputItem,
final ExecutionContext context) {
// Save blob to outputItem
outputItem.setValue(new String(content, StandardCharsets.UTF_8));
// 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();
}
함수 반환 값을 사용하는 큐 트리거(Java)
다음 예제에서는 주석을 사용하여 QueueTrigger
Blob Storage 컨테이너에 있는 파일의 이름이 포함된 메시지를 수신하는 Java 함수를 보여 줍니다. 그런 다음 주석은 BlobInput
파일을 읽고 해당 내용을 함수에 로 byte[]
전달합니다. BlobOutput
주석은 함수 반환 값에 바인딩되고, 이는 입력 Blob의 콘텐츠를 구성된 스토리지 컨테이너에 쓰기 위해 런타임에서 사용됩니다.
@FunctionName("copyBlobQueueTrigger")
@StorageAccount("Storage_Account_Connection_String")
@BlobOutput(
name = "target",
path = "myblob/{queueTrigger}-Copy")
public String copyBlobQueue(
@QueueTrigger(
name = "filename",
dataType = "string",
queueName = "myqueue-items")
String filename,
@BlobInput(
name = "file",
path = "samples-workitems/{queueTrigger}")
String content,
final ExecutionContext context) {
context.getLogger().info("The content of \"" + filename + "\" is: " + content);
return content;
}
Java 함수 런타임 라이브러리에서 Blob Storage의 @BlobOutput
개체에 값을 쓸 함수 매개 변수에 주석을 사용합니다. 매개 변수 형식은 OutputBinding<T>
이어야 합니다. 여기서 T
는 원시 Java 형식 또는 POJO입니다.
다음 예제에서는 Blob의 복사본을 만드는 큐 트리거 TypeScript 함수를 보여 줍니다. 함수는 복사할 Blob의 이름을 포함하는 큐 메시지에 의해 트리거됩니다. 새 Blob의 이름은 {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,
});
다음 예제에서는 Blob의 복사본을 만드는 큐 트리거 JavaScript 함수를 보여 줍니다. 함수는 복사할 Blob의 이름을 포함하는 큐 메시지에 의해 트리거됩니다. 새 Blob의 이름은 {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);
},
});
다음 예에서는 PowerShell 함수의 출력으로 들어오는 BLOB의 복사본을 만드는 방법을 보여줍니다.
함수의 구성 파일(function.json) trigger
에서 메타데이터 속성은 속성에서 path
출력 Blob 이름을 지정하는 데 사용됩니다.
참고 항목
무한 루프를 방지하려면 입력 및 출력 경로가 다른지 확인합니다.
{
"bindings": [
{
"name": "myInputBlob",
"path": "data/{trigger}",
"connection": "MyStorageConnectionAppSetting",
"direction": "in",
"type": "blobTrigger"
},
{
"name": "myOutputBlob",
"type": "blob",
"path": "data/copy/{trigger}",
"connection": "MyStorageConnectionAppSetting",
"direction": "out"
}
],
"disabled": false
}
PowerShell 코드는 다음과 같습니다.
# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob
다음 예제에서는 Blob 입력 및 출력 바인딩을 보여 줍니다. 이 예제는 v1 또는 v2 Python 프로그래밍 모델을 사용하는지 여부에 따라 달라집니다.
이 코드는 Blob의 복사본을 만듭니다.
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"
특성
In Process 및 격리된 작업자 프로세스 C# 라이브러리는 모두 특성을 사용하여 함수를 정의합니다. 대신 C# 스크립트는 C# 스크립팅 가이드에 설명된 대로 function.json 구성 파일을 사용합니다.
BlobOutputAttribute
생성자는 다음 매개 변수를 사용합니다.
매개 변수 | 설명 |
---|---|
BlobPath | Blob에 대한 경로입니다. |
Connection | Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요. |
로컬에서 개발하는 경우 Values
컬렉션의 local.settings.json 파일에 애플리케이션 설정을 추가합니다.
데코레이터
Python v2 프로그래밍 모델에만 적용됩니다.
데코레이터를 사용하여 정의된 Python v2 함수의 경우 데코레이터 및 blob_output
데코레이터의 blob_input
다음 속성은 Blob Storage 트리거를 정의합니다.
속성 | 설명 |
---|---|
arg_name |
함수 코드에서 Blob을 나타내는 변수의 이름입니다. |
path |
Blob에 대한 경로입니다. 데코레이터의 경우 blob_input 읽은 Blob입니다. 데코레이터의 blob_output 경우 입력 Blob의 출력 또는 복사본입니다. |
connection |
스토리지 계정 연결 문자열. |
dataType |
동적으로 형식화된 언어의 경우 기본 데이터 형식을 지정합니다. 가능한 값은 string , binary 또는 stream 입니다. 자세한 내용은 트리거 및 바인딩 개념을 참조하세요. |
function.json 사용하여 정의된 Python 함수는 구성 섹션을 참조하세요.
주석
이 @BlobOutput
특성을 사용하면 함수를 트리거한 Blob에 액세스할 수 있습니다. 특성과 함께 바이트 배열을 사용하는 경우 .로 설정합니다 dataType
binary
. 자세한 내용은 출력 예제를 참조하세요.
구성
Python v1 프로그래밍 모델에만 적용됩니다.
다음 표에서는 function.json 파일에 설정된 바인딩 구성 속성을 설명합니다.
속성 | 설명 |
---|---|
type | blob 로 설정해야 합니다. |
direction | 출력 바인딩에 대해 out 로 설정해야 합니다. 예외는 사용 섹션에 나와 있습니다. |
이름 | 함수 코드에서 Blob을 나타내는 변수의 이름입니다. $return 으로 설정하여 함수 반환 값을 참조합니다. |
path | BLOB 컨테이너에 대한 경로입니다. |
connection | Azure Blob에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요. |
전체 예제는 예제 섹션을 참조하세요.
사용
Blob 출력에서 지원하는 바인딩 형식은 함수 앱에서 사용되는 확장 패키지 버전 및 C# 양식에 따라 다릅니다.
함수가 단일 Blob에 쓰도록 하려는 경우 Blob 출력 바인딩을 다음 형식에 바인딩할 수 있습니다.
Type | 설명 |
---|---|
string |
Blob 콘텐츠를 문자열로 지정입니다. Blob 콘텐츠가 간단한 텍스트인 경우에 사용합니다. |
byte[] |
Blob 콘텐츠의 바이트입니다. |
JSON 직렬화 가능 형식 | JSON Blob의 콘텐츠를 나타내는 개체입니다. Functions는 POCO(Plain Old CLR Object) 형식을 JSON 데이터로 직렬화하려고 시도합니다. |
함수가 여러 Blob에 쓰도록 하려는 경우 Blob 출력 바인딩을 다음 형식에 바인딩할 수 있습니다.
Type | 설명 |
---|---|
T[] 여기서 T 는 단일 Blob 출력 바인딩 형식 중 하나입니다. |
여러 Blob에 대한 콘텐츠를 포함하는 배열입니다. 각 항목은 하나의 Blob의 콘텐츠를 나타냅니다. |
다른 출력 시나리오의 경우 Azure.Storage.Blobs의 다른 형식과 함께 BlobClient 또는 BlobContainerClient를 직접 만들고 사용합니다. 종속성 주입을 사용하여 Azure SDK에서 클라이언트 형식을 만드는 예제는 Azure 클라이언트 등록을 참조하세요.
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
애플리케이션 설정에 정의된 함수 앱의 기본 스토리지 계정입니다.
이 @BlobOutput
특성을 사용하면 함수를 트리거한 Blob에 액세스할 수 있습니다. 특성과 함께 바이트 배열을 사용하는 경우 .로 설정합니다 dataType
binary
. 자세한 내용은 출력 예제를 참조하세요.
function.json 파일에서 바인딩의 이름 매개 변수로 지정된 이름과 일치하는 매개 변수를 통해 Blob 데이터에 액세스합니다.
함수 매개 변수를 다음 형식으로 선언하여 Blob Storage에 쓸 수 있습니다.
- 문자열을 로
func.Out[str]
- 스트림:
func.Out[func.InputStream]
자세한 내용은 출력 예제를 참조하세요.
연결
connection
속성은 앱이 Azure Blob에 연결해야 하는 방법을 지정하는 환경 구성에 대한 참조입니다. 다음을 지정할 수 있습니다.
구성된 값이 단일 설정에 대해 정확히 일치하고 다른 설정에 대해 접두사가 일치하는 경우 정확한 일치가 사용됩니다.
Connection string
연결 문자열을 가져오려면 스토리지 계정 액세스 키 관리에 표시된 단계를 따릅니다. 연결 문자열 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 1 |
HTTPS 체계를 사용하여 연결 중인 Blob 서비스의 데이터 평면 URI입니다. | https://<storage_account_name>.blob.core.windows.net |
1 <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 트리거에 필요2) | <CONNECTION_NAME_PREFIX>__queueServiceUri |
HTTPS 체계를 사용하는 큐 서비스의 데이터 평면 URI입니다. 이 값은 Blob 트리거에만 필요합니다. | https://<storage_account_name>.queue.core.windows.net |
2 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 데이터 소유자 및 스토리지 큐 데이터 기여자1 AzureWebJobsStorage 연결에도 추가 권한을 부여해야 합니다.2 |
입력 바인딩 | Storage Blob 데이터 읽기 권한자 |
출력 바인딩 | Storage Blob 데이터 소유자 |
1 Blob 트리거는 연결에 의해 지정된 스토리지 계정의 큐에 포이즌 Blob을 작성하여 여러 다시 시도에서 실패를 처리합니다.
2 AzureWebJobsStorage 연결은 트리거를 사용하도록 설정하는 Blob 및 큐에 내부적으로 사용됩니다. ID 기반 연결을 사용하도록 구성된 경우 기본 요구 사항 이상의 추가 권한이 필요합니다. 필요한 권한은 Storage Blob 데이터 소유자, Storage 큐 데이터 기여자 및 Storage 계정 기여자 역할에서 다룹니다. 자세한 내용은 ID로 호스트 스토리지에 연결을 참조하세요.
예외 및 반환 코드
바인딩 | 참조 |
---|---|
Blob | Blob 오류 코드 |
Blob, 테이블, 큐 | 스토리지 오류 코드 |
Blob, 테이블, 큐 | 문제 해결 |