Azure Functions 2.x 이상에 대한 Azure Cosmos DB 입력 바인딩

  • 아티클

Azure Cosmos DB 입력 바인딩은 SQL API를 사용하여 하나 이상의 Azure Cosmos DB 문서를 검색하고, 함수의 입력 매개 변수에 전달합니다. 문서 ID 또는 쿼리 매개 변수는 함수를 호출하는 트리거를 기반으로 결정할 수 있습니다.

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

참고 항목

컬렉션이 분할된 경우, 조회 작업에 파티션 키 값도 지정해야 합니다.

Important

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

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

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

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

예시

달리 명시하지 않는 한 이 문서의 예제는 Azure Cosmos DB 확장의 버전 3.x를 대상으로 합니다. 확장 버전 4.x와 함께 사용하려면 속성 및 특성 이름의 문자열 collection을 container로 바꿔야 합니다.

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

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

이 섹션에는 Azure Cosmos DB 확장 버전 3.x와 Azure Storage 확장 버전 5.x가 필요한 예제가 포함되어 있습니다. 함수 앱에 아직 없는 경우 다음 NuGet 패키지에 대한 참조를 추가합니다.

예제는 간단한 ToDoItem 형식을 참조합니다.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

큐 트리거, JSON에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 함수를 보여줍니다. 함수는 스토리지 큐의 JSON 메시지에 의해 트리거됩니다. 큐 트리거는 검색할 ID 및 파티션 키 값을 포함하는 ToDoItemLookup 형식의 개체로 JSON을 구문 분석합니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 반환하는 데 해당 ID와 파티션 키 값이 사용됩니다.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

이 섹션에는 다음 예제가 포함되어 있습니다.

예제는 간단한 ToDoItem 형식을 참조합니다.

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

HTTP 트리거, 쿼리 문자열에서 ID 조회 - 문자열 매개 변수

다음 예제에서는 단일 문서를 검색하는 Java 함수를 보여 줍니다. 이 함수는 쿼리 문자열을 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 해당 ID와 파티션 키 값은 지정된 데이터베이스 및 컬렉션에서 문자열 형식의 문서를 검색하는 데 사용됩니다.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Java 함수 런타임 라이브러리에서 값이 Azure Cosmos DB에서 제공되는 함수 매개 변수에 대한 @CosmosDBInput 주석을 사용합니다. 이 주석은 을 사용하여 네이티브 Java 형식, POJO 또는 nullable 값과 함께 사용할 Optional<T>수 있습니다.

HTTP 트리거, 쿼리 문자열에서 ID 조회 - POJO 매개 변수

다음 예제에서는 단일 문서를 검색하는 Java 함수를 보여 줍니다. 이 함수는 쿼리 문자열을 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 문서를 검색하는 데 사용되는 ID 및 파티션 키 값입니다. 그런 다음 문서는 이전에 만든 POJO의 ToDoItem 인스턴스로 변환되고 함수에 인수로 전달됩니다.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP 트리거, 경로 데이터에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 Java 함수를 보여 줍니다. 이 함수는 경로 매개 변수를 사용하여 조회할 ID와 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 해당 ID 및 파티션 키 값은 지정된 데이터베이스 및 컬렉션에서 문서를 검색하여 반환하는 Optional<String>데 사용됩니다.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

HTTP 트리거, SqlQuery를 사용하여 경로 데이터에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 Java 함수를 보여 줍니다. 이 함수는 조회할 ID를 지정하기 위해 경로 매개 변수를 사용하는 HTTP 요청에 의해 트리거됩니다. 이 ID는 쿼리 조건에 따라 많은 문서가 반환될 수 있으므로 지정된 데이터베이스 및 컬렉션에서 문서를 검색하여 결과 집합을 a ToDoItem[]로 변환하는 데 사용됩니다.

참고 항목

ID로만 쿼리해야 하는 경우 이전 예제와 같이 조회를 사용하는 것이 좋습니다. 요청 단위가 적기 때문에 조회를 사용하는 것이 좋습니다. GET(지점 읽기 작업)은 ID별 쿼리보다 더 효율적입니다.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP 트리거, SqlQuery를 사용하여 경로 데이터에서 여러 문서 가져오기

다음 예제에서는 여러 문서를 검색하는 Java 함수를 보여 줍니다. 이 함수는 경로 매개 변수 desc 를 사용하여 필드에서 검색 description 할 문자열을 지정하는 HTTP 요청에 의해 트리거됩니다. 검색 용어는 지정된 데이터베이스 및 컬렉션에서 문서 컬렉션을 검색하여 결과 집합을 a ToDoItem[] 로 변환하고 함수에 인수로 전달하는 데 사용됩니다.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

이 섹션에는 다양한 원본에서 ID 값을 지정하여 단일 문서를 읽는 다음 예제가 포함되어 있습니다.

큐 트리거, JSON에서 ID 조회

다음 예제에서는 단일 문서를 읽고 문서의 텍스트 값을 업데이트하는 TypeScript 함수를 보여 줍니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

HTTP 트리거, 쿼리 문자열에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 TypeScript 함수를 보여줍니다. 이 함수는 쿼리 문자열을 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

HTTP 트리거, 경로 데이터에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 TypeScript 함수를 보여줍니다. 이 함수는 경로 데이터를 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

큐 트리거, 여러 문서 가져오기, SqlQuery 사용

다음 예제는 큐 트리거를 사용하여 쿼리 매개 변수를 사용자 지정하여 SQL 쿼리로 지정된 여러 문서를 도출하는 TypeScript 함수를 보여줍니다.

큐 트리거는 매개 변수 departmentId를 제공합니다. { "departmentId" : "Finance" }의 큐 메시지는 재무 부서에 대한 모든 레코드를 반환합니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

이 섹션에는 다양한 원본에서 ID 값을 지정하여 단일 문서를 읽는 다음 예제가 포함되어 있습니다.

큐 트리거, JSON에서 ID 조회

다음 예제에서는 단일 문서를 읽고 문서의 텍스트 값을 업데이트하는 JavaScript 함수를 보여 줍니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

HTTP 트리거, 쿼리 문자열에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 JavaScript 함수를 보여줍니다. 이 함수는 쿼리 문자열을 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

HTTP 트리거, 경로 데이터에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 JavaScript 함수를 보여줍니다. 이 함수는 경로 데이터를 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

큐 트리거, 여러 문서 가져오기, SqlQuery 사용

다음 예제는 큐 트리거를 사용하여 쿼리 매개 변수를 사용자 지정하여 SQL 쿼리로 지정된 여러 문서를 도출하는 JavaScript 함수를 보여줍니다.

큐 트리거는 매개 변수 departmentId를 제공합니다. { "departmentId" : "Finance" }의 큐 메시지는 재무 부서에 대한 모든 레코드를 반환합니다.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

큐 트리거, JSON에서 ID 조회

다음 예제에서는 단일 Azure Cosmos DB 문서를 읽고 업데이트하는 방법을 보여 줍니다. 문서의 고유 식별자는 큐 메시지의 JSON 값을 통해 제공됩니다.

Azure Cosmos DB 입력 바인딩은 함수의 구성 파일(function.js)에 있는 바인딩 목록에서 먼저 나열됩니다.

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

run.ps1 파일에는 들어오는 문서를 읽고 변경 내용을 출력하는 PowerShell 코드가 있습니다.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

HTTP 트리거, 쿼리 문자열에서 ID 조회

다음 예제에서는 웹 API에서 단일 Azure Cosmos DB 문서를 읽고 업데이트하는 방법을 보여 줍니다. 문서의 고유 식별자는 바인딩의 속성에 정의된 대로 HTTP 요청의 "Id": "{Query.Id}" 쿼리 문자열 매개 변수를 통해 제공됩니다.

Azure Cosmos DB 입력 바인딩은 함수의 구성 파일(function.js)에 있는 바인딩 목록에서 먼저 나열됩니다.

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

run.ps1 파일에는 들어오는 문서를 읽고 변경 내용을 출력하는 PowerShell 코드가 있습니다.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

HTTP 트리거, 경로 데이터에서 ID 조회

다음 예제에서는 웹 API에서 단일 Azure Cosmos DB 문서를 읽고 업데이트하는 방법을 보여 줍니다. 문서의 고유 식별자는 경로 매개 변수를 통해 제공됩니다. 경로 매개 변수는 HTTP 요청 바인딩의 route 속성에 정의되고 Azure Cosmos DB "Id": "{Id}" 바인딩 속성에서 참조됩니다.

Azure Cosmos DB 입력 바인딩은 함수의 구성 파일(function.js)에 있는 바인딩 목록에서 먼저 나열됩니다.

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

run.ps1 파일에는 들어오는 문서를 읽고 변경 내용을 출력하는 PowerShell 코드가 있습니다.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

큐 트리거, 여러 문서 가져오기, SqlQuery 사용

다음 예제에서는 여러 Azure Cosmos DB 문서를 읽는 방법에 대해 설명합니다. 함수의 구성 파일(function.json)은 바인딩 속성을 정의합니다. 여기에는 다음이 sqlQuery포함됩니다. sqlQuery 속성에 제공된 SQL 문은 함수에 제공된 문서 집합을 선택합니다.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

이 run1.ps1 파일에는 들어오는 문서를 읽는 PowerShell 코드가 있습니다.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

이 섹션에는 다양한 원본에서 ID 값을 지정하여 단일 문서를 읽는 다음 예제가 포함되어 있습니다.

예제는 v1 또는 v2 Python 프로그래밍 모델을 사용하는지 여부에 따라 달라집니다.

큐 트리거, JSON에서 ID 조회

다음 예제에서는 Azure Cosmos DB 입력 바인딩을 보여 줍니다. 이 함수는 단일 문서를 읽고 문서의 텍스트 값을 업데이트합니다.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

HTTP 트리거, 쿼리 문자열에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 함수를 보여줍니다. 이 함수는 쿼리 문자열을 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

현재 v2에 해당하는 샘플이 없습니다.

HTTP 트리거, 경로 데이터에서 ID 조회

다음 예제에서는 단일 문서를 검색하는 함수를 보여줍니다. 이 함수는 경로 데이터를 사용하여 조회할 ID 및 파티션 키 값을 지정하는 HTTP 요청에 의해 트리거됩니다. 지정된 데이터베이스 및 컬렉션에서 ToDoItem 문서를 검색하는 데 해당 ID와 파티션 키 값이 사용됩니다.

현재 v2에 해당하는 샘플이 없습니다.

큐 트리거, 여러 문서 가져오기, SqlQuery 사용

다음 예제에서는 바인딩을 사용하는 Azure Cosmos DB 입력 바인딩 Python 함수를 보여 줍니다. 이 함수는 큐 트리거를 사용하여 쿼리 매개 변수를 사용자 지정하여 SQL 쿼리로 지정된 여러 문서를 검색합니다.

큐 트리거는 매개 변수 departmentId를 제공합니다. { "departmentId" : "Finance" }의 큐 메시지는 재무 부서에 대한 모든 레코드를 반환합니다.

현재 v2에 해당하는 샘플이 없습니다.

특성

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

특성 속성 설명
Connection 쿼리 중인 Azure Cosmos DB 계정에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 자세한 내용은 연결을 참조하세요.
DatabaseName 컨테이너가 모니터링되는 Azure Cosmos DB 데이터베이스의 이름입니다.
ContainerName 모니터링되는 컨테이너의 이름입니다.
PartitionKey 조회를 위한 파티션 키 값을 지정합니다. 바인딩 매개 변수가 포함될 수 있습니다. 이는 분할된 컨테이너에서 조회 작업을 하는 데 필요합니다.
ID 검색할 문서의 ID입니다. 이 속성은 바인딩 식을 지원합니다. Id 및 SqlQuery 속성을 모두 설정하지 마세요. 둘 중 하나를 설정하지 않으면 전체 컨테이너가 검색됩니다.
SqlQuery 여러 문서를 검색하는 데 사용되는 Azure Cosmos DB SQL 쿼리입니다. 이 속성은 런타임 바인딩을 지원합니다(예: SELECT * FROM c where c.departmentId = {departmentId}). Id 및 SqlQuery 속성을 모두 설정하지 마세요. 둘 중 하나를 설정하지 않으면 전체 컨테이너가 검색됩니다.
PreferredLocations (선택 사항) Azure Cosmos DB 서비스에서 지역 복제된 데이터베이스 계정에 대한 기본 위치(지역)를 정의합니다. 값은 쉼표로 구분해야 합니다. 예들 들어 East US,South Central US,North Europe입니다.

데코레이터

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

데코레이터를 사용하여 정의된 Python v2 함수의 경우 다음 속성은 cosmos_db_input다음과 같습니다.

속성 설명
arg_name 변경 사항이 포함된 문서 목록을 나타내는 함수 코드에 사용되는 변수 이름.
database_name 모니터링 중인 컬렉션이 있는 Azure Cosmos DB 데이터베이스의 이름입니다.
collection_name 모니터링 중인 Azure Cosmos DB 컬렉션의 이름입니다.
connection_string_setting 모니터링되는 Azure Cosmos DB의 연결 문자열.
partition_key 모니터링 중인 Azure Cosmos DB의 파티션 키입니다.
id 검색할 문서의 ID입니다.

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

주석

Java 함수 런타임 라이브러리에서 Azure Cosmos DB에서 읽는 매개 변수에 대해 @CosmosDBInput 주석을 사용합니다. 주석은 다음 속정을 지원합니다.

구성

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

다음 표에서는 input.cosmosDB() 메서드에 전달된 options 개체에 설정할 수 있는 속성에 대해 설명합니다. type, direction 및 name 속성은 v4 모델에 적용되지 않습니다.

다음 표에서는 확장 버전에 따라 속성이 다른 function.json 파일에서 설정한 바인딩 구성 속성을 설명합니다.

function.json 속성 설명
type cosmosDB로 설정해야 합니다.
direction in로 설정해야 합니다.
이름 변경 사항이 포함된 문서 목록을 나타내는 함수 코드에 사용되는 변수 이름.
connection 모니터링 중인 Azure Cosmos DB 계정에 연결하는 방법을 지정하는 앱 설정 또는 설정 컨테이너의 이름입니다. 자세한 내용은 연결을 참조하세요.
databaseName 컨테이너가 모니터링되는 Azure Cosmos DB 데이터베이스의 이름입니다.
containerName 모니터링되는 컨테이너의 이름입니다.
partitionKey 조회를 위한 파티션 키 값을 지정합니다. 바인딩 매개 변수가 포함될 수 있습니다. 이는 분할된 컨테이너에서 조회 작업을 하는 데 필요합니다.
id 검색할 문서의 ID입니다. 이 속성은 바인딩 식을 지원합니다. id 및 sqlQuery 속성을 모두 설정하지 마세요. 둘 중 하나를 설정하지 않으면 전체 컨테이너가 검색됩니다.
sqlQuery 여러 문서를 검색하는 데 사용되는 Azure Cosmos DB SQL 쿼리입니다. 이 속성은 런타임 바인딩을 지원합니다(예: SELECT * FROM c where c.departmentId = {departmentId}). id 및 sqlQuery 속성을 모두 설정하지 마세요. 둘 중 하나를 설정하지 않으면 전체 컨테이너가 검색됩니다.
preferredLocations (선택 사항) Azure Cosmos DB 서비스에서 지역 복제된 데이터베이스 계정에 대한 기본 위치(지역)를 정의합니다. 값은 쉼표로 구분해야 합니다. 예들 들어 East US,South Central US,North Europe입니다.

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

사용

함수가 성공적으로 종료되면 입력 문서에 대한 변경 사항이 자동으로 유지됩니다.

Cosmor DB 입력 바인딩에서 지원하는 매개 변수 형식은 Functions 런타임 버전, 확장 패키지 버전 및 사용된 C# 형식에 따라 다릅니다.

함수가 단일 문서를 처리하도록 하려면 Cosmos DB 입력 바인딩을 다음 형식에 바인딩할 수 있습니다.

Type 설명
JSON 직렬화 가능 형식 함수는 문서의 JSON 데이터를 POCO(일반 오래된 CLR 개체) 형식으로 역직렬화하려고 시도합니다.

함수가 쿼리에서 여러 문서를 처리하도록 하려면 Cosmos DB 입력 바인딩이 다음 형식에 바인딩할 수 있습니다.

Type 설명
IEnumerable<T>여기서 T는 JSON 직렬화 가능 형식입니다. 쿼리에서 반환된 항목의 열거형입니다. 각 항목은 하나의 문서를 나타냅니다.
CosmosClient1 Cosmos DB 계정에 연결된 클라이언트입니다.
데이터베이스1 Cosmos DB 데이터베이스에 연결된 클라이언트입니다.
컨테이너1 Cosmos DB 컨테이너에 연결된 클라이언트입니다.

1 이러한 형식을 사용하려면 Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 이상 및 SDK 형식 바인딩에 대한 공통 종속성을 참조해야 합니다.

Java 함수 런타임 라이브러리에서 @CosmosDBInput 주석은 함수에 Azure Cosmos DB 데이터를 노출시킵니다. 이 주석은 을 사용하여 네이티브 Java 형식, POJO 또는 nullable 값과 함께 사용할 Optional<T>수 있습니다.

context.extraInputs.get()을(를) 사용하여 문서에 액세스합니다.

문서에 대한 업데이트 함수가 종료될 때 자동으로 만들어지지 않습니다. 함수의 문서를 업데이트하려면 출력 바인딩을 사용합니다. 자세한 내용은 PowerShell 예제를 참조하세요.

매개 변수를 통해 DocumentList 함수에 데이터를 사용할 수 있습니다. 문서의 변경 내용은 자동으로 유지되지 않습니다.

연결

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

  • 연결 문자열이 포함된 애플리케이션 설정의 이름
  • 함께 ID 기반 연결을 정의하는 여러 애플리케이션 설정에 대한 공유 접두사의 이름입니다. 이 옵션은 확장 버전 4.x 이상의 connection 및 leaseConnection 버전에만 사용할 수 있습니다.

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

Connection string

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

ID 기반 연결

버전 4.x 이상을 사용하는 경우 비밀과 함께 연결 문자열 사용하는 대신 앱에서 Microsoft Entra ID를 사용하도록 할 수 있습니다. 이렇게 하려면 트리거 및 바인딩 구성의 연결 속성에 매핑되는 공통 접두사 아래에 설정을 정의합니다.

이 모드에서 확장에는 다음 속성이 필요합니다.

속성 환경 변수 템플릿 설명 예제 값
계정 엔드포인트 <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB 계정 엔드포인트 URI. https://<database_account_name>.documents.azure.com:443/

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

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

ID에 권한 부여

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

Important

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

Cosmos DB는 데이터 작업에 Azure RBAC를 사용하지 않습니다. 대신 유사한 개념으로 빌드되는 Cosmos DB 기본 제공 RBAC 시스템을 사용합니다. 런타임에 데이터베이스 계정에 대한 액세스를 제공하는 역할 할당을 만들어야 합니다. 소유자와 같은 Azure RBAC 관리 역할로는 충분하지 않습니다. 다음 표에는 Azure Cosmos DB 확장을 정상 작동할 때 권장되는 기본 제공 역할이 나와 있습니다. 작성하는 코드에 따라 애플리케이션에 추가 권한이 필요할 수 있습니다.

바인딩 유형 예제 기본 제공 역할1
트리거2 Cosmos DB 기본 제공 데이터 기여자
입력 바인딩 Cosmos DB 기본 제공 데이터 판독기
출력 바인딩 Cosmos DB 기본 제공 데이터 기여자

1 이 역할은 Azure RBAC 역할 할당에서 사용할 수 없습니다. 이 역할을 할당하는 방법에 대한 자세한 내용은 Cosmos DB 기본 제공 RBAC 시스템 설명서를 참조하세요.

2 ID를 사용하는 경우 Cosmos DB는 컨테이너 만들기를 관리 작업으로 처리합니다. 트리거에 대한 데이터 평면 작업으로 사용할 수 없습니다. 함수를 설정하기 전에 트리거에 필요한 컨테이너(임대 컨테이너 포함)를 만들어야 합니다.

다음 단계