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

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.

Documentação | de referência da API 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.

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

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

   azd auth login
   

3. Use 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 upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.

   azd up
   

6. 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.

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

Instalar a biblioteca de cliente

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

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

   cd ./src
   

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

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

3. Além disso, instale o azidentity pacote se ainda não estiver instalado.

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

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

Modelo de objeto

Exemplos de código

• Autenticar o cliente
• Obter uma base de dados
• Obter um contentor
• Criar um item
• Obter um item
• Itens de consulta

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

Autenticar o cliente

Este exemplo cria uma nova instância de CosmosClient uso azcosmos.NewClient e autentica usando uma DefaultAzureCredential instância.

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 uma base 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 contentor

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

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 e 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.UpsertItemo . Este método "upserts" o item efetivamente substituindo o item se ele já existe.

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

Execute uma operação de leitura pontual usando os campos identificador exclusivo (id) e chave de partição. Use container.ReadItem para recuperar eficientemente 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

Execute uma consulta sobre vários itens em um contêiner usando container.NewQueryItemsPagero . Encontre todos os itens dentro 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 fazendo um loop em cada página de resultados usando pager.NextPage. Use pager.More para determinar se há algum resultado restante 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)
    }
}

Clean up resources (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

Conteúdos relacionados

• Guia de início rápido do .NET
• Guia de início rápido Node.js
• Início Rápido do Java
• Início Rápido do Python