다음을 통해 공유

Azure Functions에 대한 Azure Cosmos DB 트리거 및 바인딩 개요

이 문서 집합에서는 Azure Functions에서 Azure Cosmos DB 바인딩을 사용하는 방법을 설명합니다. Azure Functions는 Azure Cosmos DB에 대한 트리거, 입력 및 출력 바인딩을 지원합니다.

작업 유형
Azure Cosmos DB 문서를 만들거나 수정할 때 함수 실행 트리거
Azure Cosmos DB 문서 읽기 입력 바인딩
Azure Cosmos DB 문서에 변경 내용 저장 출력 바인딩

중요합니다

이 버전의 Azure Cosmos DB 바인딩 확장은 Azure Functions 버전 4.x를 지원합니다. 앱에서 여전히 Functions 런타임 버전 1.x를 사용하는 경우 대신 Azure Functions 1.x에 대한 Azure Cosmos DB 바인딩을 참조하세요. Functions v1.x 런타임에서 이 바인딩은 원래 이름이 지정 DocumentDB되었습니다.

지원되는 API

이 표는 함수 코드에서 다양한 Azure Cosmos DB API에 연결하는 방법을 나타냅니다.

API Recommendation
NoSQL용 Azure Cosmos DB Azure Cosmos DB 바인딩 확장 사용
Azure Cosmos DB for MongoDB (vCore) 현재 미리 보기 상태인 MongoDB용 Azure Cosmos DB 바인딩 확장을 사용합니다.
테이블용 Azure Cosmos DB Azure Tables 바인딩 확장의 버전 5.x 이상을 사용합니다.
Apache Cassandra용 Azure Cosmos DB 네이티브 클라이언트 SDK를 사용합니다.
Apache Gremlin용 Azure Cosmos DB(Graph API) 네이티브 클라이언트 SDK 사용
PostgreSQL용 Azure Cosmos DB 네이티브 클라이언트 SDK를 사용합니다.

확장 설치

설치하는 확장 NuGet 패키지는 함수 앱에서 사용 중인 C# 모드에 따라 다릅니다.

Functions는 격리된 C# 작업자 프로세스에서 실행됩니다. 자세한 내용은 격리된 작업자 프로세스에서 C# Azure Functions 실행 가이드를 참조하세요.

확장 설치 프로세스는 확장 버전에 따라 다릅니다.

이 버전의 Azure Cosmos DB 바인딩 확장에는 비밀 대신 ID를 사용하여 연결하는 기능이 도입되었습니다. 관리 ID로 함수 앱을 구성하는 방법에 대한 자습서는 ID 기반 연결로 함수 앱 만들기 자습서를 참조하세요.

NuGet 패키지, 버전 4.x를 설치하여 프로젝트에 확장을 추가합니다.

F#을 사용하여 애플리케이션을 작성하는 경우 앱 시작 구성의 일부로 이 확장을 구성해야 합니다. 호출 ConfigureFunctionsWorkerDefaults() 에서 매개 ConfigureFunctionsWebApplication()변수를 사용하는 대리자를 추가합니다 IFunctionsWorkerApplication . 그런 다음 해당 대리자의 본문 내에서 개체를 호출 ConfigureCosmosDBExtension() 합니다.

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

번들 설치

앱에서 이 바인딩 확장을 사용하려면 프로젝트 루트의 host.json 파일에 다음 extensionBundle 참조가 포함되어 있는지 확인합니다.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

이 예제에서 값 version 은 [4.0.0, 5.0.0) Functions 호스트가 4.x의 모든 잠재적 버전을 포함하는 최소 4.0.0 하지만 보다 5.0.0작은 번들 버전을 사용하도록 지시합니다. 이 표기법은 v4.x 확장 번들의 사용 가능한 최신 부 버전에서 앱을 효과적으로 유지 관리합니다.

가능하면 최신 확장 번들 주 버전을 사용하고 런타임에서 최신 부 버전을 자동으로 유지하도록 허용해야 합니다. 확장 번들 릴리스 페이지에서 최신 번들의 콘텐츠를 볼 수 있습니다. 자세한 내용은 Azure Functions 확장 번들을 참조하세요.

Azure Cosmos DB SDK의 스키마 변경으로 인해 Azure Cosmos DB 확장 버전 4.x에는 Java 함수용 azure-functions-java-library V3.0.0이 필요합니다.

바인딩 형식

.NET에 지원되는 바인딩 형식은 확장 버전과 C# 실행 모드에 따라 달라지며 다음 중 하나일 수 있습니다.

격리된 작업자 프로세스 클래스 라이브러리 컴파일된 C# 함수는 런타임에서 격리된 프로세스에서 실행됩니다.

모드 및 버전에 대한 바인딩 형식 세부 정보를 보려면 버전을 선택합니다.

격리된 작업자 프로세스는 아래 표에 따라 매개 변수 형식을 지원합니다. Microsoft.Azure.Cosmos의 형식에 대한 바인딩 지원은 미리 보기로 지원됩니다.

Cosmos DB 트리거

함수가 단일 문서를 처리하도록 하려는 경우 Cosmos DB 트리거는 다음 형식에 바인딩할 수 있습니다.

유형 설명
JSON 직렬화 가능 형식 함수는 Cosmos DB 변경 피드에서 문서의 JSON 데이터를 POCO(일반 CLR 개체) 형식으로 역직렬화하려고 합니다.

함수가 문서 일괄 처리를 처리하도록 하려는 경우 Cosmos DB 트리거는 다음 형식에 바인딩할 수 있습니다.

유형 설명
IEnumerable<T>여기서 T는 JSON 직렬화 가능 형식입니다. 일괄 처리에 포함된 엔터티의 열거형입니다. 각 항목은 Cosmos DB 변경 피드의 하나의 문서를 나타냅니다.

Cosmos DB 입력 바인딩

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

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

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

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

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

Cosmos DB 출력 바인딩

함수가 단일 문서에 쓰도록 하려면 Cosmos DB 출력 바인딩이 다음 형식에 바인딩할 수 있습니다.

유형 설명
JSON 직렬화 가능 형식 문서의 JSON 콘텐츠를 나타내는 개체입니다. Functions는 POCO(Plain Old CLR Object) 형식을 JSON 데이터로 직렬화하려고 시도합니다.

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

유형 설명
T[]여기T는 JSON 직렬화 가능 형식입니다. 여러 문서를 포함하는 배열입니다. 각 항목은 하나의 문서를 나타냅니다.

다른 출력 시나리오의 경우 Microsoft.Azure.Cosmos의 다른 형식과 함께 CosmosClient를 직접 만들고 사용합니다. 종속성 주입을 사용하여 Azure SDK에서 클라이언트 형식을 만드는 예제는 Azure 클라이언트 등록을 참조하세요.

SDK 바인딩 형식

Azure Cosmos에 대한 SDK 유형 지원은 미리 보기로 제공됩니다. CosmosDB용 Python SDK 바인딩 샘플에 따라 Python에서 Cosmos용 SDK 형식을 시작합니다.

중요합니다

SDK 형식 바인딩을 사용하려면 Python v2 프로그래밍 모델이 필요합니다.

바인딩 매개 변수 형식 샘플
CosmosDB 입력 ContainerProxy,
CosmosClient,
DatabaseProxy
 ContainerProxy;
CosmosClient;
DatabaseProxy

예외 및 반환 코드

바인딩 참조
Azure Cosmos DB (애저 코스모스 DB) Azure Cosmos DB에 대한 HTTP 상태 코드

host.json 설정

이 섹션에서는 버전 2.x 이상에서 이 바인딩에 사용할 수 있는 구성 설정을 설명합니다. host.json 파일의 설정은 함수 앱 인스턴스의 모든 함수에 적용됩니다. 함수 앱 구성 설정에 대한 자세한 내용은 Azure Functions에 대한host.json 참조를 참조하세요.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
속성 기본값 설명
connectionMode Gateway Azure Cosmos DB 서비스에 연결할 때 해당 함수에 의해 사용되는 연결 모드입니다. 옵션: Direct TCP를 통해 백 엔드 복제본에 직접 연결하고 대기 시간을 낮출 수 있으며 Gateway HTTPS를 통해 프런트 엔드 게이트웨이를 통해 요청을 라우팅합니다. 자세한 내용은 Azure Cosmos DB SDK 연결 모드를 참조하세요.
userAgentSuffix 해당 없음 서비스에 대한 트리거 또는 바인딩에 의해 수행된 모든 요청에 지정된 문자열 값을 추가합니다. 이렇게 하면 특정 함수 앱을 기반으로 하고 User Agent로 필터링하여 Azure Monitor에서 작업을 더 쉽게 추적할 수 있습니다.

다음 단계