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

Článek
05/02/2022
9 min ke čtení

PLATÍ PRO: Rozhraní API služby Azure Cosmos DB pro MongoDB

Azure Cosmos DB je vícemodelová databázová služba, která umožňuje rychle vytvářet a dotazovat dokumenty, tabulky, klíčové hodnoty a grafové databáze s globální distribucí a horizontálním škálováním. V tomto rychlém startu vytvoříte a spravujete účet Azure Cosmos DB pomocí azure Cloud Shell, naklonujete existující ukázkovou aplikaci z GitHub a nakonfigurujete ho tak, aby fungoval s 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 wire 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, že data jsou 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 Azure Cosmos DB zdarma bez předplatného Azure. Můžete také použít azure Cosmos DB Emulator s připojovacím řetězcem .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Přejděte na počítač a pracujte se na Go.
Git.

Použijte prostředí Bash v Azure Cloud Shell. Další informace najdete v tématu Rychlý start azure Cloud Shell – Bash.
Pokud dáváte přednost místnímu spuš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 Dockeru. 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í jsou popsané 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 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 volitelný. 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 dopředu a spustit aplikaci. 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 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 toho, do kterého clientOptions je instance předána. Ping funkce se vyvolá k potvrzení úspěšného připojení (jedná se o strategii selhání)

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

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

`todo` Vytvoření položky

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

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`

ToDO můžeme vypsat na základě kritérií. 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 hledá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. Filtr bson.D se vytvoří na _id základě a další se vytvoří pro aktualizované informace, což je nový stav (completed nebo pending) v tomto případě. Nakonec se UpdateOne funkce vyvolá s filtrem a aktualizovaným dokumentem.

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 je odstraněn na základě jeho _id a je zapouzdřen 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 aplikaci naklonovali, a vytvořte ji (pomocí go build).

cd monogdb-go-quickstart
go build -o todo

Chcete-li ověřit, že aplikace byla správně sestavena.

./todo --help

Nastavení azure Cosmos DB

Pokud se rozhodnete nainstalovat a používat rozhraní příkazového řádku (CLI) místně, musíte mít spuštěnou verzi Azure CLI 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 k 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, zkontrolujte pomocí příkazu az, zda je komponenta cosmosdb už nainstalovaná. 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 se komponenta cosmosdb v seznamu základních příkazů nenachází, přeinstalujte rozhraní příkazového řádku Azure.

Vytvoření skupiny prostředků

Vytvořte skupinu prostředků pomocí příkazu az group create. Skupina prostředků Azure je logický kontejner, ve kterém se nasazují a spravují prostředky Azure, jako například 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 pak příkaz zkopírujte do příkazového řádku.

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

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

Vytvořte účet Cosmos pomocí příkazu az cosmosdb create.

V následujícím příkazu nahraďte vlastním jedinečným názvem účtu Cosmos, kde se zobrazí <cosmosdb-name> zástupný symbol. Tento jedinečný název se použije jako součást koncového bodu Cosmos DB,https://<cosmosdb-name>.documents.azure.com/ takže tento název musí být jedinečný pro všechny účty Cosmos v 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

Abyste se mohli připojit k databázi Cosmos, 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 připojovací řetězec, databázi MongoDB a názvy kolekcí 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á z důvodu Cosmos požadavků na databázi. Další informace najdete v tématu Požadavky na připojovací řetězec.

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

<COSMOSDB_ACCOUNT_NAME>: Název účtu Azure Cosmos DB, který jste vytvořili
<COSMOSDB_PASSWORD>: Databázový klíč extrahovaný v předchozím kroku

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Můžete zvolit upřednostňované hodnoty MONGODB_DATABASE a MONGODB_COLLECTION nechat je tak, jak je to.

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 stav na completed stav), použijte ID.todo

./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á v Azure Cosmos DB jsou dostupná k zobrazení a dotazování v 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. Když se otevře okno Cosmos účtu, vyberte svůj účet Cosmos. V levém navigačním panelu vyberte Data Explorer. 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.

Data Explorer showing the newly created document

todo Odstranění pomocí ID

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Výpis seznamu todo, který chcete potvrdit

./todo --list all

Právě todo odstraněné položky by neměly být přítomné.

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

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

Až budete hotovi s aplikací a účtem Azure Cosmos DB, můžete prostředky Azure, které jste vytvořili, odstranit, abyste nemuseli účtovat další poplatky. Odstranění prostředků:

Na panelu hledání 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á chcete odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet rozhraní MongoDB API služby Azure Cosmos DB pomocí 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 pro migraci do 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ů v existujícím databázovém clusteru, přečtěte si informace o odhadu jednotek žádostí pomocí virtuálních jader nebo virtuálních procesorů.
Pokud znáte typické sazby požadavků pro aktuální úlohu databáze, přečtěte si o odhadu jednotek žádostí pomocí Plánovače kapacity Azure Cosmos DB.

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

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

Je tato stránka užitečná?

Požadavky

Klonování ukázkové aplikace

Kontrola kódu

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

todo Vytvoření položky

Položky seznamu todo

todo Aktualizace položky

Odstranění todo

Sestavení aplikace

Nastavení azure Cosmos DB

Přihlášení k Azure

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

Vytvoření skupiny prostředků

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

Načtení klíče databáze

Konfigurace aplikace

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

Spuštění aplikace

Zobrazení dat v Průzkumníku dat

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

Další kroky

`todo` Vytvoření položky

Položky seznamu `todo`

`todo` Aktualizace položky

Odstranění `todo`