使用 Golang 和 Azure 门户通过适用于 MongoDB 的 Azure Cosmos DB API 构建控制台应用

Azure Cosmos DB 是 21Vianet 提供的多区域分布式多模型数据库服务。 可快速创建和查询文档数据库,这些数据库受益于 Azure Cosmos DB 核心的多区域分布和水平缩放功能。

本快速入门演示了如何使用以 Golang 编写的现有 MongoDB 应用,并使用适用于 MongoDB 的 Azure Cosmos DB API 将其连接到支持 MongoDB 客户端连接的 Azure Cosmos DB 数据库。

换而言之,Golang 应用程序仅知道它要使用适用于 MongoDB 的 Azure Cosmos DB API 连接到某个数据库。 应用程序完全知道数据存储在 Azure Cosmos DB 中。

先决条件

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

    对于本教程,可以使用 Azure Cosmos DB 模拟器,其连接字符串为:

    mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true
    
  • Go 以及 Go 语言的基础知识。

  • IDE — GoLand(由 Jetbrains 推出)、Visual Studio Code(由 Microsoft 推出)或 Atom。 在本教程中,我将使用 GoLand。

创建数据库帐户

  1. 在新窗口中,登录到 Azure 门户
  2. 在左菜单中,依次单击“创建资源”、“数据库”,然后在“Azure Cosmos DB”下单击“创建”。

    Azure 门户的屏幕截图,其中突出显示了“更多服务”和“Azure Cosmos DB”

  3. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos DB 帐户的设置。

    设置 Description
    订阅 订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 新建

    然后输入在 ID 中提供的同一唯一名称
    选择“新建”。 然后输入帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    帐户名 输入唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 由于 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一的 ID。

    该 ID 只能使用小写字母、数字和连字符 (-) 字符。 它的长度必须介于 3 到 31 个字符之间。
    API “用于 MongoDB 的 Azure Cosmos DB”API API 确定要创建的帐户的类型。 Azure Cosmos DB 提供两种 API:适用于文档数据库的 Core(SQL) 和适用于文档数据库的 MongoDB。 目前,你必须为每种 API 创建单独的帐户。

    选择“MongoDB”,因为本快速入门将创建使用 MongoDB API 的表。
    位置 选择离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。

    选择“查看 + 创建”。 可以跳过“网络”和“标记”部分。

    Azure Cosmos DB 的“新建帐户”页

  4. 创建帐户需要几分钟时间。 等待门户中显示“祝贺你!具有 MongoDB 的网络协议兼容性的 Cosmos 帐户已准备就绪”页面。

    Azure 门户“通知”窗格

克隆示例应用程序

克隆示例应用程序,并安装所需包。

  1. 在 GOROOT\src 文件夹(默认位于 C:\Go\ 中)中创建名为 CosmosDBSample 的文件夹。
  2. 使用 git 终端窗口(例如 git bash)运行以下命令,将示例存储库克隆到 CosmosDBSample 文件夹中。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-mongodb-golang-getting-started.git
    
  3. 运行以下命令以获取 mgo 包。

    go get gopkg.in/mgo.v2
    

mgo 驱动程序是适用于 Go 语言MongoDB 驱动程序,该语言采用很简单的 API 和标准的 GO 惯用语,实现了多种经过严格测试的精选功能。

更新连接字符串

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。

  1. 单击左侧导航菜单中的“快速启动”,并单击“其他”,查看 Go 应用程序所需的连接字符串信息。

  2. 在 Goglang 的 GOROOT\CosmosDBSample 目录中打开 main.go 文件,并使用 Azure 门户中的连接字符串信息更新以下代码行,如以下屏幕截图所示。

    数据库名称是 Azure 门户连接字符串窗格中 Host 值的前缀。 就下图所示帐户来说,数据库名称为 golang-coach。

    Database: "The prefix of the Host value in the Azure portal",
    Username: "The Username in the Azure portal",
    Password: "The Password in the Azure portal",
    

    Azure 门户的“快速启动”窗格中的“其他”选项卡,显示连接字符串信息

  3. 保存 main.go 文件。

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。 否则,可以跳到运行应用

以下代码片段全部摘自 main.go 文件。

将 Go 应用连接到 Azure Cosmos DB

Azure Cosmos DB 支持启用了 SSL 的 MongoDB。 若要连接到启用了 SSL 的 MongoDB,需在 mgo.DialInfo 中定义 DialServer 函数,并使用 tls.Dial 函数进行连接。

以下 Golang 代码片段通过适用于 MongoDB 的 Azure Cosmos DB API 连接 Go 应用。 DialInfo 类包含与 MongoDB 群集建立会话的选项。

// DialInfo holds options for establishing a session with a MongoDB cluster.
dialInfo := &mgo.DialInfo{
    Addrs:    []string{"golang-couch.documents.azure.cn:10255"}, // Get HOST + PORT
    Timeout:  60 * time.Second,
    Database: "database", // It can be anything
    Username: "username", // Username
    Password: "Azure database connect password from Azure Portal", // PASSWORD
    DialServer: func(addr *mgo.ServerAddr) (net.Conn, error) {
        return tls.Dial("tcp", addr.String(), &tls.Config{})
    },
}

// Create a session which maintains a pool of socket connections
// to our Azure Cosmos DB MongoDB database.
session, err := mgo.DialWithInfo(dialInfo)

if err != nil {
    fmt.Printf("Can't connect to mongo, go error %v\n", err)
    os.Exit(1)
}

defer session.Close()

// SetSafe changes the session safety mode.
// If the safe parameter is nil, the session is put in unsafe mode, 
// and writes become fire-and-forget,
// without error checking. The unsafe mode is faster since operations won't hold on waiting for a confirmation.
// 
session.SetSafe(&mgo.Safe{})

没有 SSL 连接时,使用 mgo.Dial() 方法。 对于 SSL 连接,mgo.DialWithInfo() 方法是必需的。

可以使用 DialWIthInfo{} 对象的实例来创建会话对象。 建立会话以后,即可使用以下代码片段访问集合:

collection := session.DB("database").C("package")

创建文档

// Model
type Package struct {
    Id bson.ObjectId  `bson:"_id,omitempty"`
    FullName      string
    Description   string
    StarsCount    int
    ForksCount    int
    LastUpdatedBy string
}

// insert Document in collection
err = collection.Insert(&Package{
    FullName:"react",
    Description:"A framework for building native apps with React.",
    ForksCount: 11392,
    StarsCount:48794,
    LastUpdatedBy:"shergin",

})

if err != nil {
    log.Fatal("Problem inserting data: ", err)
    return
}

查询或读取文档

Azure Cosmos DB 支持对存储在每个集合中的 JSON 文档进行各种查询。 下面的示例代码演示可针对集合中文档运行的查询。

// Get a Document from the collection
result := Package{}
err = collection.Find(bson.M{"fullname": "react"}).One(&result)
if err != nil {
    log.Fatal("Error finding record: ", err)
    return
}

fmt.Println("Description:", result.Description)

更新文档

// Update a document
updateQuery := bson.M{"_id": result.Id}
change := bson.M{"$set": bson.M{"fullname": "react-native"}}
err = collection.Update(updateQuery, change)
if err != nil {
    log.Fatal("Error updating record: ", err)
    return
}

删除文档

Azure Cosmos DB 支持删除 JSON 文档。

// Delete a document
query := bson.M{"_id": result.Id}
err = collection.Remove(query)
if err != nil {
   log.Fatal("Error deleting record: ", err)
   return
}

运行应用程序

  1. 在 Goglang 中,确保 GOPATH(依次单击“文件”、“设置”、“Go”、“GOPATH”即可找到)包含安装 gopkg 时所在的位置,默认为 USERPROFILE\go。
  2. 注释掉用于删除文档的行(即第 103-107 行),这样就能在运行应用后看到文档。
  3. 在 Goglang 中依次单击“运行”、“运行‘生成 main.go 并运行’”。

    应用完成后,将会显示在创建文档中创建的文档的说明。

    Description: A framework for building native apps with React.
    
    Process finished with exit code 0
    

    Goglang,显示应用的输出

在数据资源管理器中查看文档

回到 Azure 门户,在数据资源管理器中查看文档。

  1. 在左侧导航菜单中单击“数据资源管理器(预览)”,展开“golang-coach”、“包”,并单击“文档”。 在“文档”选项卡中单击“_id”,在右窗格中显示文档。

    数据资源管理器,显示新创建的文档

  2. 然后即可使用内联文档,单击“更新”将其保存。 也可删除该文档,或者创建新文档或查询。

在 Azure 门户中查看 SLA

在 Azure 门户中监视帐户中资源的吞吐量、存储空间、可用性、延迟和一致性。 让我们快速了解一下这些指标。

  1. 在导航菜单中单击“指标”。

    Azure 门户中的指标

  2. 单击每个选项卡,以便了解 Azure Cosmos DB 提供的指标。

    Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图表都提供了一行,显示是否违反了任何 SLA。 Azure Cosmos DB 通过此套指标使监视 SLA 的操作更透明。

    Azure Cosmos DB 指标套件

清理资源

如果不打算继续使用此应用,请按照以下步骤删除本快速入门中创建的所有资源,以免产生任何费用:

  1. 在 Azure 门户的最左侧选择“资源组”,,然后选择创建的资源组。

    如果左侧菜单处于折叠状态,请单击 “展开”按钮 将其展开。

    Azure 门户中的指标

  2. 在新窗口中选择资源组,然后单击“删除资源组”。

    Azure 门户中的指标

  3. 在新窗口中键入要删除的资源组的名称,然后单击“删除”。

后续步骤

本快速入门教程已介绍如何创建 Azure Cosmos DB 帐户和使用 API for MongoDB 运行 Golang 应用。 现在可以将其他数据导入 Cosmos DB 帐户。