Schnellstart: Erstellen einer Apache Cassandra-App mit .NET-SDK und Azure Cosmos DB

  • Artikel

GILT FÜR: Cassandra

In diesem Schnellstart erfahren Sie, wie Sie mit .NET und der API für Cassandra von Azure Cosmos DB eine Profil-App erstellen, indem Sie ein Beispiel von GitHub klonen. Außerdem wird in dieser Schnellstartanleitung gezeigt, wie Sie das webbasierte Azure-Portal verwenden, um ein Azure Cosmos DB-Konto zu erstellen.

Azure Cosmos DB ist ein global verteilter Datenbankdienst von Microsoft mit mehreren Modellen. Sie können schnell Dokument-, Tabellen-, Schlüssel-Wert- und Graph-Datenbanken erstellen und abfragen und dabei stets die Vorteile der globalen Verteilung und der horizontalen Skalierung nutzen, die Azure Cosmos DB bietet.

Voraussetzungen

Sollten Sie über kein Azure-Abonnement verfügen, können Sie zunächst ein kostenloses Azure-Konto erstellen. Alternativ können Sie Azure Cosmos DB ohne Azure-Abonnement testen – kostenlos und ohne Verpflichtung.

Zudem benötigen Sie:

  • Aktuelle Visual Studio-Version mit der Workload „Azure-Entwicklung“. Sie können mit der kostenlosen IDE der Visual Studio-Community beginnen. Aktivieren Sie beim Setup von Visual Studio die Workload Azure-Entwicklung.
  • Installieren Sie Git, um das Beispiel zu klonen.

Erstellen eines Datenbankkontos

  1. Wählen Sie im Menü des Azure-Portals oder auf der Startseite die Option Ressource erstellen aus.

  2. Suchen Sie auf der Seite Neu nach Azure Cosmos DB, und wählen Sie die Option aus.

  3. Wählen Sie auf der Seite Azure Cosmos DB die Option Erstellen aus.

  4. Wählen Sie auf der Seite APIErstellen im Bereich Cassandra 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.

  5. 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 begrenzen wollen.

    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.

    The new account page for Azure Cosmos DB for Apache Cassandra

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

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

  8. Klicken Sie auf Überprüfen + erstellen.

  9. Ü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.

    The Azure portal Notifications pane

  10. Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.

Klonen der Beispielanwendung

Beginnen wir nun mit der Verwendung von Code. Wir klonen eine API für Cassandra-App aus GitHub, legen die Verbindungszeichenfolge fest und führen die App aus. Sie werden feststellen, dass Sie ganz einfach programmgesteuert mit Daten arbeiten können.

  1. Öffnen Sie eine Eingabeaufforderung. Erstellen Sie einen neuen Ordner namens git-samples. Schließen Sie dann die Eingabeaufforderung.

    md "C:\git-samples"

  2. Öffnen Sie ein Git-Terminalfenster (z.B. git bash), und verwenden Sie den Befehl cd, um in den neuen Ordner zu gelangen und dort die Beispiel-App zu installieren.

    cd "C:\git-samples"

  3. 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-dotnet-getting-started.git

  4. Öffnen Sie anschließend die Projektmappendatei „CassandraQuickStartSample“ in Visual Studio.

Ü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. Die Codeausschnitte stammen alle aus der Datei Program.cs, die im Ordner C:\git-samples\azure-cosmos-db-cassandra-dotnet-getting-started\CassandraQuickStartSample installiert wurde. Andernfalls können Sie mit Aktualisieren der Verbindungszeichenfolge fortfahren.

  • Initialisieren Sie die Sitzung, indem Sie eine Verbindung mit einem Cassandra-Clusterendpunkt herstellen. Die API für Cassandra für Azure Cosmos DB unterstützt nur TLSv1.2.

    var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
options.SetHostNameResolver((ipAddress) => CassandraContactPoint);
Cluster cluster = Cluster.Builder().WithCredentials(UserName, Password).WithPort(CassandraPort).AddContactPoint(CassandraContactPoint).WithSSL(options).Build();
ISession session = cluster.Connect();

  • Erstellen Sie einen neuen Keyspace.

    session.Execute("CREATE KEYSPACE uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 };");

  • Erstellen Sie eine neue Tabelle.

    session.Execute("CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)");

  • Fügen Sie Benutzerentitäten ein. Verwenden Sie hierzu das IMapper-Objekt mit einer neuen Sitzung, die eine Verbindung mit dem Keyspace „uprofile“ herstellt.

    mapper.Insert<User>(new User(1, "LyubovK", "Dubai"));

  • Fragen Sie alle Benutzerinformationen ab.

    foreach (User user in mapper.Fetch<User>("Select * from user"))
{
   Console.WriteLine(user);
}

  • Führen Sie eine Abfrage zum Abrufen der Informationen eines einzelnen Benutzers aus.

    mapper.FirstOrDefault<User>("Select * from user where user_id = ?", 3);

Aktualisieren der Verbindungszeichenfolge

Wechseln Sie nun zurück zum Azure-Portal, um die Informationen der Verbindungszeichenfolge abzurufen und in die App zu kopieren. Die Angabe der Verbindungszeichenfolgeninformationen ermöglicht Ihrer App die Kommunikation mit Ihrer gehosteten Datenbank.

  1. Wählen Sie im Azure-Portal die Option Verbindungszeichenfolge aus.

  2. Verwenden Sie die Schaltfläche auf der rechten Seite des Bildschirms, um den Benutzernamen zu kopieren.

    View and copy an access key in the Azure portal, Connection String page

  3. Öffnen Sie in Visual Studio die Datei „Program.cs“.

  4. Ersetzen Sie <FILLME> in Zeile 13 durch den Benutzernamen aus dem Portal.

    Zeile 13 von „Program.cs“ sollte nun in etwa wie folgt aussehen:

    private const string UserName = "cosmos-db-quickstart";

  5. Kehren Sie zum Portal zurück, und kopieren Sie den Wert für das Kennwort. Ersetzen Sie <FILLME> in Zeile 14 durch das Kennwort aus dem Portal.

    Zeile 14 von „Program.cs“ sollte nun in etwa wie folgt aussehen:

    private const string Password = "2Ggkr662ifxz2Mg...==";

  6. Kehren Sie zum Portal zurück, und kopieren Sie den Kontaktpunkt. Ersetzen Sie <FILLME> in Zeile 15 durch den Kontaktpunkt aus dem Portal.

    Zeile 15 von „Program.cs“ sollte nun in etwa wie folgt aussehen:

    private const string CassandraContactPoint = "cosmos-db-quickstarts.cassandra.cosmosdb.azure.com"; // DnsName

  7. Speichern Sie die Datei "Program.cs".

Ausführen der .NET-App

  1. Klicken Sie in Visual Studio auf Tools>NuGet-Paket-Manager>Paket-Manager-Konsole.

  2. Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das NuGet-Paket des .NET-Treibers zu installieren:

    Install-Package CassandraCSharpDriver

  3. Drücken Sie STRG+F5, um die Anwendung auszuführen. Ihre App wird im Konsolenfenster angezeigt.

    View and verify the output

    Drücken Sie STRG+C, um die Programmausführung zu beenden und das Konsolenfenster zu schließen.

  4. Öffnen Sie im Azure-Portal den Daten-Explorer, um diese neuen Daten abzufragen, zu ändern und zu verwenden.

    View the data in Data Explorer

Ü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:

  1. Wählen Sie im Navigationsmenü Ihres Azure Cosmos DB-Kontos die Option Metriken aus.

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

    Azure Cosmos DB metrics suite

  3. Ü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:

  1. Suchen Sie über die Suchleiste des Azure-Portals nach Ressourcengruppen, und wählen Sie die entsprechende Option aus.

  2. Wählen Sie in der Liste die Ressourcengruppe aus, die Sie für diesen Schnellstart erstellt haben.

    Select the resource group to delete

  3. Wählen Sie auf der Seite Übersicht der Ressourcengruppe die Option Ressourcengruppe löschen aus.

    Delete the resource group

  4. 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 gelernt, wie Sie ein Azure Cosmos DB-Konto erstellen, einen Container mit dem Daten-Explorer erstellen und eine Web-App ausführen. Jetzt können Sie andere Daten in Ihr Azure Cosmos DB-Konto importieren.

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