서비스 커넥터와 Azure Cosmos DB for NoSQL 통합

아티클
10/16/2024

이 페이지에는 지원되는 인증 방법 및 클라이언트가 표시되며, 서비스 커넥터를 사용하여 Azure Cosmos DB for NoSQL을 다른 클라우드 서비스에 연결하는 데 사용할 수 있는 샘플 코드가 표시됩니다. 서비스 커넥터를 사용하지 않고 다른 프로그래밍 언어로 Azure Cosmos DB for NoSQL에 계속 연결할 수 있습니다. 이 페이지에서는 서비스 연결을 만들 때 가져오는 기본 환경 변수 이름과 값(또는 Spring Boot 구성)도 보여 줍니다.

지원되는 컴퓨팅 서비스

서비스 커넥터를 사용하여 Azure Cosmos DB for NoSQL에 다음 컴퓨팅 서비스를 연결할 수 있습니다.

Azure App Service
Azure Container Apps
Azure 기능
AKS(Azure Kubernetes Service)
Azure Spring Apps

지원되는 인증 유형 및 클라이언트 유형

아래 표에서는 서비스 커넥터를 사용하여 컴퓨팅 서비스를 Azure Cosmos DB for NoSQL에 연결하는 데 지원되는 인증 방법과 클라이언트 유형의 조합을 보여 줍니다. "예"는 조합이 지원됨을 나타내고 "아니오"는 지원되지 않음을 나타냅니다.

클라이언트 유형	시스템 할당 관리 ID	사용자 할당 관리 ID	비밀/연결 문자열	서비스 사용자
.NET	예	예	예	예
Java	예	예	예	예
Java - Spring Boot	예	예	예	예
Node.JS	예	예	예	예
Python	예	예	예	예
Go	예	예	예	예
없음	예	예	예	예

이 표는 표에 있는 클라이언트 유형과 인증 방법의 모든 조합이 지원됨을 나타냅니다. 모든 클라이언트 유형은 어느 인증 방법으로나 서비스 커넥터를 사용하여 Azure Cosmos DB for NoSQL에 연결할 수 있습니다.

기본 환경 변수 이름 또는 애플리케이션 속성 및 샘플 코드

아래 연결 세부 정보를 사용하여 컴퓨팅 서비스를 Azure Cosmos DB for NoSQL에 연결합니다. 아래의 각 예제에서 자리 표시자 텍스트 <database-server>, <database-name>, <account-key>, <resource-group-name>, <subscription-ID>, <client-ID>, <SQL-server>, <client-secret>, <tenant-id> 및 <access-key>를 고유의 정보로 바꿉니다. 명명 규칙에 대한 자세한 내용은 서비스 커넥터 내부 문서를 확인하세요.

시스템 할당 관리 ID

SpringBoot 클라이언트 유형

인증 유형으로 시스템이 할당한 관리 ID를 사용하는 것은 Spring Cloud Azure 버전 4.0 이상에서만 가능합니다.

기본 환경 변수 이름	설명	예제 값
spring.cloud.azure.cosmos.credential.managed-identity-enabled	관리 ID 사용 여부	`true`
spring.cloud.azure.cosmos.database	데이터베이스	`https://management.azure.com/.default`
spring.cloud.azure.cosmos.endpoint	리소스 엔드포인트	`https://<database-server>.documents.azure.com:443/`

기타 클라이언트 유형

기본 환경 변수 이름	설명	예제 값
AZURE_COSMOS_LISTCONNECTIONSTRINGURL	연결 문자열을 가져올 URL	`https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<database-server>/listConnectionStrings?api-version=2021-04-15`
AZURE_COSMOS_SCOPE	관리 ID 범위	`https://management.azure.com/.default`
AZURE_COSMOS_RESOURCEENDPOINT	리소스 엔드포인트	`https://<database-server>.documents.azure.com:443/`

샘플 코드

시스템에서 할당한 ID를 사용하여 Azure Cosmos DB for NoSQL에 연결하려면 아래 단계 및 코드를 참조하세요.

종속성을 설치합니다.

dotnet add package Microsoft.Azure.Cosmos
dotnet add package Azure.Identity

Azure.Identity NuGet 패키지를 사용하여 인증하고 서비스 커넥터에서 추가한 환경 변수에서 엔드포인트 URL을 가져옵니다. 아래 코드를 사용하는 경우 사용하려는 인증 유형에 대한 코드 조각 부분의 주석 처리를 제거합니다.

using Microsoft.Azure.Cosmos;
using Azure.Core;
using Azure.Identity;
using System; 

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned identity.
// TokenCredential credential = new DefaultAzureCredential();

// For user-assigned identity.
// TokenCredential credential = new DefaultAzureCredential(
//     new DefaultAzureCredentialOptions
//     {
//         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
//     }
// );

// For service principal.
// TokenCredential credential = new ClientSecretCredential(
//     tenantId: Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID")!,
//     clientId: Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")!,
//     clientSecret: Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET")!,
//     options: new TokenCredentialOptions()
// );

// Create a new instance of CosmosClient using the credential above
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT")!,
    tokenCredential: credential
);

pom.xml 파일에서 다음 종속성을 추가합니다.

<dependency>
	<groupId>com.azure</groupId>
	<artifactId>azure-cosmos</artifactId>
	<version>LATEST</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.1.5</version>
</dependency>

azure-identity를 통해 인증하고 서비스 커넥터에서 추가한 환경 변수에서 엔드포인트 URL을 가져옵니다. 아래 코드를 사용하는 경우 사용하려는 인증 유형에 대한 코드 조각 부분의 주석 처리를 제거합니다.

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned identity
// DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// for user-assigned managed identity
// DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
//     .managedIdentityClientId(System.getenv("AZURE_COSMOS_CLIENTID"))
//     .build();

// for service principal
// ClientSecretCredential credential = new ClientSecretCredentialBuilder()
//   .clientId(System.getenv("<AZURE_COSMOS_CLIENTID>"))
//   .clientSecret(System.getenv("<AZURE_COSMOS_CLIENTSECRET>"))
//   .tenantId(System.getenv("<AZURE_COSMOS_TENANTID>"))
//   .build();

String endpoint = System.getenv("AZURE_COSMOS_RESOURCEENDPOINT");

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

종속성을 설치합니다.

pip install azure-identity
pip install azure-cosmos

azure-identity 라이브러리를 통해 인증하고 서비스 커넥터에서 추가한 환경 변수에서 엔드포인트 URL을 가져옵니다. 아래 코드를 사용하는 경우 사용하려는 인증 유형에 대한 코드 조각 부분의 주석 처리를 제거합니다.

import os
from azure.cosmos import CosmosClient
from azure.identity import ManagedIdentityCredential, ClientSecretCredential

# Uncomment the following lines corresponding to the authentication type you want to use.
# system-assigned managed identity
# cred = ManagedIdentityCredential()

# user-assigned managed identity
# managed_identity_client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# cred = ManagedIdentityCredential(client_id=managed_identity_client_id)

# service principal
# tenant_id = os.getenv('AZURE_COSMOS_TENANTID')
# client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# client_secret = os.getenv('AZURE_COSMOS_CLIENTSECRET')
# cred = ClientSecretCredential(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)

endpoint = os.environ["AZURE_COSMOS_RESOURCEENDPOINT"]
client = CosmosClient(url=endpoint, credential=cred)

종속성을 설치합니다.

go get t github.com/Azure/azure-sdk-for-go/sdk/azidentity
go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

azidentity npm 패키지를 사용하여 인증하고 서비스 커넥터에서 추가한 환경 변수에서 엔드포인트 URL을 가져옵니다. 아래 코드를 사용하는 경우 사용하려는 인증 유형에 대한 코드 조각 부분의 주석 처리를 제거합니다.

import (
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
    endpoint = os.Getenv("AZURE_COSMOS_RESOURCEENDPOINT")

    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // cred, err := azidentity.NewDefaultAzureCredential(nil)

    // For user-assigned identity.
    // clientid := os.Getenv("AZURE_COSMOS_CLIENTID")
    // azidentity.ManagedIdentityCredentialOptions.ID := clientid
    // options := &azidentity.ManagedIdentityCredentialOptions{ID: clientid}
    // cred, err := azidentity.NewManagedIdentityCredential(options)

    // For service principal.
    // clientid := os.Getenv("AZURE_COSMOS_CLIENTID")
    // tenantid := os.Getenv("AZURE_COSMOS_TENANTID")
    // clientsecret := os.Getenv("AZURE_COSMOS_CLIENTSECRET")
    // cred, err := azidentity.NewClientSecretCredential(tenantid, clientid, clientsecret, &azidentity.ClientSecretCredentialOptions{})

    client, err := azcosmos.NewClient(endpoint, cred, nil)
}

종속성을 설치합니다.

npm install @azure/identity
npm install @azure/cosmos

@azure/identity npm 패키지를 사용하여 인증하고 서비스 커넥터에서 추가한 환경 변수에서 엔드포인트 URL을 가져옵니다. 아래 코드를 사용하는 경우 사용하려는 인증 유형에 대한 코드 조각 부분의 주석 처리를 제거합니다.

import { CosmosClient } from "@azure/cosmos";
const { DefaultAzureCredential } = require("@azure/identity");

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned managed identity.
// const credential = new DefaultAzureCredential();

// For user-assigned managed identity.
// const credential = new DefaultAzureCredential({
//     managedIdentityClientId: process.env.AZURE_COSMOS_CLIENTID
// });

// For service principal.
// const credential = new ClientSecretCredential(
//     tenantId: process.env.AZURE_COSMOS_TENANTID,
//     clientId: process.env.AZURE_COSMOS_CLIENTID,
//     clientSecret: process.env.AZURE_COSMOS_CLIENTSECRET
// );

// Create a new instance of CosmosClient using the credential above
const cosmosClient = new CosmosClient({ 
    process.env.AZURE_COSMOS_RESOURCEENDPOINT, 
    aadCredentials: credential
});

사용자 할당 관리 ID

SpringBoot 클라이언트 유형

인증 유형으로 사용자가 할당한 관리 ID를 사용하는 것은 Spring Cloud Azure 버전 4.0 이상에서만 가능합니다.

기본 환경 변수 이름	설명	예제 값
spring.cloud.azure.cosmos.credential.managed-identity-enabled	관리 ID 사용 여부	`true`
spring.cloud.azure.cosmos.database	데이터베이스	`https://management.azure.com/.default`
spring.cloud.azure.cosmos.endpoint	리소스 엔드포인트	`https://<database-server>.documents.azure.com:443/`
spring.cloud.azure.cosmos.credential.client-id	클라이언트 ID	`<client-ID>`

기타 클라이언트 유형

기본 환경 변수 이름	설명	예제 값
AZURE_COSMOS_LISTCONNECTIONSTRINGURL	연결 문자열을 가져올 URL	`https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<database-server>/listConnectionStrings?api-version=2021-04-15`
AZURE_COSMOS_SCOPE	관리 ID 범위	`https://management.azure.com/.default`
AZURE_COSMOS_CLIENTID	클라이언트 ID	`<client-ID>`
AZURE_COSMOS_RESOURCEENDPOINT	리소스 엔드포인트	`https://<database-server>.documents.azure.com:443/`

샘플 코드

사용자가 할당한 ID를 사용하여 Azure Cosmos DB for NoSQL에 연결하려면 아래 단계 및 코드를 참조하세요.

종속성을 설치합니다.

dotnet add package Microsoft.Azure.Cosmos
dotnet add package Azure.Identity

using Microsoft.Azure.Cosmos;
using Azure.Core;
using Azure.Identity;
using System; 

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned identity.
// TokenCredential credential = new DefaultAzureCredential();

// For user-assigned identity.
// TokenCredential credential = new DefaultAzureCredential(
//     new DefaultAzureCredentialOptions
//     {
//         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
//     }
// );

// For service principal.
// TokenCredential credential = new ClientSecretCredential(
//     tenantId: Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID")!,
//     clientId: Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID")!,
//     clientSecret: Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET")!,
//     options: new TokenCredentialOptions()
// );

// Create a new instance of CosmosClient using the credential above
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT")!,
    tokenCredential: credential
);

pom.xml 파일에서 다음 종속성을 추가합니다.

<dependency>
	<groupId>com.azure</groupId>
	<artifactId>azure-cosmos</artifactId>
	<version>LATEST</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.1.5</version>
</dependency>

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned identity
// DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// for user-assigned managed identity
// DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
//     .managedIdentityClientId(System.getenv("AZURE_COSMOS_CLIENTID"))
//     .build();

// for service principal
// ClientSecretCredential credential = new ClientSecretCredentialBuilder()
//   .clientId(System.getenv("<AZURE_COSMOS_CLIENTID>"))
//   .clientSecret(System.getenv("<AZURE_COSMOS_CLIENTSECRET>"))
//   .tenantId(System.getenv("<AZURE_COSMOS_TENANTID>"))
//   .build();

String endpoint = System.getenv("AZURE_COSMOS_RESOURCEENDPOINT");

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

종속성을 설치합니다.

pip install azure-identity
pip install azure-cosmos

import os
from azure.cosmos import CosmosClient
from azure.identity import ManagedIdentityCredential, ClientSecretCredential

# Uncomment the following lines corresponding to the authentication type you want to use.
# system-assigned managed identity
# cred = ManagedIdentityCredential()

# user-assigned managed identity
# managed_identity_client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# cred = ManagedIdentityCredential(client_id=managed_identity_client_id)

# service principal
# tenant_id = os.getenv('AZURE_COSMOS_TENANTID')
# client_id = os.getenv('AZURE_COSMOS_CLIENTID')
# client_secret = os.getenv('AZURE_COSMOS_CLIENTSECRET')
# cred = ClientSecretCredential(tenant_id=tenant_id, client_id=client_id, client_secret=client_secret)

endpoint = os.environ["AZURE_COSMOS_RESOURCEENDPOINT"]
client = CosmosClient(url=endpoint, credential=cred)

종속성을 설치합니다.

go get t github.com/Azure/azure-sdk-for-go/sdk/azidentity
go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

import (
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
    endpoint = os.Getenv("AZURE_COSMOS_RESOURCEENDPOINT")

    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // cred, err := azidentity.NewDefaultAzureCredential(nil)

    // For user-assigned identity.
    // clientid := os.Getenv("AZURE_COSMOS_CLIENTID")
    // azidentity.ManagedIdentityCredentialOptions.ID := clientid
    // options := &azidentity.ManagedIdentityCredentialOptions{ID: clientid}
    // cred, err := azidentity.NewManagedIdentityCredential(options)

    // For service principal.
    // clientid := os.Getenv("AZURE_COSMOS_CLIENTID")
    // tenantid := os.Getenv("AZURE_COSMOS_TENANTID")
    // clientsecret := os.Getenv("AZURE_COSMOS_CLIENTSECRET")
    // cred, err := azidentity.NewClientSecretCredential(tenantid, clientid, clientsecret, &azidentity.ClientSecretCredentialOptions{})

    client, err := azcosmos.NewClient(endpoint, cred, nil)
}

종속성을 설치합니다.

npm install @azure/identity
npm install @azure/cosmos

import { CosmosClient } from "@azure/cosmos";
const { DefaultAzureCredential } = require("@azure/identity");

// Uncomment the following lines corresponding to the authentication type you want to use.
// For system-assigned managed identity.
// const credential = new DefaultAzureCredential();

// For user-assigned managed identity.
// const credential = new DefaultAzureCredential({
//     managedIdentityClientId: process.env.AZURE_COSMOS_CLIENTID
// });

// For service principal.
// const credential = new ClientSecretCredential(
//     tenantId: process.env.AZURE_COSMOS_TENANTID,
//     clientId: process.env.AZURE_COSMOS_CLIENTID,
//     clientSecret: process.env.AZURE_COSMOS_CLIENTSECRET
// );

// Create a new instance of CosmosClient using the credential above
const cosmosClient = new CosmosClient({ 
    process.env.AZURE_COSMOS_RESOURCEENDPOINT, 
    aadCredentials: credential
});

Connection string

Warning

사용 가능한 가장 안전한 인증 흐름을 사용하는 것이 권장됩니다. 이 절차에서 설명된 인증 흐름은 다른 흐름에는 없는 위험을 전달하며, 애플리케이션에서 매우 높은 신뢰 수준을 요구합니다. 이 흐름은 관리 ID와 같은 보다 안전한 다른 흐름을 실행할 수 없는 경우에만 사용되어야 합니다.

SpringBoot 클라이언트 유형

기본 환경 변수 이름	설명	예제 값
azure.cosmos.key	버전 4.0 미만의 Spring Cloud Azure용 데이터베이스에 대한 액세스 키	`<access-key>`
azure.cosmos.database	버전 4.0 미만의 Spring Cloud Azure용 데이터베이스	`<database-name>`
azure.cosmos.uri	버전 4.0 미만의 Spring Cloud Azure용 데이터베이스 URI	`https://<database-server>.documents.azure.com:443/`
spring.cloud.azure.cosmos.key	버전 4.0 이상의 Spring Cloud Azure용 데이터베이스에 대한 액세스 키	`<access-key>`
spring.cloud.azure.cosmos.database	버전 4.0 이상의 Spring Cloud Azure용 데이터베이스	`<database-name>`
spring.cloud.azure.cosmos.endpoint	버전 4.0 이상의 Spring Cloud Azure용 데이터베이스 URI	`https://<database-server>.documents.azure.com:443/`

기타 클라이언트 유형

기본 환경 변수 이름	설명	예제 값
AZURE_COSMOS_CONNECTIONSTRING	Azure Cosmos DB for NoSQL 연결 문자열	`AccountEndpoint=https://<database-server>.documents.azure.com:443/;AccountKey=<account-key>`