Quickstart: Een Go-toepassing koppelen aan de API van Azure Cosmos DB voor MongoDB

VAN TOEPASSING OP: Azure Cosmos DB-API voor 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 er gratis een. 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.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren.

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

1. Open een opdrachtprompt, maak een nieuwe map met de naam git-samples en sluit vervolgens de opdrachtprompt.

   mkdir "C:\git-samples"
   

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

3. 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. De Ping-functie wordt aangeroepen om de connectiviteit te bevestigen (het 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.NewClient(clientOptions)
    err = c.Connect(ctx)
    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)
    }

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

Voer een Todo-struct door die de beschrijving en de status (die in eerste instantie is ingesteld op pending) bevat

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. Een bson.D wordt gemaakt om de filtercriteria te omvatten

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 worden de gegevens in een tabel weergegeven

    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 basis van de bijbehorende _id 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

Aanmelden bij Azure

Als u ervoor kiest om de CLI lokaal te installeren en te gebruiken, moet u voor dit onderwerp gebruikmaken van Azure CLI versie 2.0 of hoger. 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 van een geïnstalleerde Azure CLI gebruikmaakt, controleert u of het onderdeel cosmosdb al is geïnstalleerd door de opdracht az 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 niet in de lijst met basisopdrachten staat, installeert u Azure CLI opnieuw.

Een resourcegroep 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 van Azure Cloud Shell gebruikmaakt, selecteert u Uitproberen, volgt u de aanwijzingen op het scherm om u aan te melden en kopieert u de opdracht naar de opdrachtprompt.

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

Maak een Azure Cosmos DB-account

Maak een Cosmos-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 Cosmos-accountnaam. Deze unieke naam wordt gebruikt als onderdeel van uw Cosmos DB-eindpunt (https://<cosmosdb-name>.documents.azure.com/). De naam moet daarom uniek zijn binnen alle Cosmos-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.

{
  "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 Cosmos-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 verbindingsreeks, de MongoDB-database en de verzamelingsnamen 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>@"

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

1. <COSMOSDB_ACCOUNT_NAME>: de naam van het Cosmos Azure DB-account dat u hebt gemaakt
2. <COSMOSDB_PASSWORD>: de databasesleutel die u in de vorige stap hebt 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

U zou de items die u zojuist hebt toegevoegd in een tabel moeten zien

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

Als u de status van een todo wilt bijwerken (bijvoorbeeld wijzigen in de status completed), gebruikt u de todo-id

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Geef alleen de voltooide todo's weer

./todo --list completed

U zou nu het item dat u zojuist hebt bijgewerkt moeten zien

+----------------------------+--------------------------------+-----------+
|             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 uw Cosmos-accountblade wordt geopend, selecteert u uw Cosmos-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.

Verwijder een todo met de bijbehorende id

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Geef de todo's weer om te bevestigen

./todo --list all

De todo die 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:

1. Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.

2. Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.

   

3. Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.

   

4. 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 MongoDB API-account maakt met behulp van Azure Cloud Shell en hoe u een app met Go-opdrachtregels kunt maken en uitvoeren om todo's te beheren. Nu kunt u aanvullende gegevens in uw Azure Cosmos DB-account importeren.

Probeert u capaciteitsplanning uit te Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

• Als u alleen het aantal vcores en servers in uw bestaande databasecluster weet, leest u over het schatten van aanvraageenheden met behulp van vCores of vCCPUs
• Als u de gebruikelijke aanvraagsnelheden voor uw huidige databaseworkload kent, leest u over het schatten van aanvraageenheden met behulp Azure Cosmos DB capacity planner