Azure Functions 2.x 이상에 대 한 Azure Cosmos DB 출력 바인딩Azure Cosmos DB output binding for Azure Functions 2.x and higher

Azure Cosmos DB 출력 바인딩을 사용하면 Azure Cosmos DB 데이터베이스에 SQL API를 사용하여 새 문서를 작성할 수 있습니다.The Azure Cosmos DB output binding lets you write a new document to an Azure Cosmos DB database using the SQL API.

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

이 섹션에는 다음 예제가 포함되어 있습니다.This section contains the following examples:

예제에서는 간단한 ToDoItem 형식을 참조하세요.The examples refer to a simple ToDoItem type:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

큐 트리거, 하나의 문서 쓰기Queue trigger, write one doc

다음 예제에서는 Queue storage의 메시지에 제공된 데이터를 사용하여 문서를 데이터베이스에 추가하는 C# 함수를 보여 줍니다.The following example shows a C# function that adds a document to a database, using data provided in message from Queue storage.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

큐 트리거, IAsyncCollector를 사용하여 문서 쓰기Queue trigger, write docs using IAsyncCollector

다음 예제에서는 큐 메시지 JSON에서 제공된 데이터를 사용하여 문서의 컬렉션을 데이터베이스에 추가하는 C# 함수를 보여줍니다.The following example shows a C# function that adds a collection of documents to a database, using data provided in a queue message JSON.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

특성 및 주석Attributes and annotations

C# 클래스 라이브러리에서 CosmosDB 특성을 사용합니다.In C# class libraries, use the CosmosDB attribute.

특성의 생성자는 데이터베이스 이름과 컬렉션 이름을 사용합니다.The attribute's constructor takes the database name and collection name. 이러한 설정 및 구성할 수 있는 다른 속성에 대한 자세한 내용은 출력 - 구성을 참조하세요.For information about those settings and other properties that you can configure, see Output - configuration. 다음은 메서드 서명의 CosmosDB 특성 예제입니다.Here's a CosmosDB attribute example in a method signature:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [CosmosDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

구성Configuration

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

function.json 속성function.json property 특성 속성Attribute property DescriptionDescription
typetype 해당 없음n/a cosmosDB로 설정해야 합니다.Must be set to cosmosDB.
directiondirection 해당 없음n/a out로 설정해야 합니다.Must be set to out.
namename 해당 없음n/a 함수에서 문서를 나타내는 바인딩 매개 변수의 이름입니다.Name of the binding parameter that represents the document in the function.
databaseNamedatabaseName DatabaseNameDatabaseName 문서가 만들어진 컬렉션을 포함하는 데이터베이스입니다.The database containing the collection where the document is created.
collectionNamecollectionName CollectionNameCollectionName 문서가 만들어진 컬렉션의 이름입니다.The name of the collection where the document is created.
createIfNotExistscreateIfNotExists CreateIfNotExistsCreateIfNotExists 컬렉션이 존재하지 않는 경우 만들 수 있는지 여부를 나타내는 부울 값입니다.A boolean value to indicate whether the collection is created when it doesn't exist. 새 컬렉션이 예약된 처리량으로 만들어져 비용이 부과되기 기본값은 false 입니다.The default is false because new collections are created with reserved throughput, which has cost implications. 자세한 내용은 가격 책정 페이지를 참조하세요.For more information, see the pricing page.
partitionKeypartitionKey PartitionKeyPartitionKey CreateIfNotExists이 true 이면 생성 된 컬렉션에 대 한 파티션 키 경로를 정의 합니다.When CreateIfNotExists is true, it defines the partition key path for the created collection.
collectionThroughputcollectionThroughput CollectionThroughputCollectionThroughput CreateIfNotExists이 true 이면 생성 된 컬렉션의 처리량 을 정의 합니다.When CreateIfNotExists is true, it defines the throughput of the created collection.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting Azure Cosmos DB 연결 문자열을 포함하는 앱 설정의 이름입니다.The name of the app setting containing your Azure Cosmos DB connection string.
preferredLocationspreferredLocations PreferredLocationsPreferredLocations 필드 Azure Cosmos DB 서비스에서 지역에서 복제 된 데이터베이스 계정에 대 한 기본 위치 (지역)를 정의 합니다.(Optional) Defines preferred locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service. 값은 쉼표로 구분 해야 합니다.Values should be comma-separated. 예를 들면 "미국 동부, 미국 중 북부, 유럽 유럽"입니다.For example, "East US,South Central US,North Europe".
useMultipleWriteLocationsuseMultipleWriteLocations UseMultipleWriteLocationsUseMultipleWriteLocations 필드 true 와 함께로 설정 하면 PreferredLocations Azure Cosmos DB 서비스에서 다중 지역 쓰기 를 활용할 수 있습니다.(Optional) When set to true along with PreferredLocations, it can leverage multi-region writes in the Azure Cosmos DB service.

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

사용Usage

기본적으로 함수에서 출력 매개 변수에 쓸 경우 데이터베이스에서 문서가 생성됩니다.By default, when you write to the output parameter in your function, a document is created in your database. 이 문서에는 자동으로 생성된 GUID가 문서 ID로 지정되어 있습니다.This document has an automatically generated GUID as the document ID. 출력 매개 변수에 전달되는 JSON 개체에 id 속성을 지정하여 출력 문서의 문서 ID를 지정할 수 있습니다.You can specify the document ID of the output document by specifying the id property in the JSON object passed to the output parameter.

참고

기존 문서의 ID를 지정하면 새 출력 문서에 의해 덮어쓰여집니다.When you specify the ID of an existing document, it gets overwritten by the new output document.

예외 및 반환 코드Exceptions and return codes

바인딩Binding 참고Reference
CosmosDBCosmosDB CosmosDB 오류 코드CosmosDB Error Codes

host.json 설정host.json settings

이 섹션에서는 버전 2.x에서 이 바인딩에 사용할 수 있는 글로벌 구성 설정을 설명합니다.This section describes the global configuration settings available for this binding in version 2.x. 버전 2.x의 글로벌 구성 설정에 대한 자세한 내용은 Azure Functions 버전 2.x에 대한 host.json 참조를 참조하세요.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}
속성Property 기본값Default DescriptionDescription
GatewayModeGatewayMode 게이트웨이Gateway Azure Cosmos DB 서비스에 연결할 때 해당 함수에 의해 사용되는 연결 모드입니다.The connection mode used by the function when connecting to the Azure Cosmos DB service. 옵션은 DirectGateway입니다.Options are Direct and Gateway
프로토콜Protocol HttpsHttps Azure Cosmos DB 서비스에 연결할 때 해당 함수에 의해 사용되는 연결 프로토콜입니다.The connection protocol used by the function when connection to the Azure Cosmos DB service. 두 모드에 대한 설명은 여기를 참조하세요.Read here for an explanation of both modes
leasePrefixleasePrefix 해당 없음n/a 앱의 모든 함수에서 사용할 접두사를 임대합니다.Lease prefix to use across all functions in an app.

다음 단계Next steps