Schnellstart: Erstellen einer Go-App mit dem `gocql`-Client zum Verwalten von Azure Cosmos DB for Apache Cassandra-Daten

Artikel
03/22/2023

GILT FÜR: Cassandra

Azure Cosmos DB ist ein Multimodell-Datenbankdienst, mit dem Sie mithilfe der Funktionen für globale Verteilung und horizontale Skalierung schnell Dokument-, Tabellen-, Schlüssel-Wert- und Graph-Datenbanken erstellen und abfragen können. In diesem Schnellstart erstellen Sie zunächst ein Azure Cosmos DB for Apache Cassandra-Konto. Anschließend führen Sie eine Go-Anwendung aus, um einen Keyspace und eine Tabelle in Cassandra zu erstellen und einige Vorgänge auszuführen. Diese Go-App verwendet gocql. Dabei handelt es sich um einen Cassandra-Client für die Sprache Go handelt.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Erstellen Sie ein kostenloses Konto. Oder testen Sie Azure Cosmos DB kostenlos ohne ein Azure-Abonnement.
Go muss auf Ihrem Computer installiert sein, und Sie müssen über ausreichende praktische Kenntnisse über Go verfügen.
Git.

Erstellen eines Datenbankkontos

Vor dem Erstellen einer Datenbank müssen Sie mit Azure Cosmos DB ein Cassandra-Konto erstellen.

Wählen Sie im Menü des Azure-Portals oder auf der Startseite die Option Ressource erstellen aus.
Suchen Sie auf der Seite Neu nach Azure Cosmos DB, und wählen Sie die Option aus.
Wählen Sie auf der Seite Azure Cosmos DB die Option Erstellen aus.
Wählen Sie auf der API-Seite Erstellen im Cassandra-Bereich aus.

Die API bestimmt den Typ des zu erstellenden Kontos. Azure Cosmos DB stellt fünf APIs bereit: für NoSQL (für Dokumentdatenbanken), Gremlin (für Graphdatenbanken), MongoDB (für Dokumentdatenbanken), Azure Table und Cassandra. Sie müssen ein separates Konto für jede API erstellen.

Wählen Sie Cassandra aus, da Sie in diesem Schnellstart eine Tabelle erstellen, die mit der API für Cassandra verwendet werden kann.

Weitere Informationen zur API für Cassandra.

Geben Sie auf der Seite Azure Cosmos DB-Konto erstellen die grundlegenden Einstellungen für das neue Azure Cosmos DB-Konto ein.

Einstellung	Wert	BESCHREIBUNG
Subscription	Ihr Abonnement	Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos DB-Konto verwenden möchten.
Ressourcengruppe	Neu erstellen Geben Sie dann den gleichen Namen als Kontonamen ein.	Wählen Sie Neu erstellen. Geben Sie dann einen neuen Ressourcengruppenname für Ihr Konto ein. Verwenden Sie der Einfachheit halber den gleichen Namen als Azure Cosmos DB-Kontonamen.
Kontoname	Geben Sie einen eindeutigen Namen ein.	Geben Sie einen eindeutigen Namen ein, der Ihr Azure Cosmos DB-Konto identifiziert. Der Konto-URI lautet cassandra.cosmos.azure.com und wird an Ihren eindeutigen Kontonamen angehängt. Der Kontoname darf nur Kleinbuchstaben, Ziffern und Bindestriche (-) enthalten und muss zwischen 3 und 31 Zeichen lang sein.
Standort	Die Region, die Ihren Benutzern am nächsten liegt	Wählen Sie einen geografischen Standort aus, an dem Ihr Azure Cosmos DB-Konto gehostet werden soll. Verwenden Sie den Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können.
Kapazitätsmodus	Bereitgestellter Durchsatz oder serverlos	Wählen Sie Bereitgestellter Durchsatz aus, um ein Konto im Modus Bereitgestellter Durchsatz zu erstellen. Wählen Sie Serverlos aus, um ein Konto im Modus Serverlos zu erstellen.
Anwenden des Rabatts für den Free-Tarif von Azure Cosmos DB	Anwenden oder Nicht anwenden	Mit dem Azure Cosmos DB-Tarif „Free“ erhalten Sie die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos in einem Konto. Weitere Informationen zum Tarif „Free“
Beschränken des gesamten Kontodurchsatzes	Auswählen, um den Durchsatz des Kontos zu begrenzen	Dies ist nützlich, wenn Sie den Gesamtdurchsatz des Kontos auf einen bestimmten Wert beschränken möchten.

Hinweis

Sie können pro Azure-Abonnement maximal ein Azure Cosmos DB-Konto im Free-Tarif einrichten und müssen sich beim Erstellen des Kontos anmelden. Wird die Option zum Anwenden des tarifspezifischen Rabatts für den Free-Tarif nicht angezeigt, bedeutet dies, dass bereits ein anderes Konto im Abonnement mit dem Free-Tarif aktiviert wurde.

Die Seite zum Erstellen eines neuen Kontos für Azure Cosmos DB for Apache Cassandra

Konfigurieren Sie auf der Registerkarte Globale Verteilung die folgenden Details. Für diese Schnellstartanleitung können Sie die Standardwerte übernehmen:

Einstellung	Wert	Beschreibung
Georedundanz	Deaktivieren	Aktivieren oder deaktivieren Sie die globale Verteilung für Ihr Konto, indem Sie Ihre Region mit einer Region koppeln. Sie können später weitere Regionen zu Ihrem Konto hinzufügen.
Schreibvorgänge in mehreren Regionen	Deaktivieren	Mit der Funktion zum Schreiben in mehreren Regionen können Sie den bereitgestellten Durchsatz für Ihre Datenbanken und Container in der ganzen Welt nutzen.
Verfügbarkeitszonen	Deaktivieren	Verfügbarkeitszonen sind isolierte Standorte innerhalb einer Azure-Region. Jede Zone besteht aus mindestens einem Rechenzentrum, dessen Stromversorgung, Kühlung und Netzwerkbetrieb unabhängig funktionieren.

Hinweis

Die folgenden Optionen sind nicht verfügbar, wenn Sie als Kapazitätsmodus die Option Serverlos auswählen:

Tarifspezifischen Rabatt für den Free-Tarif anwenden
Georedundanz
Schreibvorgänge in mehreren Regionen

Optional können Sie auf den folgenden Registerkarten zusätzliche Details konfigurieren:
- Netzwerk: Konfigurieren Sie den Zugriff über ein virtuelles Netzwerk.
- Sicherungsrichtlinie: Konfigurieren Sie eine Richtlinie für regelmäßige oder fortlaufende Sicherungen.
- Verschlüsselung: Verwenden Sie entweder einen vom Dienst verwalteten Schlüssel oder einen kundenseitig verwalteten Schlüssel.
- Tags: Tags sind Name-Wert-Paare, mit denen Sie Ressourcen kategorisieren und eine konsolidierte Abrechnung anzeigen können, indem Sie dasselbe Tag auf mehrere Ressourcen und Ressourcengruppen anwenden.
Klicken Sie auf Überprüfen + erstellen.
Überprüfen Sie die Kontoeinstellungen, und wählen Sie anschließend Erstellen aus. Die Erstellung des Kontos dauert einige Minuten. Warten Sie, bis auf der Portalseite Ihre Bereitstellung wurde abgeschlossen. angezeigt wird.
Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.

Klonen der Beispielanwendung

Beginnen Sie mit dem Klonen der Anwendung über GitHub.

Öffnen Sie eine Eingabeaufforderung, und erstellen Sie einen Ordner namens git-samples.
```
md "C:\git-samples"
```
Öffnen Sie ein Git-Terminalfenster, z.B. git bash. Wechseln Sie mit dem Befehl cd in den neuen Ordner, und installieren Sie die Beispiel-App.
```
cd "C:\git-samples"
```
Führen Sie den folgenden Befehl aus, um das Beispielrepository zu klonen. Dieser Befehl erstellt eine Kopie der Beispiel-App auf Ihrem Computer.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Überprüfen des Codes

Dieser Schritt ist optional. Wenn Sie erfahren möchten, wie der Code die Datenbankressourcen erstellt, können Sie sich die folgenden Codeausschnitte ansehen. Andernfalls können Sie mit dem Abschnitt Ausführen der Anwendung fortfahren.

Die Funktion GetSession (Teil von utils\utils.go) gibt eine Sitzung vom Typ *gocql.Session zurück. Diese Sitzung wird zum Ausführen von Clustervorgängen wie Einfügen, Suchen usw. verwendet.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Der Azure Cosmos DB-Cassandra-Host wird an die Funktion gocql.NewCluster übergeben, um eine Struktur vom Typ *gocql.ClusterConfig abzurufen, die dann zur Verwendung des Benutzernamens, des Kennworts, des Ports und der entsprechenden TLS-Version (Sicherheitsanforderung in Bezug auf HTTPS-/SSL-/TLS-Verschlüsselung) konfiguriert wird.

Die Funktion GetSession wird dann über die main-Funktion (main.go) abgerufen.

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

Die Konnektivitätsinformationen und Anmeldeinformationen werden in Form von Umgebungsvariablen (aufgelöst in der init-Methode) akzeptiert.

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

Mithilfe davon werden anschließend verschiedene Vorgänge (Teil von operations\setup.go) in Azure Cosmos DB ausgeführt. Begonnen wird mit der Erstellung von keyspace und table.

Wie der Name bereits vermuten lässt, löscht die DropKeySpaceIfExists-Funktion das keyspace-Element nur, wenn es vorhanden ist.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

Mit der Funktion CreateKeySpace wird keyspace erstellt (user_profile).

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

Danach folgt die Tabellenerstellung (user), die von der Funktion CreateUserTable übernommen wird.

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

Nach der Erstellung des Keyspace und der Tabelle rufen Sie CRUD-Vorgänge auf (Teil von operations\crud.go).

InsertUser wird zum Erstellen eines User-Elements verwendet. Die Benutzerinformationen (ID, Name und Ort) werden mithilfe von Bind als Abfrageargumente festgelegt.

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser wird verwendet, um mithilfe einer bestimmten Benutzer-ID nach einem Benutzer (model\user.go) zu suchen und gleichzeitig die Benutzerattribute mithilfe von Scan (zurückgegeben von Cassandra) an einzelne Variablen (userid, name, city ) zu binden. Dies ist nur eine der Methoden, mit denen Sie das als Suchabfrageergebnis erhaltene Ergebnis verwenden können.

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers wird zum Abrufen aller Benutzer verwendet. SliceMap wird als Kurzform verwendet, um alle Benutzerinformationen in Form eines Slice von map-Elementen zu erhalten. Stellen Sie sich jedes map-Element als Schlüssel-Wert-Paare vor. Dabei ist der Spaltenname (z. B. user_id) der Schlüssel zusammen mit dem jeweiligen Wert.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Jedes map-Element mit Benutzerinformationen wird mithilfe der mapToUser-Funktion in ein User-Element konvertiert, das einfach den Wert aus der entsprechenden Spalte extrahiert und zum Erstellen einer Instanz der User-Struktur verwendet.

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

Ausführen der Anwendung

Wie bereits erwähnt, akzeptiert die Anwendung Konnektivität und Anmeldeinformationen in Form von Umgebungsvariablen.

Wählen Sie im Azure-Portal in Ihrem Azure Cosmos DB-Konto die Option Verbindungszeichenfolge aus.

Kopieren Sie die Werte für die folgenden Attribute (CONTACT POINT, PORT, USERNAME und PRIMARY PASSWORD), und legen Sie sie auf die jeweiligen Umgebungsvariablen fest:

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

Wechseln Sie im Terminalfenster zum richtigen Ordner. Beispiel:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

Führen Sie im Terminal den folgenden Befehl aus, um die Anwendung zu starten:

go run main.go

Im Terminalfenster werden Benachrichtigungen für die verschiedenen Vorgänge angezeigt, einschließlich Keyspace- und Tabelleneinrichtung, Benutzererstellung usw.
Öffnen Sie im Azure-Portal den Daten-Explorer, um diese neuen Daten abzufragen, zu ändern und zu verwenden.

Überprüfen von SLAs im Azure-Portal

Im Azure-Portal werden Durchsatz, Speicher, Verfügbarkeit, Wartezeit und Konsistenz Ihres Azure Cosmos DB-Kontos überwacht. Diagramme für Metriken einer Azure Cosmos DB-SLA (Service Level Agreement, Vereinbarung zum Servicelevel) zeigen den SLA-Wert im Vergleich zur tatsächlichen Leistung. Diese Sammlung von Metriken macht die Überwachung Ihrer SLAs transparent.

So überprüfen Sie Metriken und SLAs:

Wählen Sie im Navigationsmenü Ihres Azure Cosmos DB-Kontos die Option Metriken aus.
Wählen Sie eine Registerkarte (etwa Wartezeit) und auf der rechten Seite einen Zeitraum aus. Vergleichen Sie Zeilen Tatsächlich und SLA in den Diagrammen.
Überprüfen Sie die Metriken auf den anderen Registerkarten.

Bereinigen von Ressourcen

Wenn Sie Ihre App und das Azure Cosmos DB-Konto fertiggestellt haben, können Sie die erstellten Azure-Ressourcen löschen, damit keine weiteren Gebühren anfallen. So löschen Sie die Ressourcen:

Suchen Sie über die Suchleiste des Azure-Portals nach Ressourcengruppen, und wählen Sie die entsprechende Option aus.
Wählen Sie in der Liste die Ressourcengruppe aus, die Sie für diesen Schnellstart erstellt haben.
Wählen Sie auf der Seite Übersicht der Ressourcengruppe die Option Ressourcengruppe löschen aus.
Geben Sie in dem nächsten Fenster den Namen der zu löschenden Ressourcengruppe ein, und wählen Sie dann Löschen aus.

Nächste Schritte

In diesem Schnellstart haben Sie erfahren, wie Sie ein Azure Cosmos DB-Konto mit API für Cassandra erstellen und eine Go-App ausführen, die eine Cassandra-Datenbank und einen Cassandra-Container erstellt. Jetzt können Sie zusätzliche Daten in Ihr Azure Cosmos DB-Konto importieren.

Azure Cosmos DB: Import Cassandra data (Azure Cosmos DB: Importieren von Cassandra-Daten)

Schnellstart: Erstellen einer Go-App mit dem gocql-Client zum Verwalten von Azure Cosmos DB for Apache Cassandra-Daten