Guia de início rápido: usar o Azure Cosmos DB for Table com o SDK do Azure para Go

2025-04-17
Aplica-se a: ✅ Table

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

Código fonte da biblioteca | Pacote (Go) | Azure Developer CLI

Pré-requisitos

Azure Developer CLI
Área de trabalho do Docker
Go 1.21 ou superior

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

Inicializar o projeto

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

Abra um terminal em um diretório vazio.
Se ainda não estiver autenticado, autentique-se na CLI do Desenvolvedor do Azure usando azd auth login. Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.
```
azd auth login
```

Use azd init para inicializar o projeto.

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

Durante a inicialização, configure um nome de ambiente exclusivo.
Implante a conta do Azure Cosmos DB usando azd up. Os templates Bicep também implantam uma aplicação web de amostra.
```
azd up
```
Durante o processo de provisionamento, selecione sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.

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.

Use o 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 cliente

A biblioteca do cliente está disponível através do Go, como o aztables pacote.

Abra um terminal e navegue até a /src pasta.
```
cd ./src
```
Se ainda não estiver instalado, instale o pacote usando aztablesgo install.
```
go install github.com/Azure/azure-sdk-for-go/sdk/data/aztables
```
Abra e revise o arquivo src/go.mod para validar que a github.com/Azure/azure-sdk-for-go/sdk/data/aztables entrada existe.

Importar bibliotecas

Importe os pacotes github.com/Azure/azure-sdk-for-go/sdk/azidentity e github.com/Azure/azure-sdk-for-go/sdk/data/aztables para o código da aplicação.

import (
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/data/aztables"
)

Modelo de objeto

Nome	Descrição
`ServiceClient`	Esse tipo é o tipo de cliente principal e é usado para gerenciar metadados ou bancos de dados em toda a conta.
`Client`	Este tipo representa o cliente de uma tabela numa conta.

O código de exemplo no modelo usa uma tabela chamada cosmicworks-products. A cosmicworks-products tabela contém detalhes como nome, categoria, quantidade, preço, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa um identificador exclusivo como a chave de linha e categoria como uma chave de partição.

Autenticar o cliente

Este exemplo cria uma nova instância do ServiceClient tipo.

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

client, err := aztables.NewServiceClient("<azure-cosmos-db-table-account-endpoint>", credential)
if err != nil {
    log.Fatal(err)
}

Obter uma mesa

Este exemplo cria uma instância do Client tipo usando a NewClient função do ServiceClient tipo.

table, err := client.NewClient("<azure-cosmos-db-table-name>")
if err != nil {
    log.Fatal(err)
}

Criar uma entidade

A maneira mais fácil de criar uma nova entidade em uma tabela é criar uma instância do tipo aztables.EDMEntity. Defina as RowKey propriedades e PartitionKey usando o aztables.Entity tipo e, em seguida, defina quaisquer propriedades extras usando um mapa de cadeia de caracteres.

entity := aztables.EDMEntity{
    Entity: aztables.Entity{
        RowKey:       "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        PartitionKey: "gear-surf-surfboards",
    },
    Properties: map[string]any{
        "Name":      "Yamba Surfboard",
        "Quantity":  12,
        "Price":     850.00,
        "Clearance": false,
    },
}

Conver a entidade em uma matriz de bytes usando json.Marshal e, em seguida, criar a entidade na tabela usando UpsertEntity.

bytes, err := json.Marshal(entity)
if err != nil {
    panic(err)
}

_, err = table.UpsertEntity(context.TODO(), bytes, nil)
if err != nil {
    panic(err)
}

Obter uma entidade

Você pode recuperar uma entidade específica de uma tabela usando GetEntityo . Em seguida, pode usar json.Unmarshal para fazer a análise com o tipo aztables.EDMEntity.

rowKey := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
partitionKey := "gear-surf-surfboards"

response, err := table.GetEntity(context.TODO(), partitionKey, rowKey, nil)
if err != nil {
    panic(err)
}

var entity aztables.EDMEntity
err = json.Unmarshal(response.Value, &entity)
if err != nil {
    panic(err)
}

Consulta de entidades

Depois de inserir uma entidade, você também pode executar uma consulta para obter todas as entidades que correspondem a um filtro específico usando NewListEntitiesPager junto com um filtro de cadeia de caracteres.

category := "gear-surf-surfboards"
// Ensure the value is OData-compliant by escaping single quotes
safeCategory := strings.ReplaceAll(category, "'", "''")
filter := fmt.Sprintf("PartitionKey eq '%s'", safeCategory)

options := &aztables.ListEntitiesOptions{
    Filter: &filter,
}

pager := table.NewListEntitiesPager(options)

Analise os resultados paginados da consulta usando a More função do pager para determinar se há mais páginas e, em seguida, a NextPage função para obter a próxima página de resultados.

for pager.More() {
    response, err := pager.NextPage(context.TODO())
    if err != nil {
        panic(err)
    }
    for _, entityBytes := range response.Entities {
        var entity aztables.EDMEntity
        err := json.Unmarshal(entityBytes, &entity)
        if err != nil {
            panic(err)
        }
        
        writeOutput(fmt.Sprintf("Found entity:\t%s\t%s", entity.Properties["Name"], entity.RowKey))
    }
}

Limpar recursos

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

azd down

Partilhar via