快速入門：搭配 Azure SDK for Go 使用適用於 NoSQL 的 Azure Cosmos DB

在本快速入門中，您會使用 Azure SDK for Go 部署適用於資料表的基本 Azure Cosmos DB 應用程式。 Azure Cosmos DB for Table 是無架構的數據存放區，可讓應用程式將結構化數據表數據儲存在雲端中。 您將瞭解如何使用 Azure SDK for Go，在 Azure Cosmos DB 資源內建立數據表、數據列及執行基本工作。

API 參考文件 | 程式庫原始程式碼 | 套件 (Go) | Azure Developer CLI

必要條件

• Azure Developer CLI
• Docker Desktop
• Go 1.21 或更新

如果您沒有 Azure 帳戶，請在您開始之前先建立 免費帳戶。

初始化專案

使用 Azure 開發人員 CLI （azd） 建立適用於資料表帳戶的 Azure Cosmos DB，並部署容器化範例應用程式。 應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

1. 在空的目錄中開啟終端機。

2. 如果您尚未通過驗證，請使用 azd auth login向 Azure 開發人員 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. 在布建程式期間，選取您的訂用帳戶、所需的位置和目標資源群組。 等候佈建程序完成。 此流程「大約需要五分鐘」的時間。

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 項目都存在。

物件模型

程式碼範例

• 驗證用戶端
• 取得資料庫
• 取得容器
• 建立項目
• 取得項目
• 查詢項目

範本中的程式碼範例使用 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
}

建立項目

建置 Go 類型，而此類型具有所有您想要序列化成 JSON 的成員。 在此範例中，此類型具有唯一識別碼，以及類別、名稱、數量、價格和銷售的欄位。

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，以在容器中建立項目。 此方法會有效地 "upserts" 可取代項目 (如果已存在) 的項目。

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 快速入門