Краткое руководство. Создание приложения Go с `gocql` помощью клиента для управления данными Azure Cosmos DB для Apache Cassandra

Статья
03/22/2023

ПРИМЕНИМО К: Кассандра

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

Предварительные требования

Учетная запись Azure с активной подпиской. Создайте бесплатно. Или воспользуйтесь пробной версией Azure Cosmos DB без подписки Azure.
На компьютере должна быть установлена среда Go, а у вас должен быть опыт работы с этим языком.
Git.

Создание учетной записи базы данных

Прежде чем создавать базу данных, необходимо создать в Azure Cosmos DB учетную запись Cassandra.

На домашней странице или в меню портала Azure выберите Создать ресурс.
На странице Создание найдите и выберите Azure Cosmos DB.
На странице Azure Cosmos DB выберите Создать.
На странице API выберите Создать в разделе Cassandra .

API определяет тип учетной записи, которую нужно создать. Azure Cosmos DB предоставляет пять API: NoSQL для баз данных документов, Gremlin для баз данных графов, MongoDB для баз данных документов, Azure Table и Cassandra. Для каждого API требуется создать отдельную учетную запись.

Выберите Cassandra, так как в этом кратком руководстве вы создаете таблицу, которая работает с API для Cassandra.

Дополнительные сведения об API для Cassandra.

На странице Создание учетной записи Azure Cosmos DB введите основные параметры для новой учетной записи Azure Cosmos DB.

Параметр	Значение	Описание
Подписка	Ваша подписка	Вы подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos DB.
Группа ресурсов	Создание Затем введите имя, использованное для учетной записи	Выберите Создать. Затем введите новое имя группы ресурсов для учетной записи. Для удобства можно использовать то же имя, которое присвоено учетной записи Azure Cosmos DB.
Имя учетной записи	Введите уникальное имя.	Введите уникальное имя для идентификации вашей учетной записи Azure Cosmos DB. URI вашей учетной записи cassandra.cosmos.azure.com будет добавлен к уникальному имени учетной записи. Имя может содержать только строчные буквы, цифры и дефисы. Его длина должна быть от 3 до 31 знаков.
Расположение	Ближайший к пользователям регион	Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.
Режим емкости	"Подготовленная пропускная способность" или "Бессерверный"	Выберите Подготовленная пропускная способность, чтобы создать учетную запись в режиме подготовленной пропускной способности. Выберите Бессерверный, чтобы создать учетную запись в режиме Бессерверный.
Применение скидки на основе категории "Бесплатный" для Azure Cosmos DB	Применить или не применять	В категории "Бесплатный" Azure Cosmos DB для учетной записи бесплатно предоставляются первые 1000 единиц запросов в секунду и 25 ГБ свободного места. Ознакомьтесь с дополнительными сведениями о категории "Бесплатный".
Ограничение общей пропускной способности учетной записи	Выбор ограничения пропускной способности учетной записи	Это полезно, если вы хотите ограничить общую пропускную способность учетной записи определенным значением.

Примечание

Вы можете использовать не более одной учетной записи Azure Cosmos DB категории "Бесплатный" на подписку Azure. При создании учетной записи нужно зарегистрироваться. Если параметр подачи заявки на скидку на основе категории "Бесплатный" не отображается, это означает, что в подписке уже включена другая учетная запись категории "Бесплатный".

Страница новой учетной записи для Azure Cosmos DB для Apache Cassandra

На вкладке Глобальное распределение настройте следующие сведения. При работе с этим кратким руководством можно оставить значения по умолчанию.

Параметр	Значение	Описание
Геоизбыточность	Отключить	Включает или отключает глобальное распределение в вашей учетной записи, связывая ваш регион с парным регионом. В дальнейшем в учетную запись можно добавить дополнительные регионы.
Операции записи с поддержкой нескольких регионов	Отключить	Поддержка записи в несколько регионов позволяет использовать подготовленную пропускную способность для баз данных и контейнеров по всему миру.
зоны доступности;	Отключить	Зоны доступности — это изолированные расположения в регионе Azure. Каждая зона состоит из одного или нескольких центров обработки данных, оснащенных независимыми системами электроснабжения, охлаждения и сетевого взаимодействия.

Примечание

Следующие параметры недоступны, если вы выбрали значение Бессерверный для параметра Режим емкости:

Применение скидки на основе категории "Бесплатный"
Геоизбыточность
Выполнение операций записи в нескольких регионах

При необходимости можно настроить дополнительные сведения на следующих вкладках.
- Сеть: настройка доступа из виртуальной сети.
- Политика резервного копирования: настройте политику периодического или непрерывного резервного копирования.
- Шифрование: используйте либо ключ, управляемый службой, либо ключ, управляемый клиентом.
- Теги: теги — это пары имя — значение, которые можно назначать различным ресурсам и группам ресурсов для их категоризации и консолидированного отображения счетов.
Выберите Review + create (Просмотреть и создать).
Проверьте параметры учетной записи, а затем нажмите кнопку Создать. Создание учетной записи занимает несколько минут. Дождитесь, пока на странице портала появится сообщение Развертывание выполнено.
Выберите Перейти к ресурсу, чтобы перейти на страницу учетной записи Azure Cosmos DB.

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

Прежде всего, клонируйте приложение из репозитория GitHub.

Откройте командную строку и создайте новую папку с именем git-samples.
```
md "C:\git-samples"
```
Откройте окно терминала Git, например Git Bash. С помощью команды cd перейдите в новую папку и установите пример приложения.
```
cd "C:\git-samples"
```
Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

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

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

Функция GetSession (в файле utils\utils.go) возвращает структуру *gocql.Session, которая используется для выполнения в кластере операций вставки, поиска и т. д.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Узел Cassandra в Azure Cosmos DB передается функции gocql.NewCluster, которая возвращает структуру *gocql.ClusterConfig, в которой мы затем настраиваем имя пользователя, пароль, порт и версию TLS (требование безопасности для шифрования HTTPS/SSL/TLS).

Затем из функции main (main.go) вызывается функция GetSession.

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

Сведения о подключении и учетные данные принимаются в виде переменных среды (значения разрешаются в методе init).

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

Эти данные применяются для выполнения операций в Azure Cosmos DB (в файле operations\setup.go), начиная с создания keyspace и table.

Как видно из названия, функция DropKeySpaceIfExists удаляет пространство ключей keyspace только в том случае, если оно существует.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

Функция CreateKeySpace применяется для создания keyspace (user_profile).

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

За этим следует создание таблиц (user), которым занимается функция CreateUserTable.

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

После создания пространства ключей и таблицы мы вызываем операции CRUD (в файле operations\crud.go).

Для создания User используется InsertUser. Она передает сведения о пользователе (идентификатор, имя и город) в качестве аргументов запроса, используя Bind.

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

Выполняется FindUser для поиска пользователя (model\user.go) по идентификатору пользователя, а затем Scan для привязки атрибутов пользователя (полученных от Cassandra) к отдельным переменным (userid, name и city). Это лишь один из возможных способов использовать результат, полученный от поискового запроса.

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers применяется для получения всех пользователей. SliceMap является краткой формой записи для получения сведений о пользователе в виде среза структуры map. Каждую структуру map можно рассматривать как пару "ключ — значение", где ключом является имя столбца (например, user_id), а значение извлекается из соответствующего столбца.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Каждая map из набора сведений о пользователе преобразуется в User с помощью функции mapToUser, которая просто извлекает значение из соответствующего столбца и создает на его основе экземпляр структуры User.

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

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

Как упоминалось ранее, приложение принимает сведения о подключении и учетные данные в виде переменных среды.

Выберите элемент Строка подключения в своей учетной записи Azure Cosmos DB на портале Azure.

Скопируйте значения следующих атрибутов (CONTACT POINT, PORT, USERNAME и PRIMARY PASSWORD) и сохраните их в соответствующие переменные среды.

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

В окне терминала перейдите в нужную папку. Пример:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

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

go run main.go

В окне терминала отображаются уведомления об операциях, включая настройку пространства ключей и таблицы, создание пользователя и т. д.
На портале Azure откройте обозреватель данных, чтобы запросить, изменить и обработать новые данные.

Просмотр соглашений об уровне обслуживания на портале Azure

Портал Azure отслеживает пропускную способность, хранилище, доступность, задержку и согласованность учетной записи Azure Cosmos DB. На диаграммах метрик, связанных с соглашением об уровне обслуживания для Azure Cosmos DB, отображается значение, указанное в соглашении об уровне обслуживания, в сравнении с фактической производительностью. Этот набор метрик обеспечивает прозрачный мониторинг выполнения соглашения об уровне обслуживания.

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

Выберите Метрики в меню навигации учетной записи Azure Cosmos DB.
Выберите вкладку, например Задержка, и укажите временной интервал справа. Сравните на диаграмме строки Actual (Фактическое значение) и SLA (Соглашение об уровне обслуживания).
Просмотрите метрики на других вкладках.

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

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

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

Дальнейшие действия

Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB с ПОМОЩЬЮ API для Cassandra и запустить приложение Go, которое создает базу данных и контейнер Cassandra. Теперь вы можете импортировать дополнительные данные в учетную запись Azure Cosmos DB.

Импорт данных Cassandra в Azure Cosmos DB

Краткое руководство. Создание приложения Go с gocql помощью клиента для управления данными Azure Cosmos DB для Apache Cassandra