快速入门：适用于 Go 的 Azure Cosmos DB for Apache Cassandra 客户端库

适用于 Go 的 Azure Cosmos DB for Apache Cassandra 客户端库入门，用于存储、管理和查询非结构化数据。 按照本指南中的步骤创建新帐户、安装 Go 客户端库、连接到帐户、执行常见作以及查询最终示例数据。

API 参考文档 | 库源代码 | 包 （Go）

先决条件

• Azure 订阅服务

  • 如果没有 Azure 订阅，可在开始前创建一个试用帐户。

• 如果在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

• Go 1.24 或更高版本

设置

首先，为本指南设置帐户和开发环境。 本部分将指导你完成创建帐户、获取其凭据以及准备开发环境的过程。

创建帐户

首先，创建用于 Apache Cassandra 帐户的 API。 创建帐户后，创建密钥空间和表资源。

获取凭据

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

准备开发环境

然后，使用新项目和客户端库配置开发环境。 在转到本指南的其余部分之前，此步骤是最后一个必需的先决条件。

1. 从空目录中开始。

2. 创建新的 Go 模块。

   go mod init quickstart
   

3. 将github.com/apache/cassandra-gocql-driver/v2包导入 Go。

   go get github.com/apache/cassandra-gocql-driver/v2
   

4. 创建 main.go 文件。

5. 添加 Go 应用程序代码模板。

   package main
   
   func main() {    
   }
   

   重要

   本指南中的剩余步骤假定你在函数中添加 main 代码。

对象模型

代码示例

• 对客户端进行身份验证
• 更新插入数据
• 读取数据
• 查询数据

对客户端进行身份验证

首先，使用本指南前面收集的凭据对客户端进行身份验证。

1. 在集成开发环境中打开 main.go 文件（IDE）。

2. 在 main 函数中，导入以下包以及 github.com/apache/cassandra-gocql-driver/v2 包：

   • context
   • crypto/tls

   import (
       "context"
       "crypto/tls"
       "github.com/apache/cassandra-gocql-driver/v2"
   )
   

3. 为本指南前面收集的凭据创建字符串变量。 为变量 username命名， password以及 contactPoint。

   username := "<username>"
   password := "<password>"
   contactPoint := "<contact-point>"
   

4. 使用前几步中指定的凭据，配置一个 PasswordAuthenticator 类型的实例。 将结果存储在名为 authentication 的变量中。

   authentication := gocql.PasswordAuthenticator{
       Username: username,
       Password: password,
   }
   

5. 配置一个实例SslOptions，要求最低传输层安全性版本为 TLS 1.2，并使用contactPoint变量作为目标服务器名称。 将结果存储在名为 sslOptions 的变量中。

   sslOptions := &gocql.SslOptions{
       Config: &tls.Config{
           MinVersion: tls.VersionTLS12,
           ServerName: contactPoint,
       },
   }
   

6. 使用 NewCluster 变量和 contactPoint 变量创建新的群集规范。

   cluster := gocql.NewCluster(contactPoint)
   

7. 使用前面步骤中创建的凭据和配置变量配置群集规范对象。

   cluster.SslOpts = sslOptions
   cluster.Authenticator = authentication
   

8. 使用这些静态值配置群集规范对象的其余部分。

   cluster.Keyspace = "cosmicworks"
   cluster.Port = 10350
   cluster.ProtoVersion = 4    
   

9. 创建一个新的会话，使用 CreateSession 连接到群集。

   session, _ := cluster.CreateSession()
   

10. 配置会话以在Close函数返回后调用main函数。

    defer session.Close()
    

11. 创建新的 Background 上下文对象并将其存储在变量中 ctx 。

    ctx := context.Background()
    

更新插入数据

接下来，将新数据向上插入表中。 Upserting 可确保根据表中是否已存在相同的数据，适当地创建或替换数据。

1. 定义一个名为 Product 的新类型，使其字段与本指南前面创建的表格相对应。

   type Product struct {
       id        string
       name      string
       category  string
       quantity  int
       clearance bool
   }
   

   小窍门

   在 Go 中，可以在另一个文件中创建此类型，或在现有文件末尾创建它。

2. 创建一个Product类型的新对象。 将对象存储在名为 .. 的 product变量中。

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

3. 创建一个名为 Cassandra 查询语言（CQL）查询的新字符串变量 insertQuery ，用于插入新行。

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

4. 使用Query和ExecContext函数来运行查询。 以查询参数的形式传入变量的各种属性 product 。

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

读取数据

然后，读取以前插入到表中的数据。

1. 创建一个名为 CQL 查询的新字符串变量 readQuery ，该查询与具有相同 id 字段的项匹配。

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

2. 创建与本指南前面创建的产品相同的值的字符串变量 id 。

   id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
   

3. 创建另一个名为 matchedProduct 用于存储此作结果的变量。

   var matchedProduct Product
   

4. 使用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,
   )
   

查询数据

最后，使用查询查找与表中特定筛选器匹配的所有数据。

1. 创建名为 findQuery 和 category 的字符串变量，包括 CQL 查询和必需参数。

   findQuery := `
       SELECT
           id,
           name,
           category,
           quantity,
           clearance
       FROM
           product
       WHERE
           category = ?
       ALLOW FILTERING
   `
   
   category := "gear-surf-surfboards"
   

2. 结合使用Query、Consistency、IterContext和Scanner函数来创建可以遍历与查询匹配的多个项目的扫描程序。

   queriedProducts := session.Query(
       findQuery, 
       &category,
   ).Consistency(gocql.All).IterContext(ctx).Scanner()
   

3. 使用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 .

清理资源

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

后续步骤