Compartilhar via

Início Rápido: Como usar o Azure Cosmos DB for NoSQL com o SDK do Azure para linguagem Go

  • Artigo
  • Aplica-se a:
    ✅ NoSQL

Nesse início rápido, você implantará um aplicativo básico do Azure Cosmos DB for Table usando o SDK do Azure para linguagem Go. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que aplicativos armazenem dados de tabela estruturados na nuvem. Você aprenderá a criar tabelas, linhas e executar tarefas básicas em seu recurso do Azure Cosmos DB usando o SDK do Azure para linguagem Go.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (Go) | Azure Developer CLI

Pré-requisitos

  • CLI do Desenvolvedor do Azure
  • Docker Desktop
  • Go 1.21 ou mais recente

Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Inicializar o projeto

Use a Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêineres. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.

  1. Abra um terminal em um diretório vazio.

  2. Se você ainda não estiver autenticado, autentique-se na Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.

    azd auth login

  3. Execute azd init para inicializar o projeto.

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

  4. Durante a inicialização, configure um nome de ambiente exclusivo.

  5. Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.

    azd up

  6. Durante o processo de provisionamento, selecione a sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.

  7. Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

    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. Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Captura de tela do aplicativo Web em execução.

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do Go, como o pacote azcosmos.

  1. Abra um terminal e vá até a pasta /src.

    cd ./src

  2. Se o pacote azcosmos ainda não estiver instalado, instale-o usando go install.

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

  3. Instale também o pacote azidentity, caso ainda não esteja instalado.

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

  4. Abra e examine o arquivo src/go.mod para validar se as entradas github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos e github.com/Azure/azure-sdk-for-go/sdk/azidentity existem.

Modelo de objeto

Nome Descrição
CosmosClient Essa é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta.
CosmosDatabase Ela representa um banco de dados dentro da conta.
CosmosContainer A classe é usada principalmente para realizar operações de leitura, atualização e exclusão no contêiner ou nos itens armazenados no contêiner.
PartitionKey Ela representa uma chave de partição lógica. É necessária também para muitas operações e consultas comuns.

Exemplos de código

O código de exemplo do modelo usa um banco de dados chamado cosmicworks e um contêiner chamado products. O contêiner products traz detalhes como o nome, a categoria, a quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a propriedade /category como uma chave de partição lógica.

Autenticar o cliente

Esta amostra cria uma instância de CosmosClient usando azcosmos.NewClient e faz a autenticação com uma instância de 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
}

Obter um banco de dados

Use client.NewDatabase para recuperar o banco de dados existente chamado cosmicworks.

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

Obter um contêiner

Recupere o contêiner existente products usando database.NewContainer.

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

Criar um item

Crie um tipo Go com todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo, além de campos para categoria, nome, quantidade, preço e venda.

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"`
}

Crie um item no contêiner usando container.UpsertItem. Esse método executa upsert no item, substituindo o item efetivamente caso ele já exista.

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
}

Ler um item

Realize uma operação de leitura de ponto usando o identificador exclusivo (id) e os campos de chave de partição. Use container.ReadItem para recuperar com eficiência o item específico.

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
    }
}

Itens de consulta

Realize uma consulta em vários itens de um contêiner usando container.NewQueryItemsPager. Localize todos os itens de uma categoria especificada usando esta consulta parametrizada:

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)

Analise os resultados paginados da consulta executando um loop em cada página de resultados com pager.NextPage. Use pager.More para determinar se ainda há resultados no início de cada loop.

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)
    }
}

Limpar os recursos

Quando você não precisar mais dos recursos ou do aplicativo de exemplo, remova a implantação correspondente e todos os recursos.

azd down

Conteúdo relacionado