Quickstart: Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor Go

2025-07-21
Van toepassing op: ✅ Apache Cassanda

Ga aan de slag met de Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor Go voor het opslaan, beheren en opvragen van ongestructureerde gegevens. Volg de stappen in deze handleiding om een nieuw account te maken, een Go-clientbibliotheek te installeren, verbinding te maken met het account, algemene bewerkingen uit te voeren en uw uiteindelijke voorbeeldgegevens op te vragen.

API-referentiedocumentatie | Bibliotheekbroncode | pakket (Go)

Vereiste voorwaarden

Een Azure-abonnement
- Als je geen Azure-abonnement hebt, maak dan een gratis account aan voordat je begint.

De nieuwste versie van de Azure CLI in Azure Cloud Shell.
- Als u liever CLI-referentieopdrachten lokaal uitvoert, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

Go 1.24 of hoger

Installeren

Stel eerst de account- en ontwikkelomgeving voor deze handleiding in. In deze sectie wordt u begeleid bij het maken van een account, het verkrijgen van de referenties en het voorbereiden van uw ontwikkelomgeving.

Een account maken

Begin met het maken van een API voor een Apache Cassandra-account. Zodra het account is gemaakt, maakt u de keyspace- en tabelbronnen.

Azure-CLI
Azure-portal

Als u nog geen doelresourcegroep hebt, gebruikt u de az group create opdracht om een nieuwe resourcegroep in uw abonnement te maken.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Gebruik de az cosmosdb create opdracht om een nieuw Azure Cosmos DB voor Apache Cassandra-account te maken met standaardinstellingen.

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

Maak een nieuwe keyspace met az cosmosdb cassandra keyspace create en noem deze cosmicworks.

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

Maak een nieuw JSON-object om uw schema weer te geven met behulp van een Bash-opdracht met meerdere regels. Gebruik vervolgens de opdracht om een nieuwe tabel met de az cosmosdb cassandra table create naam productste maken.

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"

Meld u aan bij Azure Portal (https://portal.azure.com).
Voer Azure Cosmos DB in de algemene zoekbalk in.
Binnen Services, selecteer Azure Cosmos DB.
Selecteer Maken in het deelvenster Azure Cosmos DB, en selecteer vervolgens Azure Cosmos DB voor Apache Cassandra onder het tabblad Overige.
Kies RU-gegevensbankaccount aanvragen voor het accounttype.

Configureer in het deelvenster Basisbeginselen de volgende opties en selecteer vervolgens Beoordelen en maken:

	Waarde
Workloadtype	Leren
Abonnement	Selecteer uw Azure-abonnement
Resourcegroep	Een nieuwe resourcegroep maken of een bestaande resourcegroep selecteren
Accountnaam	Geef een wereldwijd unieke naam op
Beschikbaarheidszones	Uitschakelen
Plaats	Selecteer een ondersteunde Azure-regio voor uw abonnement

Aanbeveling

U kunt alle niet-opgegeven opties op de standaardwaarden laten staan. U kunt het account ook configureren om de totale doorvoer van accounts te beperken tot 1000 aanvraageenheden per seconde (RU/s) of om de gratis laag in te schakelen om uw kosten te minimaliseren.

Wacht in het deelvenster Controleren en maken tot de validatie van uw account is voltooid, en selecteer vervolgens Maken.
De portal gaat automatisch naar het deelvenster Implementatie . Wacht tot de implementatie is voltooid.
Zodra de implementatie is voltooid, selecteert u Ga naar de resource om naar de nieuwe API voor het Apache Cassandra-account te navigeren.
Selecteer in het resourcemenu de optie Data Explorer .
Selecteer + Nieuwe tabel in Data Explorer.

Configureer in het dialoogvenster Tabel toevoegen de volgende opties en selecteer VERVOLGENS OK:

	Waarde
Keyspace	Nieuwe maken
Keyspace-naam	`cosmicworks`
Tabelnaam	`product`
Tabelschema	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Aanbeveling

U kunt alle niet-opgegeven opties op de standaardwaarden laten staan.

Referenties ophalen

Haal nu het wachtwoord op dat de clientbibliotheek moet gebruiken om een verbinding te maken met het onlangs gemaakte account.

Azure-CLI
Azure-portal

Gebruik az cosmosdb show dit om het contactpunt en de gebruikersnaam voor het account op te halen.

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

Noteer de waarde van de contactPoint en username eigenschappen uit de uitvoer van de vorige opdrachten. De waarden van deze eigenschappen zijn het contactpunt en de gebruikersnaam die u verderop in deze handleiding gebruikt om verbinding te maken met het account met de bibliotheek.

Gebruik az cosmosdb keys list om de sleutels op te halen voor het account.

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

Noteer de waarde van de primaryMasterKey eigenschap uit de uitvoer van de vorige opdrachten. De waarde van deze eigenschap is het wachtwoord dat u verderop in deze handleiding gebruikt om verbinding te maken met het account met de bibliotheek.

Ontwikkelomgeving voorbereiden

Configureer vervolgens uw ontwikkelomgeving met een nieuw project en de clientbibliotheek. Deze stap is het laatste vereiste voordat u verdergaat met de rest van deze handleiding.

Begin in een lege map.
Maak een nieuwe Go-module.
```
go mod init quickstart
```
Importeer het github.com/apache/cassandra-gocql-driver/v2 pakket vanuit Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Maak het bestand main.go .
Voeg het sjabloon voor de Go-toepassing toe.
```
package main

func main() {    
}
```
Belangrijk

In de resterende stappen in deze handleiding wordt ervan uitgegaan dat u uw code toevoegt in de main functie.

Objectmodel

	Beschrijving
`Cluster`	Vertegenwoordigt een specifieke verbinding met een cluster
`Session`	Entiteiten die een specifieke verbinding met een cluster bevatten

Client verifiëren

Begin met het authentificeren van de client met behulp van de inloggegevens die eerder in deze handleiding zijn verzameld.

Open het bestand main.go in uw geïntegreerde ontwikkelomgeving (IDE).
Importeer in de main functie de volgende pakketten samen met het github.com/apache/cassandra-gocql-driver/v2 pakket:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Maak stringvariabelen voor de in deze handleiding eerder verzamelde inloggegevens. Geef de variabelen usernameeen naam en passwordcontactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Configureer een exemplaar van het PasswordAuthenticator type met de referenties die zijn opgegeven in de vorige stappen. Sla het resultaat op in een variabele met de naam authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Configureer een exemplaar van SslOptions met een minimale versie van Tls 1.2 (Transport Layer Security) en de contactPoint variabele als de naam van de doelserver. Sla het resultaat op in een variabele met de naam sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Maak een nieuwe clusterspecificatie met behulp van NewCluster en de contactPoint variabele.
```
cluster := gocql.NewCluster(contactPoint)
```
Configureer het clusterspecificatieobject met behulp van de referenties en configuratievariabelen die in de vorige stappen zijn gemaakt.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```

Configureer de rest van het clusterspecificatieobject met deze statische waarden.

cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4

Maak een nieuwe sessie die verbinding maakt met het cluster met behulp van CreateSession.
```
session, _ := cluster.CreateSession()
```
Configureer de sessie om de Close functie aan te roepen nadat de main functie is geretourneerd.
```
defer session.Close()
```
Maak een nieuw Background contextobject en sla het op in de ctx variabele.
```
ctx := context.Background()
```

Waarschuwing

Volledige TLS-validatie (Transport Layer Security) is uitgeschakeld in deze handleiding om verificatie te vereenvoudigen. Voor productie-implementaties schakelt u validatie volledig in.

Gegevens bijwerken of toevoegen

Vervolgens worden nieuwe gegevens in een tabel geplaatst. Upserting zorgt ervoor dat de gegevens op de juiste wijze worden gemaakt of vervangen, afhankelijk van of dezelfde gegevens al in de tabel aanwezig zijn.

Definieer een nieuw type met de naam Product met velden die overeenkomen met de tabel die u eerder in deze handleiding hebt gemaakt.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Aanbeveling

In Go kunt u dit type in een ander bestand maken of maken aan het einde van het bestaande bestand.

Maak een nieuw object van het type Product. Sla het object op in een variabele met de naam product.

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

Maak een nieuwe tekenreeksvariabele insertQuery met de CQL-query (Cassandra Query Language) voor het invoegen van een nieuwe rij.

insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`

Gebruik de Query en ExecContext functies om de query uit te voeren. Geef verschillende eigenschappen van de product variabele door als queryparameters.

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

Gegevens lezen

Lees vervolgens gegevens die eerder in de tabel zijn geplaatst.

Maak een nieuwe tekenreeksvariabele genaamd readQuery, met een CQL-query die overeenkomt met items met hetzelfde id-veld.

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

Maak een tekenreeksvariabele id met dezelfde waarde als het product dat eerder in deze handleiding is gemaakt.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Maak een andere variabele met de naam matchedProduct om het resultaat van deze bewerking op te slaan.
```
var matchedProduct Product
```

Gebruik de Queryfuncties , Consistencyen IterContextScan functies samen om het ene item te vinden dat overeenkomt met de query en de eigenschappen ervan toe te wijzen aan de matchedProduct variabele.

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

Gegevens opvragen

Gebruik ten slotte een query om alle gegevens te vinden die overeenkomen met een specifiek filter in de tabel.

Maak tekenreeksvariabelen met de naam findQuery en category met de CQL-query en de vereiste parameter.

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

category := "gear-surf-surfboards"

Gebruik de Queryfuncties en ConsistencyIterContextScanner functies samen om een scanner te maken die meerdere items kan herhalen die overeenkomen met de query.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Gebruik de functies Next en Scan om door de queryresultaten te doorlopen en de eigenschappen van elk resultaat toe te wijzen aan de queriedProduct variabele.

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

De code uitvoeren

Voer de zojuist gemaakte toepassing uit met behulp van een terminal in uw toepassingsmap.

go run .

De hulpbronnen opschonen