Краткое руководство. Библиотека Azure Cosmos DB для NoSQL для Go
ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL
Начало работы с клиентской библиотекой Azure Cosmos DB для NoSQL для Go для запроса данных в контейнерах и выполнение общих операций с отдельными элементами. Выполните следующие действия, чтобы развернуть минимальное решение в вашей среде с помощью Интерфейса командной строки разработчика Azure.
Справочная документация по API: пакет исходного кода библиотеки | исходного кода | (Go) | Azure Developer CLI
Необходимые компоненты
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Учетная запись GitHub
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Интерфейс командной строки разработчика Azure
- Docker Desktop
Установка
Разверните контейнер разработки этого проекта в вашей среде. Затем используйте интерфейс командной строки разработчика Azure (azd
) для создания учетной записи Azure Cosmos DB для NoSQL и развертывания контейнерного примера приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.
Внимание
Учетные записи GitHub включают право на хранение и основные часы без затрат. Дополнительные сведения см . в разделе о хранилище и основных часах для учетных записей GitHub.
Откройте терминал в корневом каталоге проекта.
Проверка подлинности в интерфейсе командной строки разработчика Azure с помощью
azd auth login
. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.azd auth login
Используется
azd init
для инициализации проекта.azd init
Во время инициализации настройте уникальное имя среды.
Совет
Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать
msdocs-cosmos-db
.Разверните учетную запись Azure Cosmos DB с помощью
azd up
. Шаблоны Bicep также развертывают пример веб-приложения.azd up
В процессе подготовки выберите подписку и нужное расположение. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.
После завершения подготовки ресурсов 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.
Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.
Установка клиентской библиотеки
Клиентская библиотека доступна через Go в качестве azcosmos
пакета.
Откройте терминал и перейдите в папку
/src
.cd ./src
Если пакет еще не установлен, установите
azcosmos
его с помощьюgo install
.go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
Кроме того, установите
azidentity
пакет, если он еще не установлен.go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
Откройте и просмотрите файл src/go.mod , чтобы убедиться, что
github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
существуют иgithub.com/Azure/azure-sdk-for-go/sdk/azidentity
записи.
Объектная модель
Имя | Описание |
---|---|
CosmosClient |
Этот класс является основным клиентским классом и используется для управления метаданными или базами данных на уровне учетной записи. |
CosmosDatabase |
Этот класс представляет базу данных в учетной записи. |
CosmosContainer |
Этот класс в основном используется для выполнения операций чтения, обновления и удаления в контейнере или элементов, хранящихся в контейнере. |
PartitionKey |
Этот класс представляет ключ логического раздела. Этот класс необходим для многих распространенных операций и запросов. |
Примеры кода
- аутентификация клиента;
- Получение базы данных
- Получение контейнера
- Создание элемента
- Получение элемента
- Запрос элементов
Пример кода в шаблоне использует базу данных с именем cosmicworks
и контейнером products
. Контейнер products
содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category
свойство в качестве ключа логического раздела.
аутентификация клиента;
Запросы приложений к большинству служб Azure должны быть авторизованы. DefaultAzureCredential
Используйте тип в качестве предпочтительного способа реализации подключения без пароля между приложениями и Azure Cosmos DB для NoSQL. DefaultAzureCredential
поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения.
Внимание
Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности в службе базы данных. DefaultAzureCredential
предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля без риска хранения ключей.
В этом примере создается новый экземпляр CosmosClient
использования azcosmos.NewClient
и проверки подлинности с помощью экземпляра DefaultAzureCredential
.
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
return err
}
clientOptions := azcosmos.ClientOptions{
EnableContentResponseOnWrite: true,
}
client, err := azcosmos.NewClient(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
. Этот метод "upserts" элемент фактически заменяет элемент, если он уже существует.
item := Item {
Id: "70b63682-b93a-4c77-aad2-65501347265f",
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 := "70b63682-b93a-4c77-aad2-65501347265f"
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
для определения наличия каких-либо результатов в начале каждого цикла.
context := context.TODO()
items := []Item{}
requestCharge := float32(0)
for pager.More() {
response, err := pager.NextPage(context)
if err != nil {
return err
}
requestCharge += response.RequestCharge
for _, bytes := range response.Items {
item := Item{}
err := json.Unmarshal(bytes, &item)
if err != nil {
return err
}
items = append(items, item)
}
}
Очистка ресурсов
Если вам больше не нужен пример приложения или ресурсов, удалите соответствующее развертывание и все ресурсы.
azd down
В GitHub Codespaces удалите работающее пространство кода, чтобы максимально увеличить объем хранилища и основных прав.
Связанный контент
- Краткое руководство по .NET
- Краткое руководство по JavaScript/Node.js
- Краткое руководство для Java
- Краткое руководство по Python