快速入門：組建具有 `gocql` 用戶端的 Go 應用程式來管理 Azure Cosmos DB for Apache Cassandra 資料

發行項
03/25/2024

適用於： Cassandra

Azure Cosmos DB 是多模型的資料庫服務，可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。在本快速入門中，您將從建立 Azure Cosmos DB for Apache Cassandra 帳戶開始。接著，您將執行 Go 應用程式來建立 Cassandra keyspace、資料表，並執行一些作業。此 Go 應用程式會使用 gocql，這是 Go 語言的 Cassandra 用戶端。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立一個。或免費試用 Azure Cosmos DB (不需 Azure 訂用帳戶)。
在您的電腦上安裝 Go，且具備 Go 的運用知識。
Git。

建立資料庫帳戶

您必須先使用 Azure Cosmos DB 建立 Cassandra 帳戶，才可以建立資料庫。

從 Azure 入口網站功能表或 [首頁] 頁面，選取 [建立資源]。
在 [新增] 頁面上，搜尋並選取 [Azure Cosmos DB]。
在 [Azure Cosmos DB] 頁面上，選取 [建立]。
在 [API] 頁面上的 [Cassandra] 區段下面選取 [建立]。

API 會決定要建立的帳戶類型。 Azure Cosmos DB 提供五個 API：NoSQL (適用於文件資料庫)、Gremlin (適用於圖形資料庫)、MongoDB (適用於文件資料庫)、Azure 資料表與 Cassandra。您必須為每個 API 建立個別帳戶。

選取 [Cassandra]，因為在此快速入門中，您會建立可搭配 API for Cassandra 使用的資料表。

深入了解適用於 Cassandra 的 API。

在 [建立 Azure Cosmos DB 帳戶] 頁面中，輸入新 Azure Cosmos DB 帳戶的基本設定。

設定	值	Description
訂用帳戶	您的訂用帳戶	選取您要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。
資源群組	新建然後，輸入與帳戶名稱相同的名稱	選取 [新建] 然後為您的帳戶輸入新的資源群組名稱。為求簡化，請使用與 Azure Cosmos DB 帳戶名稱相同的名稱。
客戶名稱	輸入唯一名稱	輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。您的帳戶 URI 將是 cassandra.cosmos.azure.com，並附加至您的唯一帳戶名稱。帳戶名稱只能使用小寫字母、數字和連字號 (-)，且長度必須介於 3 到 31 個字元之間。
Location	最接近使用者的區域	選取用來裝載 Azure Cosmos DB 帳戶的地理位置。使用最接近使用者的位置，讓他們能以最快速度存取資料。
容量模式	佈建輸送量或無伺服器	選取 [佈建的輸送量]，以佈建的輸送量模式建立帳戶。選取 [無伺服器]，以無伺服器模式建立帳戶。
申請 Azure Cosmos DB 免費階層折扣	適用或不適用	使用 Azure Cosmos DB 免費層，您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。深入了解免費層。
限制帳戶總輸送量	選取此選項會限制帳戶的輸送量	如果您想要將帳戶的總輸送量限制為特定值，這會很有用。

注意

每個 Azure 訂用帳戶最多可以有一個免費層的 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 終端機視窗，例如 Git Bash。使用 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")
    }
}

然後會用來在 Azure Cosmos DB 執行各種作業 (operations\setup.go的一部分)，從 keyspace 和 table 建立開始。

如其名所示，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")
}

接下來就是建立資料表 (user)，以處理 CreateUserTable 函式

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")
}

建立 keyspace 和資料表後，我們會叫用 CRUD 作業 (operations\crud.go 的一部分)。

InsertUser 用來建立 User，並會使用 Bind 將使用者資訊 (識別碼、名稱和城市) 設定為查詢引數

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 用來使用特定的使用者識別碼來搜尋使用者 (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 都會使用 mapToUser 函式轉換成 User，而此函式只會從其個別的資料行中擷取值，並用該值建立 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 入口網站中的 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

終端機視窗會顯示各種作業的通知，包括 keyspace 和資料表設定、使用者建立等。
在 Azure 入口網站中，開啟 [資料總管] 以查詢、修改及使用這個新資料。

在 Azure 入口網站中檢閱 SLA

Azure 入口網站會監視 Azure Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。與 Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。此計量套件可讓您以更透明的方式監視監視 SLA。

若要檢閱計量和 SLA：

在 Azure Cosmos DB 帳戶導覽功能表中，選取 [計量]。
選取一個索引標籤 (例如 [延遲])，並在右側選取時間範圍。比較圖表中的實際和 SLA 的資料行。
檢閱其他索引標籤中的計量。

清除資源

完成您的應用程式和 Azure Cosmos DB 帳戶之後，您可以將建立的 Azure 資源刪除，以免產生更多費用。若要刪除資源：

在 Azure 入口網站的 [搜尋] 列中，搜尋並選取 [資源群組]。
在該清單中，選取您在本快速入門中建立的資源群組。
在 [資源群組] 的 [概觀] 頁面中，選取 [刪除資源群組]。
在下個視窗中輸入要刪除的資源群組名稱，然後選取 [刪除]。

下一步

在本快速入門中，您已了解如何使用適用於 Cassandra 的 API 建立 Azure Cosmos DB 帳戶，並已執行 Go 應用程式建立 Cassandra 資料庫和容器。您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。

將 Cassandra 資料匯入到 Azure Cosmos DB

快速入門：組建具有 gocql 用戶端的 Go 應用程式來管理 Azure Cosmos DB for Apache Cassandra 資料