Поделиться через

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

  • Применяется к: ✅ NoSQL

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

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

Предпосылки

  • Azure Developer CLI (Интерфейс командной строки для разработчиков Azure)
  • 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"
)

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

Имя Description
CosmosClient Этот класс является основным клиентским классом и используется для управления метаданными или базами данных на уровне учетной записи.
CosmosDatabase Этот класс представляет базу данных в учетной записи.
CosmosContainer Этот класс в первую очередь используется для выполнения операций чтения, обновления и удаления как для контейнера, так и для элементов, находящихся внутри него.
PartitionKey Этот класс представляет логический ключ раздела. Этот класс необходим для многих распространенных операций и запросов.

Примеры кода

Образец кода в шаблоне использует базу данных с именем 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

Связанный контент

  • Last updated on