.NET을 사용하여 Azure Cosmos DB for NoSQL 시작

적용 대상: NoSQL

이 문서에서는 .NET SDK를 사용하여 Azure Cosmos DB for NoSQL에 연결하는 방법을 보여 줍니다. 연결되면 데이터베이스, 컨테이너 및 항목에 대한 작업을 수행할 수 있습니다.

패키지(NuGet) | 샘플 | API 참조 | 라이브러리 소스 코드 | 피드백 제공

필수 조건

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• Azure Cosmos DB for NoSQL 계정. API for NoSQL 계정을 만듭니다.
• .NET 6.0 이상
• Azure CLI(명령줄 인터페이스) 또는 Azure PowerShell

프로젝트 설정

.NET 콘솔 애플리케이션 만들기

console 템플릿에서 dotnet new 명령을 사용하여 새 .NET 애플리케이션을 만듭니다.

dotnet new console

dotnet add package 명령을 사용하여 Microsoft.Azure.Cosmos NuGet 패키지를 가져옵니다.

dotnet add package Microsoft.Azure.Cosmos

dotnet build 명령을 사용하여 프로젝트를 빌드합니다.

dotnet build

Azure Cosmos DB for NoSQL에 연결

Azure Cosmos DB의 API for NoSQL에 연결하려면 CosmosClient 클래스의 인스턴스를 만듭니다. 이 클래스는 데이터베이스에 대한 모든 작업을 수행하기 위한 시작점입니다. 다음과 같이 CosmosClient 클래스를 사용하여 API for NoSQL 계정에 연결하는 세 가지 핵심 방법이 있습니다.

• API for NoSQL 엔드포인트 및 읽기/쓰기 키를 사용하여 연결
• API for NoSQL 연결 문자열을 사용하여 연결
• Microsoft Entra ID로 연결

엔드포인트 및 키를 사용하여 연결

CosmosClient의 가장 일반적인 생성자에는 다음 두 개의 매개 변수가 있습니다.

매개 변수	예제 값	설명
accountEndpoint	COSMOS_ENDPOINT환경 변수	모든 요청에 ​​사용할 API for NoSQL 엔드포인트
authKeyOrResourceToken	COSMOS_KEY환경 변수	인증할 때 사용할 계정 키 또는 리소스 토큰

계정 엔드포인트 및 키 검색

Azure CLI

1. resourceGroupName에 대한 셸 변수를 만듭니다.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
   

2. az cosmosdb list 명령을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 accountName 셸 변수에 저장합니다.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

3. az cosmosdb show 명령을 사용하여 계정에 대한 API for NoSQL 엔드포인트 URI를 가져옵니다.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

4. az-cosmosdb-keys-list 명령을 사용하여 계정에 대한 키 목록에서 PRIMARY KEY를 찾습니다.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

5. URI 및 기본 키 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

PowerShell

1. RESOURCE_GROUP_NAME에 대한 셸 변수를 만듭니다.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"
   

2. Get-AzCosmosDBAccount cmdlet을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 ACCOUNT_NAME 셸 변수에 저장합니다.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. Get-AzCosmosDBAccount cmdlet을 사용하여 계정에 대한 API for NoSQL 엔드포인트 URI를 가져옵니다.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. Get-AzCosmosDBAccountKey cmdlet을 사용하여 계정에 대한 키 목록에서 기본 키를 찾습니다.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"    
   

5. URI 및 기본 키 값을 기록합니다. 이러한 자격 증명은 나중에 사용합니다.

포털

팁

이 가이드에서는 msdocs-cosmos-dotnet-howto-rg 리소스 그룹 이름을 사용하는 것이 좋습니다.

1. Azure Portal에 로그인합니다.

2. 기존 Azure Cosmos DB for NoSQL 계정 페이지로 이동합니다.

3. Azure Cosmos DB for NoSQL 계정 페이지에서 키 탐색 메뉴 옵션을 선택합니다.

   

4. URI 및 기본 키 필드의 값을 기록합니다. 이러함 값은 이후 단계에서 사용합니다.

   

.NET 코드 내에서 URI 및 기본 키 값을 사용하려면 애플리케이션을 실행하는 로컬 컴퓨터의 새 환경 변수에 유지합니다.

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux / macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

계정 엔드포인트 및 키를 사용하여 CosmosClient 만들기

COSMOS_ENDPOINT 및 COSMOS_KEY 환경 변수를 매개 변수로 사용하여 CosmosClient 클래스의 새 인스턴스를 만듭니다.

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

연결 문자열로 연결

CosmosClient의 다른 생성자에는 단일 매개 변수만 포함됩니다.

매개 변수	예제 값	설명
accountEndpoint	COSMOS_ENDPOINT환경 변수	모든 요청에 ​​사용할 API for NoSQL 엔드포인트
connectionString	COSMOS_CONNECTION_STRING환경 변수	API for NoSQL 계정에 대한 연결 문자열

계정 연결 문자열 검색

Azure CLI

1. az cosmosdb list 명령을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 accountName 셸 변수에 저장합니다.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. az-cosmosdb-keys-list 명령을 사용하여 계정에 대한 연결 문자열 목록에서 PRIMARY CONNECTION STRING을 찾습니다.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
   

PowerShell

1. Get-AzCosmosDBAccount cmdlet을 사용하여 리소스 그룹에서 첫 번째 Azure Cosmos DB 계정의 이름을 검색하여 ACCOUNT_NAME 셸 변수에 저장합니다.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Get-AzCosmosDBAccountKey cmdlet을 사용하여 계정에 대한 연결 문자열 목록에서 기본 연결 문자열을 찾습니다.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

포털

팁

이 가이드에서는 msdocs-cosmos-dotnet-howto-rg 리소스 그룹 이름을 사용하는 것이 좋습니다.

1. Azure Portal에 로그인합니다.

2. 기존 Azure Cosmos DB for NoSQL 계정 페이지로 이동합니다.

3. Azure Cosmos DB for NoSQL 계정 페이지에서 키 탐색 메뉴 옵션을 선택합니다.

4. 기본 연결 문자열 필드의 값을 기록합니다.

.NET 코드 내에서 기본 연결 문자열 값을 사용하려면 이 값을 애플리케이션을 실행하는 로컬 컴퓨터의 새 환경 변수에 유지합니다.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

연결 문자열 사용하여 CosmosClient 만들기

COSMOS_CONNECTION_STRING 환경 변수를 유일한 매개 변수로 사용하여 CosmosClient 클래스의 새 인스턴스를 만듭니다.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Microsoft ID 플랫폼을 사용하여 연결

Microsoft ID 플랫폼 및 Microsoft Entra ID를 사용하여 API for NoSQL 계정에 연결하려면 보안 주체를 사용합니다. 보안 주체의 정확한 유형은 애플리케이션 코드를 호스트하는 위치에 따라 달라집니다. 아래 표는 빠른 참조 가이드 역할을 합니다.

애플리케이션이 실행되는 위치	할당할 수 있습니다.
로컬 컴퓨터(개발 및 테스트)	사용자 ID 또는 서비스 주체
Azure	관리 ID
Azure 외부의 서버 또는 클라이언트	서비스 사용자

Azure.ID 가져오기

Azure.Identity NuGet 패키지에는 모든 Azure SDK 라이브러리 간에 공유되는 핵심 인증 기능이 포함되어 있습니다.

dotnet add package 명령을 사용하여 Azure.Identity NuGet 패키지를 가져옵니다.

dotnet add package Azure.Identity

dotnet build 명령을 사용하여 프로젝트를 다시 빌드합니다.

dotnet build

코드 편집기에서 Azure.Core 및 Azure.Identity 네임스페이스에 대한 using 지시문을 추가합니다.

using Azure.Core;
using Azure.Identity;

기본 자격 증명 구현을 사용하여 CosmosClient 만들기

로컬 컴퓨터에서 테스트하거나 애플리케이션이 관리 ID를 직접 지원하는 Azure 서비스에서 실행되는 경우 DefaultAzureCredential 인스턴스를 만들어 OAuth 토큰을 얻습니다.

다음 예제에서는 SDK에서 다시 사용할 수 있는 더 일반적인 형식인 TokenCredential 형식의 변수에 인스턴스를 저장했습니다.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

COSMOS_ENDPOINT 환경 변수와 TokenCredential 개체를 매개 변수로 사용하여 CosmosClient 클래스의 새 인스턴스를 만듭니다.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

사용자 지정 자격 증명 구현을 사용하여 CosmosClient 만들기

Azure 외부에서 애플리케이션을 배포하려는 경우 .NET용 Azure.Identity 클라이언트 라이브러리의 다른 클래스를 사용하여 OAuth 토큰을 얻을 수 있습니다. 이러한 다른 클래스도 TokenCredential 클래스에서 파생됩니다.

다음 예제에서는 클라이언트 암호와 함께 클라이언트 및 테넌트 식별자를 사용하여 ClientSecretCredential 인스턴스를 만듭니다.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

Microsoft Entra ID에 애플리케이션을 등록하면 클라이언트 ID, 테넌트 ID, 클라이언트 암호를 가져올 수 있습니다. Microsoft Entra 애플리케이션 등록에 대한 자세한 내용은 Microsoft ID 플랫폼에 애플리케이션 등록을 참조하세요.

COSMOS_ENDPOINT 환경 변수와 TokenCredential 개체를 매개 변수로 사용하여 CosmosClient 클래스의 새 인스턴스를 만듭니다.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

애플리케이션 빌드

애플리케이션을 빌드할 때 코드는 주로 다음 4가지 종류의 리소스와 상호 작용합니다.

• API for NoSQL 계정 - Azure Cosmos DB 데이터에 대한 고유한 최상위 네임스페이스입니다.

• 계정의 컨테이너를 구성하는 데이터베이스

• 데이터베이스의 개별 항목 세트를 포함하는 컨테이너

• 컨테이너의 JSON 문서를 나타내는 항목

다음 다이어그램에서는 리소스 간의 관계를 보여줍니다.

맨 위에 있는 Azure Cosmos DB 계정을 보여 주는 계층 다이어그램. 계정에는 두 개의 자식 데이터베이스 노드가 있습니다. 데이터베이스 노드 중 하나에는 두 개의 자식 컨테이너 노드가 포함되어 있습니다. 다른 데이터베이스 노드에는 단일 자식 컨테이너 노드가 포함됩니다. 단일 컨테이너 노드에는 세 개의 자식 항목 노드가 있습니다.

각 리소스 형식은 하나 이상의 연결된 .NET 클래스로 표시됩니다. 가장 일반적인 클래스의 목록은 다음과 같습니다.

클래스	설명
CosmosClient	이 클래스는 Azure Cosmos DB 서비스의 클라이언트 쪽 논리적 표현을 제공합니다. 이 클라이언트 개체는 서비스에 대한 요청을 구성하고 실행하는 데 사용됩니다.
Database	이 클래스는 아직 서비스에 있거나 없을 수도 있는 데이터베이스에 대한 참조입니다. 데이터베이스에 액세스하거나 이에 대한 작업을 수행하려고 하면 서버 쪽에서 데이터베이스의 유효성이 검사됩니다.
Container	이 클래스는 아직 서비스에 없을 수도 있는 컨테이너에 대한 참조입니다. 관련 작업을 시도하면 서버 쪽에서 컨테이너의 유효성이 검사됩니다.

다음 가이드에서는 이러한 각 클래스를 사용하여 애플리케이션을 빌드하는 방법을 보여 줍니다.

가이드	설명
데이터베이스 만들기	데이터베이스 만들기
컨테이너 만들기	컨테이너 만들기
항목 읽기	특정 항목 지점 읽기
쿼리 항목	여러 항목 쿼리

참고 항목

• 패키지(NuGet)
• 샘플
• API 참조
• 라이브러리 소스 코드
• 피드백 제공

다음 단계

이제 API for NoSQL 계정에 연결했으므로 다음 가이드를 사용하여 데이터베이스를 만들고 관리합니다.

.NET을 사용하여 Azure Cosmos DB for NoSQL에서 데이터베이스 만들기