빠른 시작: .NET용 Apache Cassandra용 Azure Cosmos DB 클라이언트 라이브러리

.NET용 Azure Cosmos DB for Apache Cassandra 클라이언트 라이브러리를 시작하여 구조화되지 않은 데이터를 저장, 관리 및 쿼리합니다. 이 가이드의 단계에 따라 새 계정을 만들고, .NET 클라이언트 라이브러리를 설치하고, 계정에 연결하고, 일반적인 작업을 수행하고, 최종 샘플 데이터를 쿼리합니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet)

필수 조건

• Azure 구독

  • Azure 구독이 없는 경우, 시작하기 전에 무료 계정을 만드십시오.

• Azure Cloud Shell에서 최신 버전의 Azure CLI입니다.

  • CLI 참조 명령을 로컬로 실행하려면 명령을 사용하여 Azure CLI에 로그인합니다 az login .

• .NET SDK 9.0 이상

설치

먼저 이 가이드에 대한 계정 및 개발 환경을 설정합니다. 이 섹션에서는 계정을 만들고 자격 증명을 얻은 다음 개발 환경을 준비하는 프로세스를 안내합니다.

계정 만들기

먼저 Apache Cassandra 계정에 대한 API를 만듭니다. 계정이 만들어지면 키스페이스 및 테이블 리소스를 만듭니다.

자격 증명 가져오기

이제 최근에 만든 계정에 대한 연결을 만드는 데 사용할 클라이언트 라이브러리의 암호를 가져옵니다.

개발 환경 준비

그런 다음 새 프로젝트 및 클라이언트 라이브러리를 사용하여 개발 환경을 구성합니다. 이 단계는 이 가이드의 나머지 단계로 넘어가기 전에 마지막으로 필요한 필수 구성 요소입니다.

1. 빈 디렉터리에서 시작합니다.

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

   dotnet new console
   

3. NuGet에서 CassandraCSharpDriver 패키지를 추가합니다.

   dotnet add package CassandraCSharpDriver
   

4. 프로젝트를 빌드합니다.

   dotnet build
   

개체 모델

코드 예제

• 클라이언트 인증
• 업서트 데이터
• 데이터 읽기
• 쿼리 데이터

클라이언트 인증

먼저 이 가이드의 앞부분에서 수집한 자격 증명을 사용하여 클라이언트를 인증합니다.

1. IDE(통합 개발 환경)에서 Program.cs 파일을 엽니다.

2. 파일 내의 기존 콘텐츠를 삭제합니다.

3. 다음 네임스페이스에 대한 using 지시문을 추가합니다.

   • System.Security.Authentication
   • Cassandra
   • Cassandra.Mapping

   using System.Security.Authentication;
   using Cassandra;
   using Cassandra.Mapping;
   

4. 이 가이드의 앞부분에서 수집된 자격 증명에 대한 문자열 상수 변수를 만듭니다. 변수 username, password, 및 contactPoint의 이름을 지정하십시오.

   const string username = "<username>";
   const string password = "<password>";
   const string contactPoint = "<contact-point>";
   

5. TLS(전송 계층 보안) 1.2 프로토콜을 사용하고 인증서 해지를 확인하고 추가 클라이언트 쪽 인증 유효성 검사를 수행하지 않도록 새 SSLoptions 개체를 만듭니다.

   SSLOptions sslOptions = new(
       sslProtocol: SslProtocols.Tls12,
       checkCertificateRevocation: true,
       remoteCertValidationCallback: (_, _, _, _) => true);
   

6. 흐름 Cluster 구문을 사용하여 새 Cluster.Builder() 개체를 생성합니다. 이전 단계에서 만든 자격 증명 및 구성 변수를 사용합니다.

   Cluster cluster = Cluster.Builder()
       .WithCredentials(username, password)
       .WithPort(10350)
       .AddContactPoint(contactPoint)
       .WithSSL(sslOptions)
       .Build();
   

7. 메서드 session를 사용하여 대상 키스페이스 ConnectAsync의 이름을 전달하면서 새 cosmicworks 변수를 만듭니다.

   using ISession session = await cluster.ConnectAsync("cosmicworks");
   

8. 새롭게 만든 mapper 변수를 전달하여 Mapper 클래스 생성자를 사용해 새로운 session 변수를 만듭니다.

   Mapper mapper = new(session);
   

데이터 Upsert

다음으로 새 데이터를 테이블에 업서트합니다. Upserting은 동일한 데이터가 테이블에 이미 있는지 여부에 따라 데이터를 적절하게 만들거나 바꿉니다.

1. 이 가이드의 앞부분에서 만든 테이블에 해당하는 필드로 명명된 Product 새 레코드 형식을 정의합니다.

   	유형
   Id	string
   Name	string
   Category	string
   Quantity	int
   Price	decimal
   Clearance	bool

   record Product
   {
       public required string Id { get; init; }
   
       public required string Name { get; init; }
   
       public required string Category { get; init; }
   
       public required int Quantity { get; init; }
   
       public required decimal Price { get; init; }
   
       public required bool Clearance { get; init; }
   }
   

   팁 (조언)

   .NET에서 이 형식을 다른 파일에 만들거나 기존 파일의 끝에 만들 수 있습니다.

2. 형식의 새 개체를 만듭니다 Product. 개체를 변수 product에 저장합니다.

   Product product = new()
   {
       Id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       Name = "Yamba Surfboard",
       Category = "gear-surf-surfboards",
       Quantity = 12,
       Price = 850.00m,
       Clearance = false
   };
   

3. InsertAsync 메서드를 비동기적으로 호출하여 이전 단계에서 만든 product 변수를 전달합니다.

   await mapper.InsertAsync(product);
   

데이터 읽기

그런 다음, 이전에 테이블에 업서트된 데이터를 읽습니다.

1. 동일한 readQuery 필드가 있는 항목과 일치하는 CQL 쿼리를 사용하여 명명된 id 새 문자열 변수를 만듭니다.

   string readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. 이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 id 문자열 변수를 만듭니다.

   string id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. SingleAsync<> 제네릭 메서드를 사용하여 저장된 readQuery쿼리를 실행하고, 변수를 id 인수로 전달하고, 출력을 형식에 Product 매핑합니다. 이 작업의 결과를 형식 변수에 저장합니다 Product.

   Product matchedProduct = await mapper.SingleAsync<Product>(readQuery, [id]);
   

쿼리 데이터

마지막으로 쿼리를 사용하여 테이블의 특정 필터와 일치하는 모든 데이터를 찾습니다.

1. CQL 쿼리와 필수 매개 변수를 사용하여 findQuery 및 category라는 문자열 변수를 생성하세요.

   string findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   string category = "gear-surf-surfboards";
   

2. 두 문자열 변수와 FetchAsync<> 제네릭 메서드를 사용하여 여러 결과를 비동기적으로 쿼리합니다. 이 쿼리의 결과를 이름이 지정된 IEnumerable<Product>형식 queriedProducts 의 변수에 저장합니다.

   IEnumerable<Product> queriedProducts = await mapper.FetchAsync<Product>(findQuery, [category]);
   

3. 루프를 foreach 사용하여 쿼리 결과를 반복합니다.

   foreach (Product queriedProduct in queriedProducts)
   {
       // Do something here with each result
   }
   

코드 실행

애플리케이션 디렉터리의 터미널을 사용하여 새로 만든 애플리케이션을 실행합니다.

dotnet run

자원을 정리하세요

계정이 더 이상 필요하지 않은 경우 리소스를 삭제하여 Azure 구독에서 계정을 제거합니다.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

다음 단계