Início Rápido: Biblioteca de clientes do Azure Cosmos DB for Apache Cassandra para Go

Aplica-se a: ✅ Apache Cassanda

Comece a usar a biblioteca do cliente do Azure Cosmos DB para Apache Cassandra para Go, a fim de armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes Go, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

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

Pré-requisitos

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

A versão mais recente da CLI do Azure no Azure Cloud Shell.
- Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

Go 1.24 ou mais recente

Configurando

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Cassandra. Depois que a conta for criada, crie o keyspace e os recursos da tabela.

Azure CLI
Portal do Azure

Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Cassandra com configurações padrão.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Criar um novo keyspace com az cosmosdb cassandra keyspace create chamado cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Crie um novo objeto JSON para representar seu esquema usando um comando Bash de várias linhas. Em seguida, use o az cosmosdb cassandra table create comando para criar uma nova tabela chamada products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Entre no portal do Azure (https://portal.azure.com).
Insira o Azure Cosmos DB na barra de pesquisa global.
Em Serviços, selecione Azure Cosmos DB.
No painel do Azure Cosmos DB , selecione Criar e, em seguida, Azure Cosmos DB para Apache Cassandra na guia Outros .
Selecione a conta de banco de dados de unidade de solicitação (RU) como tipo de conta.

No painel Noções básicas, configure as seguintes opções e, em seguida, escolha Revisar + criar:

	Valor
Tipo de carga de trabalho	Aprendizagem
Subscrição	Selecione sua Assinatura do Azure.
Grupo de Recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
Nome da Conta	Forneça um nome global exclusivo
zonas de disponibilidade	Desabilitar
Localidade	Escolha uma região do Azure compatível com sua assinatura

Dica

Você pode deixar as opções não especificadas com os valores padrão. Você também pode configurar a conta para limitar a taxa de transferência total da conta a 1.000 unidades de solicitação por segundo (RU/s) ou habilitar a camada gratuita para minimizar seus custos.

No painel Revisar + criar , aguarde a conclusão bem-sucedida da validação da conta e escolha Criar.
O portal navega automaticamente para o painel Implantação. Aguarde até que a implantação seja concluída.
Depois que a implantação for concluída, selecione Ir para o recurso para navegar até a nova conta da API para Apache Cassandra.
No menu de recursos, selecione a opção Data Explorer .
No Data Explorer, selecione + Nova Tabela.

Na caixa de diálogo Adicionar Tabela , configure as seguintes opções e selecione OK:

	Valor
Keyspace	Criar novo
Nome do keyspace	`cosmicworks`
Nome da tabela	`product`
Esquema de tabela	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Dica

Você pode deixar as opções não especificadas com os valores padrão.

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Azure CLI
Portal do Azure

Use az cosmosdb show para obter o ponto de contato e o nome de usuário da conta.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Registre o valor das propriedades contactPoint e username da saída dos comandos anteriores. Os valores dessas propriedades são o ponto de contato e o nome de usuário que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Use az cosmosdb keys list para obter as chaves da conta.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Registre o valor da propriedade primaryMasterKey da saída dos comandos anteriores. O valor dessa propriedade é a senha que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Prepare o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca de clientes. Esta etapa é o último pré-requisito necessário antes de passar para o restante deste guia.

Inicie em um diretório vazio.
Crie um novo módulo Go.
```
go mod init quickstart
```
Importe o github.com/apache/cassandra-gocql-driver/v2 pacote do Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Crie o arquivo main.go .
Adicione a clichê do aplicativo Go.
```
package main

func main() {    
}
```
Importante

As etapas restantes neste guia pressupõem que você está adicionando seu código dentro da main função.

Modelo de objeto

	Descrição
`Cluster`	Representa uma conexão específica com um cluster
`Session`	Entidades que contêm uma conexão específica com um cluster

Autenticar cliente

Comece autenticando o cliente usando as credenciais coletadas anteriormente neste guia.

Abra o arquivo main.go em seu IDE (ambiente de desenvolvimento integrado).
Dentro da main função, importe os seguintes pacotes junto com o github.com/apache/cassandra-gocql-driver/v2 pacote:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Configure uma instância do PasswordAuthenticator tipo com as credenciais especificadas nas etapas anteriores. Armazene o resultado em uma variável chamada authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Configure uma instância de SslOptions com a versão mínima de Segurança da Camada de Transporte (TLS) 1.2 e use a variável contactPoint como o nome do servidor de destino. Armazene o resultado em uma variável chamada sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Crie uma nova especificação de cluster usando NewCluster e a contactPoint variável.
```
cluster := gocql.NewCluster(contactPoint)
```
Configure o objeto de especificação do cluster usando as variáveis de configuração e credencial criadas nas etapas anteriores.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
Configure o restante do objeto de especificação do cluster com esses valores estáticos.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
Crie uma nova sessão que se conecte ao cluster usando CreateSession.
```
session, _ := cluster.CreateSession()
```
Configure a sessão para invocar a Close função após o retorno da main função.
```
defer session.Close()
```
Crie um novo Background objeto de contexto e armazene-o na ctx variável.
```
ctx := context.Background()
```

Aviso

A validação completa da TLS (segurança da camada de transporte) está desabilitada neste guia para simplificar a autenticação. Para implantações de produção, habilite totalmente a validação.

Inserir ou atualizar dados

Em seguida, insira novos dados em uma tabela. O upserting garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

Defina um novo tipo nomeado Product com campos correspondentes à tabela criada anteriormente neste guia.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Dica

No Go, você pode criar esse tipo em outro arquivo ou criá-lo no final do arquivo existente.

Criar um novo objeto do tipo Product. Armazene o objeto em uma variável chamada product.

product := Product {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

Crie uma nova variável de cadeia de caracteres nomeada insertQuery com a consulta CQL (Cassandra Query Language) para inserir uma nova linha.
```
insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`
```

Use as funções Query e ExecContext para executar a consulta. Passe várias propriedades da product variável como parâmetros de consulta.

_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente na tabela.

Crie uma nova variável de cadeia de caracteres nomeada readQuery com uma consulta CQL que corresponda a itens com o mesmo id campo.

readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`

Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor que o produto criado anteriormente neste guia.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Crie outra variável nomeada matchedProduct para armazenar o resultado dessa operação.
```
var matchedProduct Product
```

Use as funções Query, Consistency, IterContext e Scan em conjunto para localizar o único item que corresponde à consulta e atribuir suas propriedades à variável matchedProduct.

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a um filtro específico na tabela.

Crie variáveis de cadeia de caracteres nomeadas findQuery e category com a consulta CQL e o parâmetro necessário.

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Use as funções Query, Consistency, IterContext e Scanner juntas para criar um scanner que possa iterar sobre vários itens que correspondam à consulta.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Use as funções Next e Scan para iterar sobre os resultados da consulta e atribuir as propriedades de cada resultado à variável interna queriedProduct.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

go run .

Limpar os recursos