Schnellstart: Verbinden einer Go-Anwendung mit der Azure Cosmos DB für MongoDB

Artikel
03/29/2023

GILT FÜR: MongoDB

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 dieser Schnellstartanleitung erstellen und verwalten Sie ein Azure Cosmos DB-Konto mithilfe von Azure Cloud Shell, klonen eine vorhandene Beispielanwendung von GitHub und konfigurieren sie für das Arbeiten mit Azure Cosmos DB.

Bei der Beispielanwendung handelt es sich um ein befehlszeilenbasiertes todo-Verwaltungstool, das in Go geschrieben wurde. Die Azure Cosmos DB-API für MongoDB ist mit dem MongoDB Wire Protocol kompatibel, sodass alle MongoDB-Clienttreiber eine Verbindung damit herstellen können. Diese Anwendung verwendet den Go-Treiber für MongoDB so, dass es für die Anwendung transparent ist, dass die Daten in einer Azure Cosmos DB-Datenbank gespeichert sind.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Erstellen Sie ein kostenloses Konto. Oder testen Sie Azure Cosmos DB kostenlos ohne ein Azure-Abonnement. Sie können auch den Azure Cosmos DB-Emulator mit der Verbindungszeichenfolge .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true verwenden.
Go muss auf Ihrem Computer installiert sein, und Sie müssen über ausreichende praktische Kenntnisse über Go verfügen.
Git.

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Klonen der Beispielanwendung

Führen Sie die folgenden Befehle aus, um das Beispielrepository zu klonen.

Öffnen Sie eine Eingabeaufforderung, erstellen Sie einen neuen Ordner namens git-samples, und schließen Sie dann die Eingabeaufforderung.
```
mkdir "C:\git-samples"
```
Ö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"
```
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/cosmosdb-go-mongodb-quickstart
```

Überprüfen des Codes

Dieser Schritt ist optional. Wenn Sie erfahren möchten, wie die Anwendung funktioniert, können Sie sich die folgenden Codeausschnitte ansehen. Andernfalls können Sie mit dem Abschnitt Ausführen der Anwendung fortfahren. Das Anwendungslayout sieht wie folgt aus:

.
├── go.mod
├── go.sum
└── todo.go

Die folgenden Codeausschnitte stammen alle aus der Datei todo.go.

Herstellen einer Verbindung für die Go-App mit Azure Cosmos DB

clientOptions kapselt die Verbindungszeichenfolge für Azure Cosmos DB, die mithilfe einer Umgebungsvariable übergeben wird (Details finden Sie im nächsten Abschnitt). Die Verbindung wird mithilfe der Funktion mongo.NewClient initialisiert, an die die clientOptions-Instanz übergeben wird. Die PingFunktion wird aufgerufen, um die erfolgreiche Konnektivität zu bestätigen (dies ist eine Fail-Fast-Strategie).

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
    defer cancel()

    clientOptions := options.Client().ApplyURI(mongoDBConnectionString).SetDirect(true)
    
    c, err := mongo.Connect(ctx, clientOptions)
    if err != nil {
        log.Fatalf("unable to initialize connection %v", err)
    }

    err = c.Ping(ctx, nil)
    if err != nil {
        log.Fatalf("unable to connect %v", err)
    }

Hinweis

Die Verwendung der SetDirect(true)-Konfiguration ist wichtig. Ohne diese Konfiguration erhalten Sie den folgenden Verbindungsfehler: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Erstellen eines `todo`-Elements

Zum Erstellen eines todo-Elements rufen wir ein Handle für eine mongo.Collection ab und rufen die Funktion InsertOne auf.

func create(desc string) {
    c := connect()
    ctx := context.Background()
    defer c.Disconnect(ctx)

    todoCollection := c.Database(database).Collection(collection)
    r, err := todoCollection.InsertOne(ctx, Todo{Description: desc, Status: statusPending})
    if err != nil {
        log.Fatalf("failed to add todo %v", err)
    }

Wir übergeben eine Todo-Struktur mit der Beschreibung und dem Status (der anfangs auf pending festgelegt ist):

type Todo struct {
    ID          primitive.ObjectID `bson:"_id,omitempty"`
    Description string             `bson:"description"`
    Status      string             `bson:"status"`
}

Auflisten von `todo`-Elementen

Wir können TODO-Elemente basierend auf Kriterien auflisten. Ein bson.D wird erstellt, um die Filterkriterien zu kapseln:

func list(status string) {
    .....
    var filter interface{}
    switch status {
    case listAllCriteria:
        filter = bson.D{}
    case statusCompleted:
        filter = bson.D{{statusAttribute, statusCompleted}}
    case statusPending:
        filter = bson.D{{statusAttribute, statusPending}}
    default:
        log.Fatal("invalid criteria for listing todo(s)")
    }

Find wird verwendet, um basierend auf dem Filter nach Dokumenten zu suchen, und das Ergebnis wird in einen Slice von Todo konvertiert.

    todoCollection := c.Database(database).Collection(collection)
    rs, err := todoCollection.Find(ctx, filter)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }
    var todos []Todo
    err = rs.All(ctx, &todos)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }

Abschließend werden die Informationen im Tabellenformat gerendert:

    todoTable := [][]string{}

    for _, todo := range todos {
        s, _ := todo.ID.MarshalJSON()
        todoTable = append(todoTable, []string{string(s), todo.Description, todo.Status})
    }

    table := tablewriter.NewWriter(os.Stdout)
    table.SetHeader([]string{"ID", "Description", "Status"})

    for _, v := range todoTable {
        table.Append(v)
    }
    table.Render()

Aktualisieren eines `todo`-Elements

Ein todo-Element kann basierend auf der zugehörigen _id aktualisiert werden. Ein bson.D-Filter wird basierend auf der _id erstellt, und für die aktualisierten Informationen wird ein weiterer Filter erstellt, in diesem Fall ein neuer Status (completed oder pending). Abschließend wird die Funktion UpdateOne mit dem Filter und dem aktualisierten Dokument aufgerufen:

func update(todoid, newStatus string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }
    filter := bson.D{{"_id", oid}}
    update := bson.D{{"$set", bson.D{{statusAttribute, newStatus}}}}
    _, err = todoCollection.UpdateOne(ctx, filter, update)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }

Löschen eines `todo`-Elements

Ein todo-Element wird basierend auf der zugehörigen _id gelöscht und in Form einer bson.D-Instanz gekapselt. DeleteOne wird zum Löschen des Dokuments aufgerufen.

func delete(todoid string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("invalid todo ID %v", err)
    }
    filter := bson.D{{"_id", oid}}
    _, err = todoCollection.DeleteOne(ctx, filter)
    if err != nil {
        log.Fatalf("failed to delete todo %v", err)
    }
}

Erstellen der Anwendung

Wechseln Sie in das Verzeichnis, in dem Sie die Anwendung geklont haben, und erstellen Sie die Anwendung (mit go build).

cd monogdb-go-quickstart
go build -o todo

Damit bestätigen Sie, dass die Anwendung ordnungsgemäß erstellt wurde.

./todo --help

Einrichten von Azure Cosmos DB

Wenn Sie die Azure CLI lokal installieren und verwenden möchten, ist es für dieses Thema erforderlich, mindestens Version 2.0 auszuführen. Führen Sie az --version aus, um die Version zu ermitteln. Wenn Sie die CLI installieren oder aktualisieren müssen, finden Sie die entsprechende Anleitung unter [Installieren der Azure CLI].

Wenn Sie eine installierte Azure CLI verwenden, melden Sie sich mit dem Befehl az login bei Ihrem Azure-Abonnement an, und befolgen Sie die Anweisungen auf dem Bildschirm. Sie können diesen Schritt überspringen, wenn Sie Azure Cloud Shell verwenden.

az login

Hinzufügen des Azure Cosmos DB-Moduls

Wenn Sie eine installierte Azure CLI verwenden, überprüfen Sie, ob die cosmosdb-Komponente bereits installiert ist, indem Sie den az-Befehl ausführen. Wenn cosmosdb in der Liste der Basisbefehle enthalten ist, fahren Sie mit dem nächsten Befehl fort. Sie können diesen Schritt überspringen, wenn Sie Azure Cloud Shell verwenden.

Wenn cosmosdb nicht in der Liste der Basisbefehle enthalten ist, installieren Sie die Azure-Befehlszeilenschnittstelle erneut.

Erstellen einer Ressourcengruppe

Erstellen Sie mit dem Befehl az group create eine Ressourcengruppe. Eine Azure-Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen wie Web-Apps, Datenbanken und Speicherkonten bereitgestellt und verwaltet werden.

Im folgenden Beispiel wird eine Ressourcengruppe in der Region „Europa, Westen“ erstellt. Wählen Sie einen eindeutigen Namen für die Ressourcengruppe aus.

Wenn Sie Azure Cloud Shell verwenden, wählen Sie Ausprobieren aus, befolgen Sie die Anweisungen auf dem Bildschirm für die Anmeldung, und kopieren Sie dann den Befehl in die Eingabeaufforderung.

az group create --name myResourceGroup --location "West Europe"

Erstellen eines Azure Cosmos DB-Kontos

Erstellen Sie mit dem Befehl az cosmosdb create ein Azure Cosmos DB-Konto.

Ersetzen Sie im folgenden Befehl den Platzhalter <cosmosdb-name> durch Ihren eigenen eindeutigen Azure Cosmos DB-Kontonamen. Da dieser eindeutige Name als Teil des Azure Cosmos DB-Endpunkts (https://<cosmosdb-name>.documents.azure.com/) verwendet wird, muss er für alle Azure Cosmos DB-Konten in Azure eindeutig sein.

az cosmosdb create --name <cosmosdb-name> --resource-group myResourceGroup --kind MongoDB

Der --kind MongoDB-Parameter ermöglicht MongoDB-Clientverbindungen.

Nach dem Erstellen des Azure Cosmos DB-Kontos zeigt die Azure-CLI ähnliche Informationen wie im folgenden Beispiel an.

Hinweis

In diesem Beispiel wird JSON als Azure CLI-Ausgabeformat (Standardeinstellung) verwendet. Informationen zur Verwendung anderer Ausgabeformate finden Sie unter Ausgabeformate für Azure CLI-Befehle.

{
  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>.documents.azure.com:443/",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Document
DB/databaseAccounts/<cosmosdb-name>",
  "kind": "MongoDB",
  "location": "West Europe",
  "name": "<cosmosdb-name>",
  "readLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ],
  "resourceGroup": "myResourceGroup",
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "writeLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ]
}

Abrufen des Datenbankschlüssels

Um eine Verbindung mit der Azure Cosmos DB-Datenbank herstellen zu können, benötigen Sie den Datenbankschlüssel. Rufen Sie den Primärschlüssel mit dem Befehl az cosmosdb keys list ab.

az cosmosdb keys list --name <cosmosdb-name> --resource-group myResourceGroup --query "primaryMasterKey"

Die Azure-CLI gibt Informationen ähnlich wie im folgenden Beispiel aus.

"RUayjYjixJDWG5xTqIiXjC..."

Konfigurieren der Anwendung

Exportieren Sie die Verbindungszeichenfolge, die MongoDB-Datenbank und die Sammlungsnamen als Umgebungsvariablen.

export MONGODB_CONNECTION_STRING="mongodb://<COSMOSDB_ACCOUNT_NAME>:<COSMOSDB_PASSWORD>@<COSMOSDB_ACCOUNT_NAME>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@<COSMOSDB_ACCOUNT_NAME>@"

Hinweis

Die Option ssl=true ist wichtig, um die Voraussetzungen von Azure Cosmos DB zu erfüllen. Weitere Informationen finden Sie unter Anforderungen an die Verbindungszeichenfolge.

Ersetzen Sie bei der Umgebungsvariable MONGODB_CONNECTION_STRING die Platzhalter <COSMOSDB_ACCOUNT_NAME> und <COSMOSDB_PASSWORD>.

<COSMOSDB_ACCOUNT_NAME>: Der Name des von Ihnen erstellten Azure Cosmos DB-Kontos
<COSMOSDB_PASSWORD>: Der im vorherigen Schritt extrahierte Datenbankschlüssel

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Sie können für MONGODB_DATABASE und MONGODB_COLLECTION Ihre bevorzugten Werte auswählen oder die Standardwerte unverändert übernehmen.

Ausführen der Anwendung

So erstellen Sie ein todo

./todo --create "Create an Azure Cosmos DB database account"

Wenn der Vorgang erfolgreich war, wird eine Ausgabe mit der MongoDB-_id des neu erstellten Dokuments angezeigt:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Erstellen eines weiteren todo-Elements

./todo --create "Get the MongoDB connection string using the Azure CLI"

Auflisten aller todo-Elemente

./todo --list all

Es sollten die eben von Ihnen hinzugefügten Elemente im Tabellenformat angezeigt werden:

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | pending   |
|                            | database account               |           |
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

Wenn Sie den Status eines todo-Elements aktualisieren (z. B. den Status in completed ändern) möchten, verwenden Sie die todo-ID:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Auflisten der abgeschlossenen todo-Elemente

./todo --list completed

Es sollte nur das eben von Ihnen aktualisierte Element angezeigt werden:

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | completed |
|                            | database account               |           |
+----------------------------+--------------------------------+-----------+

Anzeigen von Daten im Daten-Explorer

Die in Azure Cosmos DB gespeicherten Daten können im Azure-Portal angezeigt und abgefragt werden.

Melden Sie sich im Azure-Portal in Ihrem Webbrowser an, um die im vorherigen Schritt erstellten Benutzerdaten anzuzeigen, abzufragen und mit ihnen zu arbeiten.

Geben Sie im Suchfeld oben Azure Cosmos DB ein. Wenn sich das Blatt Ihres Azure Cosmos DB-Kontos öffnet, wählen Sie Ihr Azure Cosmos DB-Konto aus. Wählen Sie im linken Navigationsbereich Daten-Explorer aus. Erweitern Sie Ihre Sammlung im Bereich „Sammlungen“. Anschließend können Sie die Dokumente in der Sammlung anzeigen, die Daten abfragen und sogar gespeicherte Prozeduren, Trigger und UDFs erstellen und ausführen.

Daten-Explorer mit dem neu erstellten Dokument

Löschen eines todo-Elements anhand der ID:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Auflisten aller todo-Elemente zur Bestätigung:

./todo --list all

Das Element vom Typ todo, das Sie eben gelöscht haben, sollte nicht vorhanden sein:

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

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 dieser Schnellstartanleitung haben Sie erfahren, wie Sie mit Azure Cloud Shell ein Azure Cosmos DB for MongoDB-Konto erstellen sowie eine Go-Befehlszeilen-App erstellen und ausführen, um todo-Elemente zu verwalten. Jetzt können Sie zusätzliche Daten in Ihr Azure Cosmos DB-Konto importieren.

Versuchen Sie, die Kapazitätsplanung für eine Migration zu Azure Cosmos DB durchzuführen? Sie können Informationen zu Ihrem vorhandenen Datenbankcluster für die Kapazitätsplanung verwenden.

Wenn Sie nur die Anzahl der virtuellen Kerne und Server in Ihrem vorhandenen Datenbankcluster kennen, lesen Sie die Informationen zum Schätzen von Anforderungseinheiten mithilfe von virtuellen Kernen oder virtuellen CPUs
Wenn Sie die typischen Anforderungsraten für Ihre aktuelle Datenbankworkload kennen, lesen Sie die Informationen zum Schätzen von Anforderungseinheiten mit dem Azure Cosmos DB-Kapazitätsplaner

Import MongoDB data into Azure Cosmos DB (Importieren von Daten aus MongoDB in Azure Cosmos DB)

Schnellstart: Verbinden einer Go-Anwendung mit der Azure Cosmos DB für MongoDB

Voraussetzungen

Klonen der Beispielanwendung

Überprüfen des Codes

Herstellen einer Verbindung für die Go-App mit Azure Cosmos DB

Erstellen eines todo-Elements

Auflisten von todo-Elementen

Aktualisieren eines todo-Elements

Löschen eines todo-Elements

Erstellen der Anwendung

Einrichten von Azure Cosmos DB

Anmelden bei Azure

Hinzufügen des Azure Cosmos DB-Moduls

Erstellen einer Ressourcengruppe

Erstellen eines Azure Cosmos DB-Kontos

Abrufen des Datenbankschlüssels

Konfigurieren der Anwendung

Exportieren Sie die Verbindungszeichenfolge, die MongoDB-Datenbank und die Sammlungsnamen als Umgebungsvariablen.

Ausführen der Anwendung

Anzeigen von Daten im Daten-Explorer

Bereinigen von Ressourcen

Nächste Schritte

Zusätzliche Ressourcen

Erstellen eines `todo`-Elements

Auflisten von `todo`-Elementen

Aktualisieren eines `todo`-Elements

Löschen eines `todo`-Elements