Краткое руководство. Подключение приложение Go в Azure Cosmos DB для MongoDB

Статья
03/29/2023

Область применения: Mongodb

Azure Cosmos DB — это служба многомодельной базы данных, позволяющая быстро создать и запрашивать документы, таблицы, пары "ключ-значение", а также графовые базы данных, используя возможности глобального распределения и горизонтального масштабирования. В этом кратком руководстве описано, как создать учетную запись Azure Cosmos DB и управлять ею с помощью Azure Cloud Shell, клонировать имеющийся пример приложения из GitHub и настроить его для работы с Azure Cosmos DB.

Пример приложения — это программа командной строки для управления элементами todo, написанная на языке Go. API-интерфейс Azure Cosmos DB для MongoDB совместим с протоколом проводной сети MongoDB, благодаря чему к нему может подключиться любой клиентский драйвер MongoDB. Это приложение использует драйвер Go для MongoDB таким образом, что ему прозрачно предоставляются сведения о хранении данных в базе данных Azure Cosmos DB.

Необходимые компоненты

Учетная запись Azure с активной подпиской. Создайте ее бесплатно. Или бесплатно поработайте с Azure Cosmos DB без подписки Azure. Вы также можете воспользоваться эмулятором Azure Cosmos DB со строкой подключения .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
На компьютере должна быть установлена среда Go, а у вас должен быть опыт работы с этим языком.
Git.

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Клонирование примера приложения

Затем выполните следующие команды, чтобы клонировать репозиторий с примером.

Откройте командную строку, создайте папку git-samples, а затем закройте окно командной строки.
```
mkdir "C:\git-samples"
```
Откройте окно терминала git, например git bash, и выполните команду cd, чтобы перейти в новую папку для установки примера приложения.
```
cd "C:\git-samples"
```
Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

Просмотр кода

Этот шаг необязательный. Если вы хотите узнать, как работает приложение, изучите приведенные ниже фрагменты кода. В противном случае вы можете сразу перейти к разделу Выполнение приложения. Макет приложения выглядит следующим образом:

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

Приведенные ниже фрагменты кода взяты из файла todo.go.

Подключение приложения Go к Azure Cosmos DB

clientOptions инкапсулирует строку подключения к Azure Cosmos DB, которая передается в переменной среды (дополнительные сведения см. в следующем разделе). Подключение инициализируется с помощью функции mongo.NewClient, которой передается экземпляр clientOptions. Ping Функция вызывается для подтверждения успешного подключения (это стратегия сбоя).

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

Примечание.

При этом важно использовать конфигурацию SetDirect(true), без которой произойдет следующая ошибка подключения: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed.

Создание элемента `todo`

Чтобы создать todo, можно запустить обработчик для mongo.Collection и вызвать функцию 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)
    }

Мы передаём структуру Todo , содержащую описание и состояние (которое изначально задано в pending):

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

Элементы списка `todo`

Список задач можно составлять на основе условий. Создается для bson.D инкапсулировать критерии фильтра:

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 для поиска документов, соответствующих условиям фильтра, а результат преобразуется в срез 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)
    }

Наконец, сведения отображаются в табличном формате:

    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`

todo можно обновить на основе _id. Создается фильтр bson.D создается на основе _id и еще один для обновленных сведений, что в нашем примере соответствует состоянию "новые" (completed или pending). Наконец, UpdateOne функция вызывается фильтром и обновленным документом:

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

Удаление `todo`

Объект todo удаляется на основе его _id инкапсулируется в виде экземпляра bson.D . Для удаления документа вызывается DeleteOne.

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

Сборка приложения

Перейдите в каталог, куда клонировано приложение, и создайте его (с помощью go build).

cd monogdb-go-quickstart
go build -o todo

Чтобы убедиться в правильности работы созданного приложения, воспользуйтесь следующей командой:

./todo --help

Настройка Azure Cosmos DB

Если вы решили установить и использовать ИНТЕРФЕЙС командной строки локально, в этом разделе требуется, чтобы вы работали с Azure CLI версии 2.0 или более поздней. Чтобы узнать версию, выполните команду az --version. Если вам необходимо выполнить установку или обновление, см. статью [Установка Azure CLI].

Если вы используете установленный Интерфейс командной строки Azure, войдите в подписку Azure с помощью команды az login и следуйте инструкциям на экране. Этот шаг можно пропустить, если вы используете Azure Cloud Shell.

az login

Добавление модуля Azure Cosmos DB

Если вы используете установленный Интерфейс командной строки Azure, проверка, чтобы узнать, установлен ли cosmosdb компонент, выполнив az команду. Если компонент cosmosdb включен в список базовых команд, перейдите к следующей команде. Этот шаг можно пропустить, если вы используете Azure Cloud Shell.

Если cosmosdb нет в списке базовых команд, переустановите Azure CLI.

Создание или изменение группы ресурсов

Создайте группу ресурсов с помощью команды az group create. Группа ресурсов Azure — это логический контейнер, в котором происходит развертывание ресурсов Azure (веб-приложений, баз данных и учетных записей хранения) и управление ими.

В следующем примере показано создание группы ресурсов в регионе "Западная Европа". Выберите уникальное имя для группы ресурсов.

Если вы используете Azure Cloud Shell, нажмите кнопку "Попробовать", следуйте инструкциям на экране, чтобы войти в систему, а затем скопируйте команду в командную строку.

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

Создание учетной записи Azure Cosmos DB

Создайте учетную запись Azure Cosmos DB с помощью команды az cosmosdb create.

В следующей команде замените <cosmosdb-name> уникальным именем своей базы данных Azure Cosmos DB везде, где встречается этот заполнитель. Это уникальное имя будет использоваться как часть конечной точки Azure Cosmos DB (https://<cosmosdb-name>.documents.azure.com/), поэтому оно должно быть уникальным для всех учетных записей Cosmos DB в Azure.

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

Параметр --kind MongoDB разрешает клиентские подключения MongoDB.

После создания учетной записи Azure Cosmos DB в Azure CLI отображаются сведения, схожие с теми, которые приведены ниже.

Примечание.

В этом примере JSON по умолчанию используется как формат выходных данных Azure CLI. Чтобы использовать другой формат выходных данных, ознакомьтесь со статьей Форматы выходных данных для команд 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"
    }
  ]
}

Получение ключа базы данных

Чтобы подключиться к базе данных Azure Cosmos DB, вам понадобится ключ базы данных. Чтобы получить первичный ключ, выполните команду az cosmosdb keys list.

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

В Azure CLI отображаются сведения, подобные следующим:

"RUayjYjixJDWG5xTqIiXjC..."

Настройка веб-приложения

Экспортируйте строку подключения, базу данных MongoDB и имена коллекций как переменные среды.

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

Примечание.

Этот ssl=true параметр важен из-за требований Azure Cosmos DB. Дополнительные сведения см. в разделе Требования к строке подключения.

Для переменной среды MONGODB_CONNECTION_STRING замените заполнители для <COSMOSDB_ACCOUNT_NAME> и <COSMOSDB_PASSWORD>

<COSMOSDB_ACCOUNT_NAME>: имя учетной записи Azure Cosmos DB, которую вы создали
<COSMOSDB_PASSWORD>: ключ базы данных, извлеченный на предыдущем шаге

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Вы можете выбрать предпочтительные значения для MONGODB_DATABASE и MONGODB_COLLECTION или оставить их как есть.

Выполнение приложения

Создание todo

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

В случае успеха вы увидите выходные данные с _id MongoDB для только что созданного документа.

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Создайте еще один элемент todo.

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

Перечислите все элементы todo.

./todo --list all

Вы должны увидеть только что добавленные в табличном формате:

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

Чтобы обновить состояние todo (например, изменить его на completed состояние), используйте todo идентификатор:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Перечислите только завершенные элементы todo.

./todo --list completed

Вы должны увидеть только что обновленный:

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

Просмотр данных в обозревателе данных

Данные, хранимые в Azure Cosmos DB, доступны для просмотра и запроса на портале Azure.

Чтобы просмотреть данные пользователя, созданные на предыдущем шаге, запросить их и начать с ними работать, войдите на портал Azure с помощью своего браузера.

В поле поиска в верхней области введите Azure Cosmos DB. Когда откроется колонка учетной записи Azure Cosmos DB, выберите учетную запись Azure Cosmos DB. В левой области навигации щелкните Обозреватель данных. Разверните свою коллекцию на панели коллекций. Вы сможете увидеть документы в коллекции, запросить данные и даже создать и запустить хранимые процедуры, триггеры и определенные пользователем функции.

Обозреватель данных, отображающий только что созданный документ

todo Удалите идентификатор, используя его идентификатор:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

todoСписок s для подтверждения:

./todo --list all

Только что удаленные todo не должны присутствовать:

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

Очистка ресурсов

После завершения работы с приложением и учетной записью Azure Cosmos DB можно удалить созданные ресурсы Azure, чтобы избежать дополнительных расходов. Удаление ресурсов:

На панели поиска портала Azure найдите и выберите Группы ресурсов.
Выберите из списка группу ресурсов, созданную для этого краткого руководства.
На странице обзора группы ресурсов выберите Удалить группу ресурсов.
В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

Следующие шаги

Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB для MongoDB с помощью Azure Cloud Shell и создать и запустить приложение командной строки Go для управления todos. Теперь можно импортировать дополнительные данные в учетную запись Azure Cosmos DB.

Если вы планируете ресурсы для миграции в Azure Cosmos DB, Для планирования ресурсов можно использовать сведения об имеющемся кластере базы данных.

Если вам известно только количество виртуальных ядер и серверов в существующем кластере баз данных, прочитайте об оценке единиц запроса на основе этих данных.
Если вам известна стандартная частота запросов для текущей рабочей нагрузки базы данных, ознакомьтесь со статьей о расчете единиц запросов с помощью планировщика ресурсов Azure Cosmos DB

Перенос данных MongoDB в Azure Cosmos DB

Краткое руководство. Подключение приложение Go в Azure Cosmos DB для MongoDB

Необходимые компоненты

Клонирование примера приложения

Просмотр кода

Подключение приложения Go к Azure Cosmos DB

Создание элемента todo

Элементы списка todo

Обновление элемента todo

Удаление todo

Сборка приложения

Настройка Azure Cosmos DB

Вход в Azure

Добавление модуля Azure Cosmos DB

Создание или изменение группы ресурсов

Создание учетной записи Azure Cosmos DB

Получение ключа базы данных

Настройка веб-приложения

Экспортируйте строку подключения, базу данных MongoDB и имена коллекций как переменные среды.

Выполнение приложения

Просмотр данных в обозревателе данных

Очистка ресурсов

Следующие шаги

Дополнительные ресурсы

Создание элемента `todo`

Элементы списка `todo`

Обновление элемента `todo`

Удаление `todo`