Краткое руководство. Использование Azure Cosmos DB для NoSQL с пакетом SDK Azure для Go

В этом кратком руководстве описано, как развернуть базовое приложение Azure Cosmos DB для NoSQL с помощью пакета SDK Azure для Go. Azure Cosmos DB для NoSQL — это хранилище данных без схемы, позволяющее приложениям хранить неструктурированные данные в облаке. Запрос данных в контейнерах и выполнение общих операций с отдельными элементами с помощью пакета SDK Azure для Go.

Справочная документация по API: пакет исходного кода библиотеки | исходного кода | (Go) | Azure Developer CLI

• Azure Developer CLI
• Docker Desktop
• Go 1.21 или более поздней версии

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

Используйте интерфейс командной строки разработчика Azure (azd) для создания учетной записи Azure Cosmos DB для NoSQL и развертывания контейнерного примера приложения. Пример приложения использует клиентскую библиотеку для управления, создания, чтения и выполнения запросов к образцам данных.

1. Откройте терминал в пустом каталоге.

2. Если вы еще не прошли проверку подлинности, выполните проверку подлинности в интерфейсе командной строки разработчика Azure с помощью azd auth login. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.

   azd auth login
   

3. Используется azd init для инициализации проекта.

   azd init --template cosmos-db-nosql-go-quickstart
   

4. Во время инициализации настройте уникальное имя среды.

5. Разверните учетную запись Azure Cosmos DB с помощью azd up. Шаблоны Bicep также развертывают пример веб-приложения.

   azd up
   

6. В процессе подготовки выберите подписку, требуемое расположение и целевую группу ресурсов. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.

7. После завершения подготовки ресурсов Azure в выходные данные будет включен URL-адрес работающего веб-приложения.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

Клиентская библиотека доступна через Go в качестве azcosmos пакета.

1. Откройте терминал и перейдите в папку /src .

   cd ./src
   

2. Если пакет еще не установлен, установите azcosmos его с помощью go install.

   go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
   

3. Кроме того, установите azidentity пакет, если он еще не установлен.

   go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

4. Откройте и просмотрите файл src/go.mod, чтобы убедиться, что обе записи github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos и github.com/Azure/azure-sdk-for-go/sdk/azidentity существуют.

github.com/Azure/azure-sdk-for-go/sdk/azidentity Импортируйте и github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos пакеты в код приложения.

import (
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

• аутентификация клиента;
• Получение базы данных
• Возьмите контейнер
• Создание элемента
• Получить элемент
• Запрос элементов

Пример кода в шаблоне использует базу данных с именем cosmicworks и контейнером products. Контейнер products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category свойство в качестве ключа логического раздела.

В этом примере создается новый экземпляр CosmosClient с использованием azcosmos.NewClient и аутентификацией с помощью экземпляра DefaultAzureCredential.

credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return err
}

clientOptions := azcosmos.ClientOptions{
    EnableContentResponseOnWrite: true,
}

client, err := azcosmos.NewClient("<azure-cosmos-db-nosql-account-endpoint>", credential, &clientOptions)
if err != nil {
    return err
}

Используется client.NewDatabase для извлечения существующей базы данных с именем cosmicworks.

database, err := client.NewDatabase("cosmicworks")
if err != nil {
    return err
}

Получение существующего products контейнера с помощью database.NewContainer.

container, err := database.NewContainer("products")
if err != nil {
    return err
}

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

type Item struct {
  Id        string  `json:"id"`
  Category  string  `json:"category"`
  Name      string  `json:"name"`
  Quantity  int     `json:"quantity"`
  Price     float32 `json:"price"`
  Clearance bool    `json:"clearance"`
}

Создайте элемент в контейнере с помощью container.UpsertItem. Этот метод осуществляет операцию "обновления или вставки" элемента, фактически заменяя его, если он уже существует.

item := Item {
    Id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    Category:  "gear-surf-surfboards",
    Name:      "Yamba Surfboard",
    Quantity:  12,
    Price:     850.00,
    Clearance: false,
}

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

bytes, err := json.Marshal(item)
if err != nil {
    return err
}

response, err := container.UpsertItem(context, partitionKey, bytes, nil)
if err != nil {
    return err
}

Выполните операцию точечного чтения с помощью полей уникального идентификатора (id) и ключа раздела. Используйте container.ReadItem, чтобы эффективно извлечь определённый элемент.

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

itemId := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

response, err := container.ReadItem(context, partitionKey, itemId, nil)
if err != nil {
    return err
}

if response.RawResponse.StatusCode == 200 {
    read_item := Item{}
    err := json.Unmarshal(response.Value, &read_item)
    if err != nil {
        return err
    }
}

Выполнение запроса по нескольким элементам в контейнере с помощью container.NewQueryItemsPager. Найдите все элементы в указанной категории с помощью этого параметризованного запроса:

SELECT * FROM products p WHERE p.category = @category

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

query := "SELECT * FROM products p WHERE p.category = @category"

queryOptions := azcosmos.QueryOptions{
    QueryParameters: []azcosmos.QueryParameter{
        {Name: "@category", Value: "gear-surf-surfboards"},
    },
}

pager := container.NewQueryItemsPager(query, partitionKey, &queryOptions)

Анализ результатов запроса с разбивкой на страницы путем цикла по каждой странице результатов с помощью pager.NextPage. Используйте pager.More для определения, остались ли результаты в начале каждого цикла.

items := []Item{}

for pager.More() {
    response, err := pager.NextPage(context.TODO())
    if err != nil {
        return err
    }

    for _, bytes := range response.Items {
        item := Item{}
        err := json.Unmarshal(bytes, &item)
        if err != nil {
            return err
        }
        items = append(items, item)
    }
}

Используйте расширение Visual Studio Code для Azure Cosmos DB для изучения данных NoSQL. В том числе и не ограничиваясь следующим, вы можете выполнять основные операции с базой данных:

• Выполнение запросов с помощью альбома вырезок или редактора запросов
• Изменение, обновление, создание и удаление элементов
• Импорт массовых данных из других источников
• Управление базами данных и контейнерами

Для получения дополнительной информации см. как использовать расширение Visual Studio Code для изучения Azure Cosmos DB для NoSQL данных.

Если вам больше не нужен пример приложения или ресурсов, удалите соответствующее развертывание и все ресурсы.

azd down

• Краткое руководство по .NET
• Краткое руководство по Node.js
• Краткое руководство для Java
• Краткое руководство по Python
• Краткое руководство по Rust