빠른 시작 가이드: Go용 Apache Cassandra 클라이언트 라이브러리를 위한 Azure Cosmos DB

적용 대상: ✅ Apache Cassanda

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

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

필수 조건

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

Azure Cloud Shell에서 최신 버전의 Azure CLI입니다.
- CLI 참조 명령을 로컬로 실행하려면 명령을 사용하여 Azure CLI에 로그인합니다 az login .

Go 1.24 이상

설치

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

계정 만들기

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

Azure CLI
Azure Portal

대상 리소스 그룹이 아직 없는 경우 이 명령을 사용하여 az group create 구독에 새 리소스 그룹을 만듭니다.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

이 az cosmosdb create 명령을 사용하여 기본 설정으로 Apache Cassandra용 새 Azure Cosmos DB 계정을 만듭니다.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

az cosmosdb cassandra keyspace create을 사용하여 cosmicworks라는 새 키스페이스를 생성합니다.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

여러 줄 Bash 명령을 사용하여 스키마를 나타내는 새 JSON 개체를 만듭니다. 그런 다음, az cosmosdb cassandra table create 명령을 사용하여 products이라는 새 테이블을 만듭니다.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Azure Portal에 로그인합니다(https://portal.azure.com).
전역 검색 창에 Azure Cosmos DB를 입력합니다.
서비스 내에서 Azure Cosmos DB를 선택합니다.
Azure Cosmos DB 창에서 만들기를 선택한 다음, 다른 탭 내에서 Apache Cassandra용 Azure Cosmos DB를 선택합니다.
계정 유형에 대한 RU(요청 단위) 데이터베이스 계정을 선택합니다.

기본 창에서 다음 옵션을 구성한 다음 검토 + 만들기를 선택합니다.

	가치
워크로드 유형	학습
구독	Azure 구독 선택
리소스 그룹	새 리소스 그룹을 만들거나 기존 리소스 그룹을 선택합니다.
계정 이름	전역적으로 고유한 이름 입력
가용성 영역	비활성화
위치	구독에 대해 지원되는 Azure 지역 선택

팁 (조언)

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다. 총 계정 처리량을 초당 1,000개 요청 단위(RU/s)로 제한하거나 무료 계층을 사용하도록 계정을 구성하여 비용을 최소화할 수도 있습니다.

검토 + 만들기 창에서 계정 유효성 검사가 성공적으로 완료될 때까지 기다린 다음 만들기를 선택합니다.
포털이 자동으로 배포 창으로 이동합니다. 배포가 완료되기를 기다립니다.
배포가 완료되면 리소스로 이동하여 Apache Cassandra 계정의 새 API로 이동합니다.
리소스 메뉴에서 데이터 탐색기 옵션을 선택합니다.
데이터 탐색기에서 + 새 테이블을 선택합니다.

테이블 추가 대화 상자에서 다음 옵션을 구성한 다음 확인을 선택합니다.

	가치
Keyspace	새로 만들기
키스페이스 이름	`cosmicworks`
테이블 이름	`product`
테이블 스키마	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

팁 (조언)

지정하지 않은 옵션은 기본값으로 그대로 둘 수 있습니다.

자격 증명 가져오기

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

Azure CLI
Azure Portal

계정의 연락처 지점 및 사용자 이름을 가져오는 데 사용합니다 az cosmosdb show .

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

이전 명령 출력의 contactPoint 값 및 username 속성을 기록합니다. 이러한 속성의 값은 이 가이드를 진행할 때 라이브러리를 사용하여 계정에 연결하는 데 사용하는 연락처 와 사용자 이름입니다.

계정의 az cosmosdb keys list 가져오는 데 사용합니다.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

이전 명령의 primaryMasterKey 출력에서 속성 값을 기록합니다. 이 속성의 값은 이 가이드의 뒷부분에서 라이브러리를 사용하여 계정에 연결하는 데 사용하는 암호 입니다.

개발 환경 준비

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

빈 디렉터리에서 시작합니다.
새 Go 모듈을 만듭니다.
```
go mod init quickstart
```
github.com/apache/cassandra-gocql-driver/v2 Go에서 패키지를 가져옵니다.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
main.go 파일을 만듭니다.
Go 애플리케이션 상용구 추가
```
package main

func main() {    
}
```
중요합니다

이 가이드의 나머지 단계에서는 main 함수 내에 코드를 추가한다고 가정합니다.

개체 모델

	설명
`Cluster`	클러스터에 대한 특정 연결을 나타냅니다.
`Session`	클러스터에 대한 특정 연결을 보유하는 엔터티

클라이언트 인증

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

IDE(통합 개발 환경)에서 main.go 파일을 엽니다.
함수 내에서 main 패키지와 github.com/apache/cassandra-gocql-driver/v2 함께 다음 패키지를 가져옵니다.
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
이 가이드의 앞부분에서 수집된 자격 증명에 대한 문자열 변수를 만듭니다. 변수 username, password, 및 contactPoint의 이름을 지정하세요.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
이전 단계에서 지정된 자격 증명을 사용하여 형식의 PasswordAuthenticator 인스턴스를 구성합니다. authentication라는 변수에 결과를 저장합니다.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
TLS(전송 계층 보안) 1.2의 최소 버전으로 인스턴스 SslOptions 를 구성하고 변수를 contactPoint 대상 서버 이름으로 구성합니다. sslOptions라는 변수에 결과를 저장합니다.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
새 클러스터 사양을 NewCluster 및 contactPoint 변수를 사용하여 만듭니다.
```
cluster := gocql.NewCluster(contactPoint)
```
이전 단계에서 만든 자격 증명 및 구성 변수를 사용하여 클러스터 사양 개체를 구성합니다.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
이러한 정적 값을 사용하여 클러스터 사양 개체의 나머지 부분을 구성합니다.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
를 사용하여 CreateSession클러스터에 연결하는 새 세션을 만듭니다.
```
session, _ := cluster.CreateSession()
```
Close 함수가 반환된 후 main 함수를 호출하도록 세션을 구성합니다.
```
defer session.Close()
```
새 Background 컨텍스트 개체를 만들고 변수에 ctx 저장합니다.
```
ctx := context.Background()
```

경고

인증을 간소화하기 위해 이 가이드에서는 TLS(전체 전송 계층 보안) 유효성 검사를 사용할 수 없습니다. 프로덕션 배포의 경우 유효성 검사를 완전히 사용하도록 설정합니다.

데이터 Upsert

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

이 가이드의 앞부분에서 만든 테이블에 해당하는 필드로 명명 Product 된 새 형식을 정의합니다.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
팁 (조언)

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

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

product := Product {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

새 행을 삽입하기 위해 CQL(Cassandra Query Language) 쿼리로 명명된 insertQuery 새 문자열 변수를 만듭니다.

insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`

Query 및 ExecContext 함수를 사용하여 쿼리를 실행합니다. 변수의 product 다양한 속성을 쿼리 매개 변수로 전달합니다.

_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)

데이터 읽기

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

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

readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`

이 가이드의 앞부분에서 만든 제품과 동일한 값으로 명명된 id 문자열 변수를 만듭니다.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
이 작업의 결과를 저장할 다른 matchedProduct 변수를 만듭니다.
```
var matchedProduct Product
```

Query, Consistency및 IterContext함수를 함께 사용하여 쿼리와 Scan 일치하는 단일 항목을 찾고 변수에 해당 속성을 matchedProduct 할당합니다.

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

쿼리 데이터

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

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

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Query, Consistency및 IterContext함수를 함께 사용하여 쿼리와 Scanner 일치하는 여러 항목을 반복할 수 있는 스캐너를 만듭니다.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Next 및 Scan 함수를 사용하여 쿼리 결과를 반복하고 각 결과의 속성을 내부 queriedProduct 변수에 할당합니다.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

코드 실행

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

go run .

자원을 정리하세요