rychlý start: Připojení aplikaci v cestách pro Azure Cosmos DB API pro MongoDB

Článek
11/25/2021
9 min ke čtení

PLATÍ pro: Azure Cosmos DB API pro MongoDB

Azure Cosmos DB je databázová služba pro více modelů, která umožňuje rychle vytvářet a dotazovat databáze dokumentů, tabulek, klíčových hodnot a grafů s funkcemi globální distribuce a horizontálního škálování. v tomto rychlém startu vytvoříte a spravujete účet Azure Cosmos DB pomocí Azure Cloud Shell, naklonete existující ukázkovou aplikaci z GitHub a nakonfigurujete ji pro práci s Azure Cosmos DB.

Ukázková aplikace je nástroj pro správu založený na příkazovém řádku todo napsaný v části přejít. rozhraní API pro MongoDB je kompatibilní s MongoDBm přenosovým protokolem, takže je možné, že se k němu připojí kterýkoli klientský ovladač MongoDB. Azure Cosmos DB tato aplikace používá ovladač cestách pro MongoDB způsobem, který je transparentní pro aplikaci, že 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 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 .
V počítači se nainstaluje a získáte praktické znalosti o cestách.
Git.

V nástroji použijte prostředí Bash Azure Cloud Shell.
Pokud tomu dáváte přednost, můžete nainstalovat Azure CLI a spouštět referenční příkazy CLI.
- 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-samples a 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 volitelný. Pokud vás zajímá, jak aplikace funguje, můžete zkontrolovat následující fragmenty kódu. V opačném případě můžete přeskočit ke 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 Azure Cosmos DB, který se předává pomocí proměnné prostředí (podrobnosti najdete v nadcházející části). Připojení je inicializováno pomocí, mongo.NewClient ke kterému clientOptions je instance předána. vyvolaná Ping funkce pro potvrzení úspěšného připojení (Jedná se o strategii s chybou pro rychlé obnovení)

    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

Použití SetDirect(true) Konfigurace je důležité, bez toho, aby se zobrazila 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řit `todo` položku

Chcete-li vytvořit todo , získáme popisovač mongo.Collection a vyvolá 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áte do Todo struktury, která obsahuje popis a stav (který je zpočátku nastavený na hodnotu pending ).

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

`todo`Položky seznamu

Na základě kritérií můžeme seznam TODO. Vytvoří se 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 je převeden 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 vykreslí 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()

Aktualizace `todo` položky

todoMůže být aktualizován na základě jeho _id . Vytvoří se bson.D filtr založený na _id a druhý vytvoří aktualizované informace, což je nový stav ( completed nebo pending ) v tomto případě. Nakonec UpdateOne je funkce vyvolána 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í `todo`

A todo je odstraněn v závislosti na jeho _id a zapouzdřený ve formě bson.D instance. DeleteOne je vyvolána pro 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, kam jste naklonováni aplikaci, a sestavte ji (pomocí go build ).

cd monogdb-go-quickstart
go build -o todo

Pro potvrzení, že aplikace byla správně sestavena.

./todo --help

instalační 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 instalaci nebo upgrade, přečtěte si téma [instalace rozhraní příkazového řádku Azure].

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, 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í nástroje 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, postupujte podle pokynů na obrazovce pro přihlášení a pak 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 Cosmos.

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

aby bylo možné se připojit k databázi Cosmos, potřebujete klíč databáze. K načtení primárního klíče použijte příkaz AZ cosmosdb Keys list .

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, MongoDB databáze 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

ssl=truemožnost je důležitá z důvodu Cosmos DB požadavků. Další informace najdete v tématu požadavky na připojovací řetězec.

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

<COSMOSDB_ACCOUNT_NAME>: název účtu 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 pro MONGODB_DATABASE a MONGODB_COLLECTION nebo je nechat.

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 todo s

./todo --list all

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

+----------------------------+--------------------------------+-----------+
|             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 (třeba změnit na completed stav), použijte todo ID.

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Vy list only the completed todo s

./todo --list completed

Měl by se zobrazit 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 je možné zobrazit a dotazovat 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. Po otevření Cosmos účtu vyberte svůj Cosmos účet. 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

Odstranění todo s použitím ID

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

List the todo s to confirm

./todo --list all

Právě todo odstraněný soubor by neměl 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 Azure Cosmos DB účtem hotovi, můžete odstranit prostředky Azure, které jste vytvořili, abyste se neúčtují 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 tento rychlý Start.
Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.
V dalším okně zadejte název skupiny prostředků, kterou 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í rozhraní Azure Cloud Shell a jak vytvořit a spustit aplikaci příkazového řádku Go pro správu todo s. Teď můžete do svého účtu služby Azure Cosmos DB importovat další data.

Pokoušíte se provést plánování kapacity pro migraci do Azure Cosmos DB? Informace o existujícím databázovém clusteru můžete použít k plánování kapacity.

Pokud víte jen počet virtuálních jadr a serverů ve stávajícím databázovém clusteru, přečtěte si o odhadování jednotek žádostí pomocí virtuálních jadr nebo virtuálních procesorů.
Pokud znáte typickou míru požadavků pro aktuální databázové úlohy, přečtěte si o odhadování 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í aplikaci v cestách pro Azure Cosmos DB API pro MongoDB

Ohodnoťte vaše zkušenosti

Požadavky

Klonování ukázkové aplikace

Kontrola kódu

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

Vytvořit todo položku

todoPoložky seznamu

Aktualizace todo položky

Odstraní todo

Sestavení aplikace

instalační 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, MongoDB databáze 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

Vytvořit `todo` položku

`todo`Položky seznamu

Aktualizace `todo` položky

Odstraní `todo`