Быстрый старт: Azure Cosmos DB для клиентской библиотеки Apache Cassandra на Go

2025-07-21
Применяется к: ✅ Apache Cassanda

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

Справочная документация по | APIИсходный код | библиотекиПакет (Go)

Предпосылки

подписка Azure
- Если у вас нет подписки на Azure, создайте бесплатную учетную запись перед началом.

Последняя версия Azure CLI в Azure Cloud Shell.
- Если вы предпочитаете локально запускать справочные команды CLI, войдите в Azure CLI с помощью az login команды.

Go 1.24 или более поздней версии

Настройка

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

Создать аккаунт

Сначала создайте API для учетной записи Apache Cassandra. После создания учетной записи создайте пространство ключей и ресурсы для таблицы.

Azure CLI
Портал Azure

Если у вас еще нет целевой группы ресурсов, используйте az group create команду для создания новой группы ресурсов в подписке.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```
az cosmosdb create Используйте команду для создания новой учетной записи Azure Cosmos DB для Apache Cassandra с параметрами по умолчанию.
```
az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"
```

Создайте новое пространство ключей с именем cosmicworks с помощью az cosmosdb cassandra keyspace create.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Создайте новый объект JSON для представления схемы с помощью команды Bash с несколькими строками. Затем используйте az cosmosdb cassandra table create команду, чтобы создать новую таблицу с именем products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Войдите на портал Azure (https://portal.azure.com).
Введите Azure Cosmos DB в глобальной строке поиска.
В службах выберите Azure Cosmos DB.
В области Azure Cosmos DB выберите "Создать", а затем Azure Cosmos DB для Apache Cassandra на вкладке "Другие ".
Выберите тип учетной записи учетная запись базы данных единицы запроса (RU).

В области "Основные сведения" настройте следующие параметры и нажмите кнопку "Проверить и создать".

	Ценность
Тип рабочей нагрузки	Обучение
Подписка	Выберите подписку Azure.
Группа ресурсов	Создание новой группы ресурсов или выбор существующей группы ресурсов
Имя аккаунта	Укажите глобально уникальное имя
Зоны доступности	Отключить
Местоположение	Выбор поддерживаемого региона Azure для подписки

Подсказка

Вы можете оставить любые не указанные параметры значениями по умолчанию. Вы также можете настроить учетную запись, чтобы ограничить общую пропускную способность учетной записи до 1000 единиц запросов в секунду (ЕЗ/с) или включить бесплатный уровень для минимизации затрат.

На панели "Проверка и создание" дождитесь успешной проверки учетной записи и нажмите кнопку "Создать".
Портал автоматически переходит в область развертывания. Дождитесь завершения развертывания.
После завершения развертывания выберите "Перейти к ресурсу" , чтобы перейти к новой учетной записи API для Apache Cassandra.
В меню ресурсов выберите параметр Обозревателя данных .
В обозревателе данных выберите +Создать таблицу.

В диалоговом окне "Добавить таблицу " настройте следующие параметры и нажмите кнопку "ОК".

	Ценность
Пространство ключей	Создать
Имя пространства ключей	`cosmicworks`
Имя таблицы	`product`
Схема таблицы	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Подсказка

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

Получение учетных данных

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

Azure CLI
Портал Azure

Используйте az cosmosdb show, чтобы получить точку контакта и имя пользователя для учетной записи.
```
az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"
```
Запишите значение свойств contactPoint и username из вывода предыдущих команд. Эти свойства представляют собой контактную точку и имя пользователя , которое вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Используйте az cosmosdb keys list для получения ключей для учетной записи.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Запишите значение primaryMasterKey свойства из выходных данных предыдущих команд. Это значение свойства — это пароль , который вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.

Подготовка среды разработки

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

Начните в пустом каталоге.
Создайте модуль Go.
```
go mod init quickstart
```
github.com/apache/cassandra-gocql-driver/v2 Импортируйте пакет из Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Создайте файл main.go .
Добавьте шаблон приложения Go.
```
package main

func main() {    
}
```
Это важно

Остальные действия в этом руководстве предполагают, что вы добавляете код в функцию main .

Объектная модель

	Описание
`Cluster`	Представляет определенное подключение к кластеру
`Session`	Сущности, которые имеют специальное подключение к кластеру

Проверка подлинности клиента

Начните с проверки подлинности клиента с помощью учетных данных, собранных ранее в этом руководстве.

Откройте файл main.go в интегрированной среде разработки (IDE).
main В функции импортируйте следующие пакеты вместе с пакетомgithub.com/apache/cassandra-gocql-driver/v2:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Создайте строковые переменные для учетных данных, собранных ранее в этом руководстве. Присвойте переменным usernamepasswordи contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Настройте экземпляр PasswordAuthenticator типа с учетными данными, указанными на предыдущих шагах. Сохраните результат в переменной под названием authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Настройте экземпляр SslOptions с минимальной версией протокола Transport Layer Security (TLS) 1.2 и используйте переменную contactPoint в качестве имени серверa назначения. Сохраните результат в переменной под названием sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Создайте новую спецификацию кластера с помощью NewCluster и переменной contactPoint .
```
cluster := gocql.NewCluster(contactPoint)
```
Настройте объект спецификации кластера с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
Настройте оставшуюся часть объекта спецификации кластера с этими статическими значениями.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
Создайте новый сеанс, который подключается к кластеру с помощью CreateSession.
```
session, _ := cluster.CreateSession()
```
Настройте сеанс для вызова функции Close после завершения функции main.
```
defer session.Close()
```
Создайте объект Background контекста и сохраните его в переменной ctx .
```
ctx := context.Background()
```

Предупреждение

Полная проверка уровня транспорта (TLS) отключена в этом руководстве для упрощения проверки подлинности. Для рабочих развертываний полностью включите проверку.

Обновление-вставка данных

Затем переведите новые данные в таблицу. Upserting гарантирует, что данные создаются или заменяются соответствующим образом в зависимости от того, существуют ли те же данные в таблице.

Определите новый тип Product с полями, соответствующими таблице, созданной ранее в этом руководстве.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Подсказка

В Go вы можете создать этот тип в другом файле или создать его в конце существующего файла.

Создайте новый объект типа Product. Сохраните объект в переменной с именем product.

product := Product {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

Создайте новую строковую переменную insertQuery с языковым запросом Cassandra (CQL) для вставки новой строки данных.
```
insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`
```
Используйте функции Query и ExecContext для выполнения запроса. Передайте различные свойства переменной product в качестве параметров запроса.
```
_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)
```

Чтение данных

Затем считывайте данные, которые ранее были добавлены в таблицу.

Создайте новую строковую переменную с именем readQuery, содержащую CQL-запрос, который выбирает элементы с тем же полем id.
```
readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`
```
Создайте строковую переменную id с тем же значением, что и продукт, созданный ранее в этом руководстве.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Создайте другую переменную с именем matchedProduct , чтобы сохранить результат этой операции.
```
var matchedProduct Product
```
Используйте функции Query, Consistency, IterContext и Scan вместе, чтобы найти один элемент, соответствующий запросу, и назначить его свойства переменной matchedProduct.
```
session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)
```

Запрос данных

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

Создайте строковые переменные с именем findQuery и category с помощью запроса CQL и обязательного параметра.

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Используйте функции Query, Consistency, IterContext, и Scanner вместе для создания сканера, который может выполнять итерацию по нескольким элементам, совпадающим с запросом.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Next и Scan функции используйте для перебора результатов запроса и присвоения свойств каждого результата внутренней queriedProduct переменной.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

Запустите код

Запустите созданное приложение с помощью терминала в каталоге приложения.

go run .

Очистите ресурсы

Azure CLI
Портал Azure

Используйте az cosmosdb show, чтобы получить точку контакта и имя пользователя для учетной записи.
```
az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"
```
Запишите значение свойств contactPoint и username из вывода предыдущих команд. Эти свойства представляют собой контактную точку и имя пользователя , которое вы используете далее в этом руководстве для подключения к учетной записи с библиотекой.