快速入门:使用 gocql
客户端生成 Go 应用来管理 Azure Cosmos DB for Apache Cassandra 数据
适用对象: Cassandra
Azure Cosmos DB 是一种多模型数据库服务,可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图形数据库。 在本快速入门中,你将首先创建一个 Azure Cosmos DB for Apache Cassandra 帐户。 然后,你将运行一个 Go 应用程序来创建 Cassandra 密钥空间、表,并执行一些操作。 此 Go 应用使用 gocql,这是 Go 语言的 Cassandra 客户端。
先决条件
创建数据库帐户
在创建数据库之前,需通过 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 的表。
在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos DB 帐户的基本设置。
设置 值 说明 订阅 订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。 资源组 新建
然后,输入与帐户名称相同的名称。选择“新建”。 然后输入帐户的新资源组名称。 为简单起见,请使用与 Azure Cosmos DB 帐户名称相同的名称。 帐户名 输入唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 帐户 URI 将是追加到唯一帐户名称的“cassandra.cosmos.azure.cn” 。
帐户名称只能使用小写字母、数字及连字符 (-),必须为 3 到 31 个字符长。API Cassandra API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API:适用于文档数据库的 NoSQL、适用于图形数据库的 Gremlin、适用于文档数据库的 MongoDB、Azure 表和 Cassandra。 必须为每种 API 创建单独的帐户。
选择“Cassandra”,因为本快速入门将创建使用 API for Cassandra 的表。
详细了解 API for Cassandra。位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。 容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。 应用 Azure Cosmos DB 免费层折扣 “应用”或“不应用” 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。 注意
每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。
在“全局分发”选项卡中,配置以下详细信息。 对于本快速入门,可以保留默认值:
设置 值 说明 异地冗余 禁用 通过将你的区域与某个配对区域进行配对来启用或禁用帐户的多区域分发。 稍后可以将更多区域添加到帐户。 多区域写入 禁用 借助多区域写入功能,可以利用全中国的数据库和容器的预配吞吐量。 可用性区域 禁用 可用性区域是指 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
,该函数用于执行 insert、find 等群集操作。
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")
}
创建密钥空间和表后,调用 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
}
使用 mapToUser
函数将用户信息的每个 map
转换为 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
终端窗口显示各种操作的通知信息,包括密钥空间和表设置、用户创建等。
在 Azure 门户中,打开数据资源管理器,以查询、修改和处理这些新数据。
在 Azure 门户中查看 SLA
Azure 门户可监视 Azure Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。 与 Azure Cosmos DB 服务级别协议 (SLA) 关联的指标的图表显示与实际性能相比的 SLA 值。 此套指标使得监视 SLA 十分透明。
若要查看指标和 SLA,请执行以下操作:
请在 Azure Cosmos DB 帐户的导航菜单中选择“指标”。
选择一个选项卡,如“延迟”,然后选择右侧的时间范围。 比较图表上的“实际”和“SLA”线。
查看其他选项卡上的指标。
清理资源
执行完应用和 Azure Cosmos DB 帐户的操作以后,可以删除所创建的 Azure 资源,以免产生更多费用。 若要删除资源,请执行以下操作:
在 Azure 门户的“搜索”栏中,搜索并选择“资源组”。
从列表中选择为本快速入门创建的资源组。
在资源组“概览”页上,选择“删除资源组”。
在下一窗口中输入要删除的资源组的名称,然后选择“删除”。
后续步骤
本快速入门介绍了如何使用 API for Cassandra 创建 Azure Cosmos DB 帐户,以及如何运行用于创建 Cassandra 数据库和容器的 Go 应用。 现在可以将其他数据导入 Azure Cosmos DB 帐户了。