Schnellstart: Azure Cosmos DB für Apache Cassandra-Clientbibliothek für Go

Gilt für:: ✅ Apache Cassanda

Erste Schritte mit der Azure Cosmos DB für Apache Cassandra-Clientbibliothek für Go zum Speichern, Verwalten und Abfragen unstrukturierter Daten. Führen Sie die Schritte in diesem Handbuch aus, um ein neues Konto zu erstellen, eine Go-Clientbibliothek zu installieren, eine Verbindung mit dem Konto herzustellen, allgemeine Vorgänge auszuführen und Ihre endgültigen Beispieldaten abzufragen.

API-Referenzdokumentation | Bibliotheks-Quellcode | Paket (Go)

Voraussetzungen

Ein Azure-Abonnement
- Wenn Sie noch kein Azure-Abonnement haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

Die neueste Version der Azure CLI in Azure Cloud Shell.
- Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, melden Sie sich mit dem az login Befehl bei der Azure CLI an.

Go 1.24 oder höher

Einrichten

Richten Sie zunächst die Konto- und Entwicklungsumgebung für diesen Leitfaden ein. In diesem Abschnitt erfahren Sie, wie Sie ein Konto erstellen, die Anmeldeinformationen des Kontos abrufen und Ihre Entwicklungsumgebung vorbereiten.

Erstellen eines Kontos

Erstellen Sie zunächst eine API für Apache Cassandra-Konto. Nachdem das Konto erstellt wurde, erstellen Sie die Keyspace- und Tabellen-Ressourcen.

Azure CLI
Azure-Portal

Wenn Sie noch keine Zielressourcengruppe haben, verwenden Sie den az group create Befehl, um eine neue Ressourcengruppe in Ihrem Abonnement zu erstellen.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Verwenden Sie den az cosmosdb create Befehl, um ein neues Azure Cosmos DB für Apache Cassandra-Konto mit Standardeinstellungen zu erstellen.

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

Erstellen Sie einen neuen Keyspace mit az cosmosdb cassandra keyspace create namens cosmicworks.

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

Erstellen Sie ein neues JSON-Objekt, um Ihr Schema mithilfe eines mehrzeiligen Bash-Befehls darzustellen. Verwenden Sie dann den az cosmosdb cassandra table create Befehl, um eine neue Tabelle mit dem Namen productszu erstellen.

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"

Melden Sie sich beim Azure-Portal (https://portal.azure.com) an.
Geben Sie Azure Cosmos DB in die globale Suchleiste ein.
Wählen Sie in DienstenAzure Cosmos DB aus.
Wählen Sie im Bereich "Azure Cosmos DB " die Option "Erstellen" und dann "Azure Cosmos DB" für Apache Cassandra auf der Registerkarte "Andere " aus.
Wählen Sie das Anforderungseinheitsdatenbankkonto (RU) für den Kontotyp aus.

Konfigurieren Sie im Bereich Allgemeine Informationen die folgenden Optionen, und wählen Sie dann Bewertung + Create:

	Wert
Workloadtyp	Lernen
Abonnement	Wählen Sie Ihr Azure-Abonnement aus.
Ressourcengruppe	Erstellen Sie eine neue Ressourcengruppe, oder wählen Sie eine vorhandene Ressourcengruppe aus
Kontoname	Geben Sie einen global eindeutigen Namen an.
Verfügbarkeitszonen	Deaktivieren
Ort	Wählen Sie eine unterstützte Azure-Region für Ihre Subscription

Tipp

Sie können alle nicht spezifizierten Optionen auf ihren Standardwerten belassen. Sie können das Konto auch so konfigurieren, dass der Gesamtkontodurchsatz auf 1.000 Anforderungseinheiten pro Sekunde (RU/s) beschränkt oder die kostenlose Stufe aktiviert wird, um Ihre Kosten zu minimieren.

Warten Sie im Bereich Bewertung + Create, bis die Validierung Ihres Kontos erfolgreich abgeschlossen ist, und wählen Sie dann Create.
Das Portal navigiert automatisch zum Bereitstellungsbereich. Warten Sie, bis die Bereitstellung abgeschlossen ist.
Nachdem die Bereitstellung abgeschlossen ist, wählen Sie "Zur Ressource wechseln " aus, um zur neuen API für Apache Cassandra-Konto zu navigieren.
Wählen Sie im Ressourcenmenü die Option "Daten-Explorer " aus.
Wählen Sie im Daten-Explorer +Neue Tabelle aus.

Konfigurieren Sie im Dialogfeld "Tabelle hinzufügen " die folgenden Optionen, und wählen Sie dann "OK" aus:

	Wert
Keyspace	Neu erstellen
Schlüsselraumname	`cosmicworks`
Tabellenname	`product`
Tabellenschema	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Tipp

Sie können alle nicht spezifizierten Optionen auf ihren Standardwerten belassen.

Abrufen von Anmeldeinformationen

Rufen Sie nun das Kennwort für die Clientbibliothek ab, um eine Verbindung mit dem vor Kurzem erstellten Konto herzustellen.

Azure CLI
Azure-Portal

Verwenden Sie az cosmosdb show, um den Kontaktpunkt und den Benutzernamen für das Konto abzurufen.

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

Notieren Sie den Wert der contactPoint Und username Eigenschaften aus der Ausgabe der vorherigen Befehle. Die Werte dieser Eigenschaften sind der Kontaktpunkt und der Benutzername , den Sie später in diesem Handbuch verwenden, um eine Verbindung mit dem Konto mit der Bibliothek herzustellen.

Verwenden Sie az cosmosdb keys list, um die Schlüssel für das Konto zu erhalten.

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

Notieren Sie den Wert der Eigenschaft primaryMasterKey aus der Ausgabe des vorherigen Befehls. Der Wert dieser Eigenschaft ist das Kennwort , das Sie später in diesem Handbuch zum Herstellen einer Verbindung mit dem Konto mit der Bibliothek verwenden.

Vorbereiten der Entwicklungsumgebung

Konfigurieren Sie dann Ihre Entwicklungsumgebung mit einem neuen Projekt und der Clientbibliothek. Dieser Schritt ist die letzte erforderliche Voraussetzung, bevor Sie mit dem Rest dieses Handbuchs fortfahren.

Beginnen Sie in einem leeren Verzeichnis.
Erstellen Sie ein neues Go-Modul.
```
go mod init quickstart
```
Importieren Sie das github.com/apache/cassandra-gocql-driver/v2 Paket von Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Erstellen Sie die Datei "main.go ".
Fügen Sie die Go-Anwendungsbausteine hinzu.
```
package main

func main() {    
}
```
Von Bedeutung

Die verbleibenden Schritte in diesem Leitfaden gehen davon aus, dass Sie Ihren Code innerhalb der main Funktion hinzufügen.

Objektmodell

	BESCHREIBUNG
`Cluster`	Stellt eine bestimmte Verbindung zu einem Cluster dar.
`Session`	Entitäten, die eine bestimmte Verbindung zu einem Cluster enthalten

Authentifizieren des Clients

Beginnen Sie damit, den Client mithilfe der Anmeldeinformationen zu authentifizieren, die zuvor in diesem Handbuch gesammelt wurden.

Öffnen Sie die Datei "main.go " in Ihrer integrierten Entwicklungsumgebung (IDE).
Importieren Sie in der main Funktion die folgenden Pakete zusammen mit dem github.com/apache/cassandra-gocql-driver/v2 Paket:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Erstellen Sie String-Variablen für die zuvor in diesem Handbuch gesammelten Anmeldeinformationen. Benennen Sie die Variablen username, passwordund contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Konfigurieren Sie eine Instanz des PasswordAuthenticator Typs mit den in den vorherigen Schritten angegebenen Anmeldeinformationen. Speichern Sie das Ergebnis in einer Variable namens authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Konfigurieren Sie eine Instanz SslOptions mit einer Mindestversion von TLS (Transport Layer Security) 1.2 und der contactPoint Variablen als Zielservernamen. Speichern Sie das Ergebnis in einer Variable namens sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Erstellen Sie eine neue Clusterspezifikation mithilfe NewCluster und der contactPoint Variablen.
```
cluster := gocql.NewCluster(contactPoint)
```
Konfigurieren Sie das Clusterspezifikationsobjekt mithilfe der in den vorherigen Schritten erstellten Anmeldeinformationen und Konfigurationsvariablen.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
Konfigurieren Sie den Rest des Clusterspezifikationsobjekts mit diesen statischen Werten.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
Erstellen Sie eine neue Sitzung, die eine Verbindung mit dem Cluster herstellt.CreateSession
```
session, _ := cluster.CreateSession()
```
Konfigurieren Sie die Sitzung so, dass die Close-Funktion aufgerufen wird, nachdem die main-Funktion zurückkehrt.
```
defer session.Close()
```
Erstellen Sie ein neues Background Kontextobjekt, und speichern Sie es in der ctx Variablen.
```
ctx := context.Background()
```

Warnung

Die vollständige TLS-Überprüfung (Transport Layer Security) ist in diesem Handbuch deaktiviert, um die Authentifizierung zu vereinfachen. Aktivieren Sie die Validierung vollständig für Produktionsbereitstellungen.

Daten-Update durchführen

Als Nächstes fügen Sie neue Daten in eine Tabelle ein. Upserting stellt sicher, dass die Daten erstellt oder entsprechend ersetzt werden, je nachdem, ob die gleichen Daten bereits in der Tabelle vorhanden sind.

Definieren Sie einen neuen Typ namens Product mit Feldern, die der Tabelle entsprechen, die zuvor in diesem Leitfaden erstellt wurde.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Tipp

In Go können Sie diesen Typ in einer anderen Datei erstellen oder am Ende der vorhandenen Datei erstellen.

Erstellen Sie ein neues Objekt vom Typ Product. Speichern Sie das Objekt in einer Variablen mit dem Namen product.

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

Erstellen Sie eine neue Zeichenfolgenvariable insertQuery mit der Cassandra Query Language (CQL)-Abfrage zum Einfügen einer neuen Zeile.
```
insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`
```

Verwenden Sie die Funktionen Query und ExecContext, um die Abfrage auszuführen. Übergeben Sie verschiedene Eigenschaften der product Variablen als Abfrageparameter.

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

Daten lesen

Lesen Sie dann Daten, die zuvor in die Tabelle eingefügt wurden.

Erstellen Sie eine neue Zeichenfolgenvariable mit dem Namen readQuery, die eine CQL-Abfrage enthält, die Elemente mit demselben id Feld abgleicht.

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

Erstellen Sie eine Zeichenfolgenvariable id mit demselben Wert wie das zuvor in diesem Handbuch erstellte Produkt.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Erstellen Sie eine weitere Variable, die zum Speichern des Ergebnisses dieses Vorgangs benannt matchedProduct ist.
```
var matchedProduct Product
```

Verwenden Sie die Query, Consistency, IterContextund Scan Funktionen zusammen, um das einzelne Element zu finden, das der Abfrage entspricht, und weisen Sie der Variablen dessen matchedProduct Eigenschaften zu.

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

Abfragedaten

Verwenden Sie schließlich eine Abfrage, um alle Daten zu finden, die einem bestimmten Filter in der Tabelle entsprechen.

Erstellen Sie Zeichenfolgenvariablen namens findQuery und category mit der CQL-Abfrage und dem erforderlichen Parameter.

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

category := "gear-surf-surfboards"

Verwenden Sie die Query, Consistency, IterContext und Scanner Funktionen zusammen, um einen Scanner zu erstellen, der über mehrere Elemente iterieren kann, die der Abfrage entsprechen.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Verwenden Sie die Funktionen Next und Scan, um die Abfrageergebnisse zu durchlaufen und die Eigenschaften jedes Ergebnisses der inneren queriedProduct Variablen zuzuweisen.

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

Ausführen des Codes

Führen Sie die neu erstellte Anwendung mit einem Terminal in Ihrem Anwendungsverzeichnis aus.

go run .

Bereinigen von Ressourcen