你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将 Azure Cosmos DB for NoSQL 与 Azure SDK for Go 配合使用

• 适用于:

  ✅ NoSQL

• .NET
• Node.js
• Java
• Python
• Go

在本快速入门中，你将使用 Azure SDK for Go 部署基本的 Azure Cosmos DB for Table 应用程序。 Azure Cosmos DB for Table 是一种无架构数据存储，允许应用程序在云中存储结构化表数据。 你将了解如何使用 Azure SDK for Go 在 Azure Cosmos DB 资源中创建表、行并执行基本任务。

API 参考文档 | 库源代码 | 包 (Go) | Azure Developer CLI

先决条件

• Azure 开发人员 CLI
• Docker Desktop
• Go 1.21 或更高版本

如果没有 Azure 帐户，请在开始前创建一个免费帐户。

初始化项目

使用 Azure Developer CLI (azd) 创建 Azure Cosmos DB for Table 帐户并部署容器化示例应用程序。 示例应用程序使用客户端库来管理、创建、读取和查询示例数据。

1. 在空目录中打开终端。

2. 如果尚未经过身份验证，请使用 azd auth login 向 Azure Developer CLI 进行身份验证。 按照该工具指定的步骤，使用首选 Azure 凭据向 CLI 进行身份验证。

   azd auth login
   

3. 使用 azd init 来初始化项目。

   azd init --template cosmos-db-nosql-go-quickstart
   

4. 在初始化期间，配置唯一的环境名称。

5. 使用 azd up 部署 Azure Cosmos DB 帐户。 Bicep 模板还部署示例 Web 应用程序。

   azd up
   

6. 在预配过程中，选择订阅、所需位置和目标资源组。 等待预配过程完成。 此过程可能需要大约 5 分钟。

7. 预配 Azure 资源后，输出中将包含指向正在运行的 Web 应用程序的 URL。

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. 使用控制台中的 URL 在浏览器中导航到 Web 应用程序。 观察正在运行的应用的输出。

安装客户端库

客户端库可通过 Go 作为 azcosmos 包使用。

1. 打开终端并导航到 /src 文件夹。

   cd ./src
   

2. 使用 go install 安装 azcosmos 包（如果尚未安装）。

   go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
   

3. 另请安装 azidentity 包（如果尚未安装）。

   go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

4. 打开并检查 src/go.mod 文件以验证 github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos 和 github.com/Azure/azure-sdk-for-go/sdk/azidentity 条目是否都存在。

对象模型

名称	描述
CosmosClient	此类是主要客户端类，用于管理帐户范围的元数据或数据库。
CosmosDatabase	此类表示帐户内的数据库。
CosmosContainer	此类主要用于对容器或容器中存储的项执行读取、更新和删除操作。
PartitionKey	此类表示逻辑分区键。 许多常见操作和查询都需要此类。

代码示例

• 对客户端进行身份验证
• 获取数据库
• 获取容器
• 创建项
• 获取项
• 查询项

模板中的示例代码使用名为 cosmicworks 的数据库和名为 products 的容器。 products 容器包含每个产品的名称、类别、数量、唯一标识符和销售标志等详细信息。 该容器使用 /category 属性作为逻辑分区键。

验证客户端

此示例使用 azcosmos.NewClient 创建一个新的 CosmosClient 实例并使用 DefaultAzureCredential 实例进行身份验证。

credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return err
}

clientOptions := azcosmos.ClientOptions{
    EnableContentResponseOnWrite: true,
}

client, err := azcosmos.NewClient("<azure-cosmos-db-nosql-account-endpoint>", credential, &clientOptions)
if err != nil {
    return err
}

获取数据库

使用 client.NewDatabase 检索名为 cosmicworks 的现有数据库。

database, err := client.NewDatabase("cosmicworks")
if err != nil {
    return err
}

获取容器

使用 database.NewContainer 检索现有的 products 容器。

container, err := database.NewContainer("products")
if err != nil {
    return err
}

创建项

使用要序列化为 JSON 的所有成员构建一个 Go 类型。 在此示例中，该类型具有唯一标识符以及用于类别、名称、数量、价格和销售的字段。

type Item struct {
  Id        string  `json:"id"`
  Category  string  `json:"category"`
  Name      string  `json:"name"`
  Quantity  int     `json:"quantity"`
  Price     float32 `json:"price"`
  Clearance bool    `json:"clearance"`
}

使用 container.UpsertItem 在容器中创建某个项。 此方法会“更新插入”该项，有效地替换该项（如果该项已存在）。

item := Item {
    Id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    Category:  "gear-surf-surfboards",
    Name:      "Yamba Surfboard",
    Quantity:  12,
    Price:     850.00,
    Clearance: false,
}

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

bytes, err := json.Marshal(item)
if err != nil {
    return err
}

response, err := container.UpsertItem(context, partitionKey, bytes, nil)
if err != nil {
    return err
}

读取项

同时使用唯一标识符 (id) 和分区键字段来执行点读取操作。 使用 container.ReadItem 以有效检索特定项。

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

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

response, err := container.ReadItem(context, partitionKey, itemId, nil)
if err != nil {
    return err
}

if response.RawResponse.StatusCode == 200 {
    read_item := Item{}
    err := json.Unmarshal(response.Value, &read_item)
    if err != nil {
        return err
    }
}

查询项

使用 container.NewQueryItemsPager 对容器中的多个项执行查询。 使用此参数化查询查找指定类别中的所有项：

SELECT * FROM products p WHERE p.category = @category

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

query := "SELECT * FROM products p WHERE p.category = @category"

queryOptions := azcosmos.QueryOptions{
    QueryParameters: []azcosmos.QueryParameter{
        {Name: "@category", Value: "gear-surf-surfboards"},
    },
}

pager := container.NewQueryItemsPager(query, partitionKey, &queryOptions)

通过使用 pager.NextPage 循环访问每个结果页来分析查询的分页结果。 在每个循环的开头使用 pager.More 来确定是否还剩下任何结果。

items := []Item{}

for pager.More() {
    response, err := pager.NextPage(context.TODO())
    if err != nil {
        return err
    }

    for _, bytes := range response.Items {
        item := Item{}
        err := json.Unmarshal(bytes, &item)
        if err != nil {
            return err
        }
        items = append(items, item)
    }
}

清理资源

不再需要示例应用程序或资源时，请删除相应的部署和所有资源。

azd down

相关内容

• .NET 快速入门
• Node.js 快速入门
• Java 快速入门
• Python 快速入门