Rychlý start: Připojení aplikace Go do služby Azure Cosmos DB pro MongoDB

Článek
04/19/2024

PLATÍ PRO: MongoDB

Azure Cosmos DB je databázová služba s více modely, která umožňuje rychle vytvářet a dotazovat dokumenty, tabulky, klíč-hodnota a grafové databáze s funkcemi globální distribuce a horizontálního škálování. V tomto rychlém startu vytvoříte a spravujete účet služby Azure Cosmos DB pomocí služby Azure Cloud Shell, naklonujete existující ukázkovou aplikaci z GitHubu a nakonfigurujete ho pro práci se službou Azure Cosmos DB.

Ukázková aplikace je nástroj pro správu založený na todo příkazovém řádku napsaný v go. Rozhraní API služby Azure Cosmos DB pro MongoDB je kompatibilní s přenosovém protokolem MongoDB, takže se k němu může připojit jakýkoli klientský ovladač MongoDB. Tato aplikace používá ovladač Go pro MongoDB způsobem, který je transparentní pro aplikaci, kterou jsou data uložena v databázi Azure Cosmos DB.

Požadavky

Účet Azure s aktivním předplatným. Vytvořte si ho zdarma. Nebo vyzkoušejte službu Azure Cosmos DB zdarma bez předplatného Azure. Můžete také použít emulátor služby Azure Cosmos DB s připojovací řetězec .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Běžte si nainstalovat do počítače a pracujte na Jazyku Go.
Git

Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.
Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
- Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
- Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
- Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Klonování ukázkové aplikace

Spuštěním následujících příkazů naklonujte ukázkové úložiště.

Otevřete příkazový řádek, vytvořte novou složku s názvem git-samplesa pak zavřete příkazový řádek.
```
mkdir "C:\git-samples"
```
Otevřete okno terminálu Git, například Git Bash, a pomocí příkazu cd přejděte do nové složky, do které chcete nainstalovat ukázkovou aplikaci.
```
cd "C:\git-samples"
```
Ukázkové úložiště naklonujete spuštěním následujícího příkazu. Tento příkaz vytvoří na vašem počítači kopii ukázkové aplikace.
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

Kontrola kódu

Tento krok je nepovinný. Pokud se chcete dozvědět, jak aplikace funguje, můžete zkontrolovat následující fragmenty kódu. V opačném případě můžete přeskočit k spuštění aplikace. Rozložení aplikace je následující:

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

Všechny následující fragmenty kódu pocházejí ze souboru todo.go.

Připojení aplikace v jazyce Go ke službě Azure Cosmos DB

clientOptionszapouzdřuje připojovací řetězec pro službu Azure Cosmos DB, která se předává pomocí proměnné prostředí (podrobnosti v nadcházející části). Připojení se inicializuje pomocí mongo.NewClient , do kterého clientOptions se instance předává. Ping funkce se vyvolá, aby se potvrdilo úspěšné připojení (jedná se o strategii se selháním).

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

Poznámka:

SetDirect(true) Použití konfigurace je důležité, bez kterého se zobrazí následující chyba připojení:unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Vytvoření `todo` položky

Abychom vytvořili todo, získáme popisovač mongo.Collection funkce a vyvoláme ji InsertOne .

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

Předáváme Todo strukturu, která obsahuje popis a stav (který je původně nastaven na pending):

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

Položky seznamu `todo`

Na základě kritérií můžeme vypsat toDO. Vytvoří se A bson.D pro zapouzdření kritérií filtru:

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 slouží k vyhledávání dokumentů na základě filtru a výsledek se převede na řez 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)
    }

Nakonec se informace vykreslují v tabulkovém formátu:

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

`todo` Aktualizace položky

A todo lze aktualizovat na základě jeho _id. Vytvoří se bson.D filtr založený na _id tom, který druhý se vytvoří pro aktualizované informace, což je nový stav (completed nebo pending) v tomto případě. Nakonec se UpdateOne funkce vyvolá pomocí filtru a aktualizovaného dokumentu:

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

Odstranění `todo`

A todo se odstraní na základě jeho _id a zapouzdří se ve formě bson.D instance. DeleteOne je vyvolána k odstranění dokumentu.

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

Sestavení aplikace

Přejděte do adresáře, do kterého jste naklonovali aplikaci, a sestavte ji (pomocí go build).

cd monogdb-go-quickstart
go build -o todo

Abyste si ověřili, že aplikace byla správně sestavená.

./todo --help

Nastavení služby Azure Cosmos DB

Pokud se rozhodnete nainstalovat a používat rozhraní příkazového řádku místně, musíte mít Azure CLI verze 2.0 nebo novější. Verzi zjistíte spuštěním příkazu az --version. Pokud potřebujete nainstalovat nebo upgradovat, přečtěte si téma [Instalace Azure CLI].

Pokud používáte nainstalované Rozhraní příkazového řádku Azure, přihlaste se ke svému předplatnému Azure pomocí příkazu az login a postupujte podle pokynů na obrazovce. Pokud používáte Azure Cloud Shell, můžete tento krok přeskočit.

az login

Přidání modulu služby Azure Cosmos DB

Pokud používáte nainstalované Rozhraní příkazového řádku Azure, spuštěním příkazu zkontrolujte, jestli cosmosdb už je komponenta nainstalovaná az . Pokud se komponenta cosmosdb v seznamu základních příkazů nachází, pokračujte k dalšímu příkazu. Pokud používáte Azure Cloud Shell, můžete tento krok přeskočit.

Pokud cosmosdb není v seznamu základních příkazů, přeinstalujte Azure CLI.

Vytvoření skupiny zdrojů

Vytvořte pomocí příkazu az group create skupinu prostředků. Skupina prostředků Azure je logický kontejner, do kterého se nasazují a spravují prostředky Azure, jako jsou webové aplikace, databáze a účty úložiště.

Následující příklad vytvoří skupinu prostředků pro oblast Západní Evropa. Pro skupinu prostředků vyberte jedinečný název.

Pokud používáte Azure Cloud Shell, vyberte Vyzkoušet, přihlaste se podle pokynů na obrazovce a zkopírujte příkaz do příkazového řádku.

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

Vytvoření účtu služby Azure Cosmos DB

Pomocí příkazu az cosmosdb create vytvořte účet služby Azure Cosmos DB.

V následujícím příkazu nahraďte zástupný symbol <cosmosdb-name> vlastním jedinečným názvem účtu služby Azure Cosmos DB. Tento jedinečný název se použije jako součást koncového bodu služby Azure Cosmos DB (https://<cosmosdb-name>.documents.azure.com/). Název proto musí být jedinečný ve všech účtech služby Azure Cosmos DB platformy Azure.

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

Parametr --kind MongoDB umožňuje klientská připojení MongoDB.

Po vytvoření účtu služby Azure Cosmos DB zobrazí rozhraní příkazového řádku Azure podobné informace jako v následujícím příkladu.

Poznámka:

Tento příklad jako formát výstupu Azure CLI používá výchozí JSON. Pokud chcete použít jiný formát výstupu, přečtěte si téma Formáty výstupu pro příkazy Azure CLI.

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

Načtení klíče databáze

Aby bylo možné se připojit k databázi služby Azure Cosmos DB, potřebujete klíč databáze. Pomocí příkazu az cosmosdb keys list načtěte primární klíč.

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

Výstupní informace rozhraní příkazového řádku Azure jsou podobné jako v následujícím příkladu.

"RUayjYjixJDWG5xTqIiXjC..."

Konfigurace aplikace

Exportujte názvy připojovací řetězec, databáze MongoDB a kolekce jako proměnné prostředí.

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

Poznámka:

Tato ssl=true možnost je důležitá kvůli požadavkům služby Azure Cosmos DB. Další informace najdete v tématu Připojení požadavky na řetězec.

Pro proměnnou MONGODB_CONNECTION_STRING prostředí nahraďte zástupné symboly pro <COSMOSDB_ACCOUNT_NAME> a <COSMOSDB_PASSWORD>

<COSMOSDB_ACCOUNT_NAME>: Název účtu služby Azure Cosmos DB, který jste vytvořili.
<COSMOSDB_PASSWORD>: Klíč databáze extrahovaný v předchozím kroku

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Můžete zvolit preferované hodnoty MONGODB_DATABASE nebo MONGODB_COLLECTION je nechat tak, jak jsou.

Spuštění aplikace

Vytvoření todo

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

V případě úspěchu by se měl zobrazit výstup s MongoDB _id nově vytvořeného dokumentu:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Vytvořit další todo

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

Zobrazit seznam všech položek todo

./todo --list all

Měli byste vidět ty, které jste právě přidali v tabulkovém formátu, například:

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

Pokud chcete aktualizovat stav todo (např. změnit na completed stav), použijte todo ID:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Vypsat pouze dokončené todopoložky

./todo --list completed

Měli byste vidět ten, který jste právě aktualizovali:

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

Zobrazení dat v Průzkumníku dat

Data uložená ve službě Azure Cosmos DB jsou k dispozici k zobrazení a dotazování na webu Azure Portal.

Pokud chcete zobrazovat uživatelská data vytvořená v předchozím kroku, zadávat na ně dotazy a pracovat s nimi, přihlaste se k portálu Azure Portal ve webovém prohlížeči.

Do horního vyhledávacího pole zadejte Azure Cosmos DB. Po otevření okna účtu služby Azure Cosmos DB vyberte svůj účet služby Azure Cosmos DB. V levém navigačním panelu vyberte Průzkumník dat. Rozbalte kolekci v podokně Kolekce. Pak můžete zobrazovat dokumenty v kolekci, dotazovat se na data a dokonce vytvářet a spouštět uložené procedury, triggery a funkce UDF.

Průzkumník dat zobrazující nově vytvořený dokument

todo Odstranění pomocí jeho ID:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Uveďte seznam, který todochcete potvrdit:

./todo --list all

Právě todo odstraněné položky by neměly být k dispozici:

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

Vyčištění prostředků

Až budete s aplikací a účtem služby Azure Cosmos DB hotovi, můžete odstranit vytvořené prostředky Azure, takže se vám nebudou účtovat další poplatky. Odstranění prostředků:

Na panelu hledání na webu Azure Portal vyhledejte a vyberte skupiny prostředků.
V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro účely tohoto rychlého startu.
Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.
V dalším okně zadejte název skupiny prostředků, která se má odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet služby Azure Cosmos DB pro MongoDB pomocí služby Azure Cloud Shell a vytvořit a spustit aplikaci příkazového řádku Go pro správu todos. Teď můžete do svého účtu služby Azure Cosmos DB importovat další data.

Pokoušíte se naplánovat kapacitu migrace do služby Azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.

Pokud víte, že je počet virtuálních jader a serverů ve vašem existujícím databázovém clusteru, přečtěte si o odhadu jednotek žádostí pomocí virtuálních jader nebo virtuálních procesorů.
Pokud znáte typické sazby požadavků pro vaši aktuální úlohu databáze, přečtěte si informace o odhadu jednotek žádostí pomocí plánovače kapacity služby Azure Cosmos DB.

Importování dat MongoDB do databáze Azure Cosmos

Rychlý start: Připojení aplikace Go do služby Azure Cosmos DB pro MongoDB

Požadavky

Klonování ukázkové aplikace

Kontrola kódu

Připojení aplikace v jazyce Go ke službě Azure Cosmos DB

Vytvoření todo položky

Položky seznamu todo

todo Aktualizace položky

Odstranění todo

Sestavení aplikace

Nastavení služby Azure Cosmos DB

Přihlášení k Azure

Přidání modulu služby Azure Cosmos DB

Vytvoření skupiny zdrojů

Vytvoření účtu služby Azure Cosmos DB

Načtení klíče databáze

Konfigurace aplikace

Exportujte názvy připojovací řetězec, databáze MongoDB a kolekce jako proměnné prostředí.

Spuštění aplikace

Zobrazení dat v Průzkumníku dat

Vyčištění prostředků

Další kroky

Další materiály

Vytvoření `todo` položky

Položky seznamu `todo`

`todo` Aktualizace položky

Odstranění `todo`