Quickstart: een Go-toepassing Verbinding maken naar Azure Cosmos DB voor MongoDB

Artikel
04/19/2024

VAN TOEPASSING OP: MongoDB

Met Azure Cosmos DB, een databaseservice met meerdere modellen, kunt u snel databases met documenten, tabellen, sleutelwaarden en grafieken maken en hier query's op uitvoeren. Deze databases hebben wereldwijde distributie en horizontale schaalmogelijkheden. In deze quickstart gaat u een Azure Cosmos DB-account maken en beheren met behulp van Azure Cloud Shell, een bestaande voorbeeldtoepassing klonen vanuit GitHub en deze configureren voor gebruik met Azure Cosmos DB.

De voorbeeldtoepassing is een op opdrachtregels gebaseerd todo-beheerprogramma dat is geschreven in Go. De API van Azure Cosmos DB voor MongoDB is compatibel met het wire-protocol van MongoDB, waardoor elk MongoDB-clientstuurprogramma er verbinding mee kan maken. Deze toepassing maakt op transparante wijze gebruik van het Go-stuurprogramma voor MongoDB om de gegevens in een Azure Cosmos DB-database op te slaan.

Vereisten

Een Azure-account met een actief abonnement. Maak gratis een account. Of probeer Azure Cosmos DB gratis zonder Azure-abonnement. U kunt ook de Azure Cosmos DB Emulator gebruiken met de verbindingsreeks .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Go moet zijn geïnstalleerd op uw computer en u moet praktische kennis van Go hebben.
Git.

Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
- Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
- Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
- Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

De voorbeeldtoepassing klonen

Voer de volgende opdrachten uit om de voorbeeldopslagplaats te klonen.

Open een opdrachtprompt, maak een nieuwe map met de naam git-samples en sluit vervolgens de opdrachtprompt.
```
mkdir "C:\git-samples"
```
Open een git-terminalvenster, bijvoorbeeld git bash, en gebruik de cd-opdracht om naar de nieuwe map te gaan voor het installeren van de voorbeeld-app.
```
cd "C:\git-samples"
```
Voer de volgende opdracht uit om de voorbeeldopslagplaats te klonen. Deze opdracht maakt een kopie van de voorbeeld-app op uw computer.
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

De code bekijken

Deze stap is optioneel. Als u wilt weten hoe de toepassing werkt, kunt u de volgende codefragmenten bekijken. Anders slaat u dit over en gaat u naar De toepassing uitvoeren. De indeling van de toepassing is als volgt:

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

De volgende codefragmenten zijn allemaal afkomstig uit het bestand todo.go.

De Go-app verbinden met Azure Cosmos DB

clientOptions bevat de verbindingsreeks voor Azure Cosmos DB, die wordt doorgegeven via een omgevingsvariabele (details staan in de komende sectie). De verbinding wordt geïnitialiseerd met behulp van mongo.NewClient, waaraan het clientOptions-exemplaar is doorgegeven. Ping de functie wordt aangeroepen om een geslaagde verbinding te bevestigen (dit is een 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)
    }

Notitie

Het gebruik van de SetDirect(true)-configuratie is belangrijk. Zonder de configuratie krijgt u de volgende verbindingsfout: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Een `todo`-item maken

Als u een todo wilt maken, moet u een koppeling naar een mongo.Collection maken en de InsertOne-functie aanroepen.

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)
    }

We geven een Todo struct door die de beschrijving en de status bevat (die in eerste instantie is ingesteld op pending):

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

`todo`-items weergeven

U kunt TODO's weergeven op basis van criteria. Er wordt een bson.D gemaakt om de filtercriteria in te kapselen:

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 wordt gebruikt om te zoeken naar documenten op basis van het filter, en het resultaat wordt geconverteerd naar een segment van Todo

    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)
    }

Ten slotte wordt de informatie weergegeven in tabelvorm:

    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()

Een `todo`-item bijwerken

Een todo kan worden bijgewerkt op basis van de bijbehorende _id. Er wordt een bson.D-filter gemaakt op basis van de _id en er wordt nog een gemaakt voor de bijgewerkte informatie. Dit is in dit geval een nieuwe status (completed of pending). Ten slotte wordt de UpdateOne functie aangeroepen met het filter en het bijgewerkte document:

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)
    }

Een `todo` verwijderen

Een todo wordt verwijderd op _id basis van de bijbehorende en wordt ingekapseld in de vorm van een bson.D exemplaar. DeleteOne wordt aangeroepen om het document te verwijderen.

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)
    }
}

De toepassing bouwen

Ga naar de map waarnaar u de toepassing hebt gekloond en bouw deze (met behulp van go build).

cd monogdb-go-quickstart
go build -o todo

Om te controleren of de toepassing correct is gemaakt.

./todo --help

Azure Cosmos DB instellen

Als u ervoor kiest om de CLI lokaal te installeren en te gebruiken, moet u voor dit onderwerp Versie 2.0 of hoger van Azure CLI uitvoeren. Voer az --version uit om de versie te bekijken. Als u Azure CLI 2.0 wilt installeren of upgraden, raadpleegt u [Azure CLI installeren].

Als u een geïnstalleerde Azure CLI gebruikt, meldt u zich aan bij uw Azure-abonnement met de opdracht az login en volgt u de instructies op het scherm. U kunt deze stap overslaan als u de Azure Cloud Shell gebruikt.

az login

De Azure Cosmos DB-module toevoegen

Als u een geïnstalleerde Azure CLI gebruikt, controleert u of het cosmosdb onderdeel al is geïnstalleerd door de az opdracht uit te voeren. Als cosmosdb in de lijst met basisopdrachten staat, gaat u verder met de volgende opdracht. U kunt deze stap overslaan als u de Azure Cloud Shell gebruikt.

Als cosmosdb deze zich niet in de lijst met basisopdrachten bevindt, installeert u Azure CLI opnieuw.

Een brongroep maken

Maak een resourcegroep met de opdracht az group create. Een Azure-resourcegroep is een logische container waarin Azure-resources zoals web-apps, databases en opslagaccounts worden geïmplementeerd en beheerd.

In het volgende voorbeeld wordt een resourcegroep gemaakt in de regio Europa - west. Kies een unieke naam voor de resourcegroep.

Als u Azure Cloud Shell gebruikt, selecteert u Proberen, volgt u de aanwijzingen op het scherm om u aan te melden en kopieert u de opdracht vervolgens naar de opdrachtprompt.

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

Een Azure Cosmos DB-account maken

Maak een Azure Cosmos DB-account met de opdracht az cosmosdb create.

Vervang in de volgende opdracht waar u de plaatsaanduiding <cosmosdb-name> ziet staan, de accountnaam met uw unieke Azure Cosmos DB-accountnaam. Deze unieke naam wordt gebruikt als onderdeel van uw Azure Cosmos DB-eindpunt (https://<cosmosdb-name>.documents.azure.com/), dus de naam moet uniek zijn binnen alle Azure Cosmos DB-accounts in Azure.

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

De parameter --kind MongoDB maakt MongoDB-clientverbindingen mogelijk.

Wanneer de Azure Cosmos DB-account wordt gemaakt toont de Azure CLI informatie die lijkt op het volgende voorbeeld.

Notitie

In dit voorbeeld wordt JSON gebruikt als de Azure CLI-uitvoerindeling. Dit is standaardindeling. Zie Output formats for Azure CLI commands (Uitvoerindelingen voor Azure CLI-opdrachten) als u een andere uitvoerindeling wilt gebruiken.

{
  "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"
    }
  ]
}

De databasesleutel ophalen

U hebt de databasesleutel nodig om verbinding te kunnen maken met een Azure Cosmos DB-database. Gebruik de opdracht az cosmosdb keys list om de primaire sleutel op te halen.

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

De Azure CLI voert informatie uit die lijkt op het volgende voorbeeld.

"RUayjYjixJDWG5xTqIiXjC..."

De toepassing configureren

Exporteer de namen van de verbindingsreeks, mongoDB-database en verzameling als omgevingsvariabelen.

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>@"

Notitie

De ssl=true optie is belangrijk vanwege azure Cosmos DB-vereisten. Zie Connection string requirements (Vereisten voor verbindingsreeksen) voor meer informatie.

Voor de omgevingsvariabele MONGODB_CONNECTION_STRING vervangt u de tijdelijke aanduidingen door <COSMOSDB_ACCOUNT_NAME> en <COSMOSDB_PASSWORD>

<COSMOSDB_ACCOUNT_NAME>: De naam van het Azure Cosmos DB-account dat u hebt gemaakt
<COSMOSDB_PASSWORD>: De databasesleutel die in de vorige stap is geëxtraheerd

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

U kunt uw voorkeurswaarden voor MONGODB_DATABASE en MONGODB_COLLECTION kiezen of deze laten staan.

De toepassing uitvoeren

Een todo maken

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

Als dit lukt, ziet u een uitvoer met de MongoDB-_id van het nieuwe document:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Maak nog een todo

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

Geef alle todo's weer

./todo --list all

Als het goed is, ziet u de items die u zojuist hebt toegevoegd in een tabelvorm:

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

Gebruik todo de id om de status van een todo (bijvoorbeeld wijzigen in status) bij te completed werken:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Geef alleen de voltooide todo's weer

./todo --list completed

Als het goed is, ziet u het bericht dat u zojuist hebt bijgewerkt:

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

Gegevens bekijken in Data Explorer

Gegevens die zijn opgeslagen in een Azure Cosmos DB-database kunnen via de Azure-portal worden bekeken en er kunnen vanuit de portal query's op worden uitgevoerd.

Meld u aan bij de Azure Portal in uw webbrowser om de gebruikersgegevens die u in de vorige stap hebt gemaakt, te bekijken, query’s erop uit te voeren of andere taken ermee uit te voeren.

Voer Azure Cosmos DB in het bovenste zoekvak in. Wanneer de blade van uw Azure Cosmos DB-account wordt geopend, selecteert u uw Azure Cosmos DB-account. Selecteer in het linker navigatiegedeelte Data Explorer. Vouw uw verzameling uit in het venster Verzamelingen. Dan kunt u de documenten in de verzameling zien, query’s op de gegevens uitvoeren en zelfs opgeslagen procedures, triggers en UDF’s maken en uitvoeren.

Data Explorer waarin het zojuist gemaakte document wordt weergegeven

Verwijder een todo met behulp van de id:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Geef de todos weer die u wilt bevestigen:

./todo --list all

Het bestand dat todo u zojuist hebt verwijderd, mag niet aanwezig zijn:

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

Resources opschonen

Wanneer u uw app en Azure Cosmos DB-account niet meer nodig hebt, kunt u de Azure-resources die u hebt gemaakt, verwijderen zodat er geen kosten meer voor in rekening worden gebracht. Om de resources te verwijderen:

Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.
Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.
Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.
Selecteer in het volgende venster de naam van de resourcegroep die u wilt verwijderen en selecteer vervolgens Verwijderen.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB voor MongoDB-account maakt met behulp van De Azure Cloud Shell en een Go-opdrachtregel-app maakt en uitvoert om s te beheren todo. Nu kunt u aanvullende gegevens in uw Azure Cosmos DB-account importeren.

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

Als alles wat u weet het aantal vcores en servers in uw bestaande databasecluster is, leest u meer over het schatten van aanvraageenheden met behulp van vCores of vCPU's
Als u typische aanvraagtarieven voor uw huidige databaseworkload kent, leest u meer over het schatten van aanvraageenheden met behulp van azure Cosmos DB-capaciteitsplanner

MongoDB-gegevens importeren in Azure Cosmos DB

Quickstart: een Go-toepassing Verbinding maken naar Azure Cosmos DB voor MongoDB

Vereisten

De voorbeeldtoepassing klonen

De code bekijken

De Go-app verbinden met Azure Cosmos DB

Een todo-item maken

todo-items weergeven

Een todo-item bijwerken

Een todo verwijderen

De toepassing bouwen

Azure Cosmos DB instellen

Aanmelden bij Azure

De Azure Cosmos DB-module toevoegen

Een brongroep maken

Een Azure Cosmos DB-account maken

De databasesleutel ophalen

De toepassing configureren

Exporteer de namen van de verbindingsreeks, mongoDB-database en verzameling als omgevingsvariabelen.

De toepassing uitvoeren

Gegevens bekijken in Data Explorer

Resources opschonen

Volgende stappen

Aanvullende resources

Een `todo`-item maken

`todo`-items weergeven

Een `todo`-item bijwerken

Een `todo` verwijderen