빠른 시작: `gocql` 클라이언트를 통해 Go 앱을 빌드하여 Azure Cosmos DB for Apache Cassandra 데이터 관리

아티클
02/13/2024

적용 대상: Cassandra

Azure Cosmos DB는 글로벌 배포 및 수평적 크기 조정 기능을 사용하여 문서, 테이블, 키 값 및 그래프 데이터베이스를 빠르게 만들고 쿼리할 수 있는 다중 모델 데이터베이스 서비스입니다. 이 빠른 시작에서는 Azure Cosmos DB for Apache Cassandra 계정을 만들어 시작합니다. 그런 다음, Go 애플리케이션을 실행하여 Cassandra 키스페이스, 테이블을 만들고 몇 가지 작업을 실행합니다. 이 Go 앱은 Go 언어용 Cassandra 클라이언트인 gocql을 사용합니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정 만들기 또는 Azure 구독 없이 무료로 Azure Cosmos DB를 사용할 수 있습니다.
컴퓨터에 설치된 Go 및 Go에 대한 실무 지식.
Git

데이터베이스 계정 만들기

데이터베이스를 만들려면 먼저 Azure Cosmos DB로 Cassandra 계정을 만들어야 합니다.

Azure Portal 메뉴 또는 홈 페이지에서 리소스 만들기를 선택합니다.
새로 만들기 페이지에서 Azure Cosmos DB를 검색하여 선택합니다.
Azure Cosmos DB 페이지에서 생성를 선택합니다.
API 페이지에서 Cassandra 섹션 아래의 만들기를 선택합니다.

API는 만들 계정의 형식을 결정합니다. Azure Cosmos DB는 문서 데이터베이스용 NoSQL, 그래프 데이터베이스용 Gremlin, 문서 데이터베이스용 MongoDB, Azure Table 및 Cassandra 등 5개의 API를 제공합니다. 각 API에 대한 별도의 계정을 만들어야 합니다.

이 빠른 시작에서는 API for Cassandra와 함께 작동하는 테이블을 만들고 있으므로 Cassandra를 선택합니다.

API for Cassandra에 대해 자세히 알아봅니다.

Azure Cosmos DB 계정 만들기 페이지에서 새 Azure Cosmos DB 계정에 대한 기본 설정을 입력합니다.

설정	값	Description
구독	구독	이 Azure Cosmos DB 계정에 사용할 Azure 구독을 선택합니다.
리소스 그룹	새로 만들기 그런 다음, 계정 이름과 같은 이름 입력	새로 만들기를 선택합니다. 그런 다음, 계정의 새 리소스 그룹 이름을 입력합니다. 간단히 하기 위해 Azure Cosmos DB 계정 이름과 동일한 이름을 사용합니다.
계정 이름	고유한 이름 입력	내 Azure Cosmos DB 계정을 식별하는 고유한 이름을 입력합니다. 계정 URI는 고유한 계정 이름에 cassandra.cosmos.azure.com이 추가됩니다. 계정 이름은 소문자, 숫자 및 하이픈(-) 문자만 포함할 수 있으며, 3-31자여야 합니다.
위치	사용자와 가장 가까운 지역	Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.
용량 모드	프로비저닝된 처리량 또는 서버리스	프로비저닝된 처리량을 선택하여 프로비저닝된 처리량 모드에서 계정을 만듭니다. 서버리스를 선택하여 서버리스 모드에서 계정을 만듭니다.
Azure Cosmos DB 체험 계층 할인 적용	적용 또는 적용 안 함	Azure Cosmos DB 무료 계층을 사용하면 계정 하나에 처음 1000RU/초 및 25GB의 스토리지가 별도의 비용 없이 제공됩니다. 체험 계층에 대해 자세히 알아보세요.
총 계정 처리량 제한	계정의 처리량을 제한하려면 선택합니다.	이는 계정의 총 처리량을 특정 값으로 제한하려는 경우에 유용합니다.

참고 항목

Azure 구독당 최대 1개의 체험 계층 Azure Cosmos DB 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다. 체험 계층 할인을 적용하는 옵션이 표시되지 않으면 구독의 다른 계정에서 이미 체험 계층을 사용하도록 설정되었음을 의미합니다.

The new account page for Azure Cosmos DB for Apache Cassandra

전역 배포 탭에서 다음 세부 정보를 구성합니다. 이 빠른 시작의 목적을 위해 기본값을 그대로 둘 수 있습니다.

설정	값	Description
지리적 중복	사용 안 함	지역에 쌍 영역을 페어링하여 계정에서 글로벌 배포를 사용하거나 사용하지 않도록 설정합니다. 나중에 계정에 더 많은 지역을 추가할 수 있습니다.
다중 지역 쓰기	사용 안 함	다중 영역 쓰기 기능을 사용하면 전 세계의 데이터베이스 및 컨테이너에 대해 프로비저닝된 처리량을 활용할 수 있습니다.
가용성 영역	사용 안 함	가용성 영역은 Azure 지역 내의 격리된 위치입니다. 각 영역은 독립된 전원, 냉각 및 네트워킹을 갖춘 하나 이상의 데이터 센터로 구성됩니다.

참고 항목

용량 모드로 서버리스를 선택한 경우 다음 옵션을 사용할 수 없습니다.

무료 계층 할인 적용
지리적 중복
다중 지역 쓰기

필요에 따라 다음 탭에서 추가 세부 정보를 구성할 수 있습니다.
- 네트워킹 - 가상 네트워크에서 액세스를 구성합니다.
- 백업 정책 - 주기적 또는 지속적인 백업 정책을 구성합니다.
- 암호화 - 서비스 관리형 키 또는 고객 관리형 키를 사용합니다.
- 태그 - 태그는 동일한 태그를 여러 개의 리소스 및 리소스 그룹에 적용하여 리소스를 범주화하고 통합된 청구를 볼 수 있는 이름/값 쌍입니다.
검토 + 만들기를 선택합니다.
계정 설정을 검토한 다음, 만들기를 선택합니다. 계정을 만드는 데 몇 분이 걸립니다. 포털 페이지에 배포가 완료됨이 표시되기를 기다립니다.
리소스로 이동을 선택하여 Azure Cosmos DB 계정 페이지로 이동합니다.

샘플 애플리케이션 복제

GitHub에서 애플리케이션을 복제하여 시작합니다.

명령 프롬프트를 열고 git-samples라는 새 폴더를 만듭니다.
```
md "C:\git-samples"
```
git bash와 같은 git 터미널 창을 엽니다. cd 명령을 사용하여 새 폴더로 변경하고 샘플 앱을 설치합니다.
```
cd "C:\git-samples"
```
다음 명령을 실행하여 샘플 리포지토리를 복제합니다. 이 명령은 컴퓨터에서 샘플 앱의 복사본을 만듭니다.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

코드 검토

이 단계는 선택 사항입니다. 코드로 데이터베이스 리소스를 만드는 방법을 알아보려는 경우 다음 코드 조각을 검토할 수 있습니다. 그렇지 않으면 애플리케이션 실행으로 건너뛸 수 있습니다.

GetSession 함수(utils\utils.go의 일부)는 삽입, 찾기 등의 클러스터 작업을 실행하는 데 사용되는 *gocql.Session을 반환합니다.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Azure Cosmos DB Cassandra 호스트는 gocql.NewCluster 함수에 전달되어 *gocql.ClusterConfig 구조체를 가져온 다음, 사용자 이름, 암호, 포트 및 적절한 TLS 버전(HTTPS/SSL/TLS 암호화 보안 요구 사항)을 사용하도록 구성됩니다.

그런 다음, main 함수(main.go)에서 GetSession 함수를 호출합니다.

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

연결 정보 및 자격 증명은 환경 변수 형식으로 수락됩니다(init 메서드에서 확인됨).

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

그런 다음, keyspace 및 table 생성으로 시작하는 Azure Cosmos DB에서 다양한 작업(operations\setup.go의 일부)을 실행하는 데 사용됩니다.

이름에서 알 수 있듯이 DropKeySpaceIfExists 함수는 존재하는 경우에만 keyspace를 삭제합니다.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

CreateKeySpace 함수는 keyspace(user_profile)를 만드는 데 사용됩니다.

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

그러면 CreateUserTable 함수를 처리하는 테이블 생성(user)이 수행됩니다.

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

키스페이스 및 테이블이 만들어지면 CRUD 작업(operations\crud.go의 일부)을 호출합니다.

InsertUser는 User를 만드는 데 사용됩니다. Bind를 사용하여 사용자 정보(ID, 이름 및 도시)를 쿼리 인수로 설정합니다.

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser는 특정 사용자 ID를 사용하여 사용자(model\user.go)를 검색하는 데 사용하는 반면 Scan가 사용자 특성(Cassandra에서 반환)을 개별 변수(userid, name, city)에 바인딩하는 것은 검색 쿼리 결과로 얻은 결과를 사용할 수 있는 방법 중 하나일 뿐입니다.

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers는 모든 사용자를 페치하는 데 사용됩니다. SliceMap는 map의 조각 형식으로 모든 사용자 정보를 가져오는 약어로 사용됩니다. 각 map을 키-값 쌍으로 간주합니다. 여기서 열 이름(예: user_id)은 해당 값과 함께 키입니다.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

사용자 정보의 각 map은 해당 열에서 값을 추출하고 이를 사용하여 User 구조체의 인스턴스를 만드는 mapToUser 함수를 사용하여 User로 변환됩니다.

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

애플리케이션 실행

앞에서 설명한 것처럼 애플리케이션은 환경 변수 형식으로 연결 및 자격 증명을 허용합니다.

Azure Portal의 Azure Cosmos DB 계정에서 연결 문자열을 선택합니다.

다음 특성(CONTACT POINT, PORT, USERNAME 및 PRIMARY PASSWORD)의 값을 복사하여 해당 환경 변수로 설정합니다.

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

터미널 창에서 올바른 폴더로 변경합니다. 예시:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

터미널에서 다음 명령을 실행하여 애플리케이션을 시작합니다.

go run main.go

터미널 창에는 키스페이스 및 테이블 설정, 사용자 만들기 등의 다양한 작업에 대한 알림이 표시됩니다.
Azure Portal에서 데이터 탐색기를 열어 이 새 데이터를 쿼리/수정/사용합니다.

Azure Portal에서 SLA 검토

Azure Portal에서는 Azure Cosmos DB 계정 처리량, 스토리지, 가용성, 대기 시간 및 일관성을 모니터링합니다. Azure Cosmos DB SLA(서비스 수준 계약)와 관련된 메트릭 차트에는 실제 성능 대비 SLA 값이 표시됩니다. 이 메트릭 모음을 통해 SLA를 투명하게 모니터링할 수 있습니다.

메트릭 및 SLA를 검토하려면 다음을 수행합니다.

Azure Cosmos DB 계정의 탐색 메뉴에서 메트릭을 선택합니다.
대기 시간과 같은 탭을 선택하고, 오른쪽에서 시간 프레임을 선택합니다. 차트의 실제 및 SLA 줄을 비교합니다.
다른 탭의 메트릭을 검토합니다.

리소스 정리

앱과 Azure Cosmos DB 계정을 모두 사용했으면 추가로 비용을 지불하지 않도록 만든 Azure 리소스를 삭제할 수 있습니다. 리소스를 삭제하려면:

Azure Portal 검색 창에서 리소스 그룹을 검색하고 선택합니다.
목록에서 이 빠른 시작에서 만든 리소스 그룹을 선택합니다.
리소스 그룹 개요 페이지에서 리소스 그룹 삭제를 선택합니다.
새 창에서 삭제할 리소스 그룹의 이름을 입력한 다음, 삭제를 선택합니다.

다음 단계

이 빠른 시작에서는 API for Cassandra를 사용하여 Azure Cosmos DB 계정을 만들고 Cassandra 데이터베이스 및 컨테이너를 만드는 Go 앱을 실행하는 방법을 알아보았습니다. 이제 Azure Cosmos DB 계정으로 추가 데이터를 가져올 수 있습니다.

Azure Cosmos DB로 Cassandra 데이터 가져오기

다음을 통해 공유

빠른 시작: `gocql` 클라이언트를 통해 Go 앱을 빌드하여 Azure Cosmos DB for Apache Cassandra 데이터 관리

필수 조건

데이터베이스 계정 만들기

샘플 애플리케이션 복제

코드 검토

애플리케이션 실행

Azure Portal에서 SLA 검토

리소스 정리

다음 단계

추가 리소스

다음을 통해 공유

빠른 시작: gocql 클라이언트를 통해 Go 앱을 빌드하여 Azure Cosmos DB for Apache Cassandra 데이터 관리

필수 조건

데이터베이스 계정 만들기

샘플 애플리케이션 복제

코드 검토

애플리케이션 실행

Azure Portal에서 SLA 검토

리소스 정리

다음 단계

추가 리소스

빠른 시작: `gocql` 클라이언트를 통해 Go 앱을 빌드하여 Azure Cosmos DB for Apache Cassandra 데이터 관리