Введение в пакет SDK для Microsoft .NET версии 3 для Azure Cosmos DB

  • 3 мин

В этом уроке основное внимание уделяется пакету SDK для .NET для Azure Cosmos DB версии 3 для API для NoSQL. (Пакет NuGet Microsoft.Azure.Cosmos .) Если вы знакомы с предыдущей версией пакета SDK для .NET, вы можете ознакомиться с коллекцией терминов и документами.

Репозиторий GitHub azure-cosmos-dotnet-v3 содержит новейшие примеры решений для .NET. Эти решения можно использовать для выполнения операций CRUD (создание, чтение, обновление и удаление) и других распространенных операций с ресурсами Azure Cosmos DB.

Так как Azure Cosmos DB поддерживает несколько моделей API, версия 3 пакета SDK для .NET использует универсальный контейнер терминов и элемент. Контейнер может быть коллекцией, графом или таблицей. Элемент может быть документом, ребром или вершиной либо строкой, и он содержится внутри контейнера.

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

CosmosClient

Создает новый объект CosmosClient со строкой подключения. CosmosClient является потокобезопасным. Рекомендуется поддерживать один экземпляр CosmosClient в течение всего времени существования приложения, который обеспечивает эффективное управление подключениями и производительность.

CosmosClient client = new CosmosClient(endpoint, key);

Примеры баз данных

Создание базы данных

Метод CosmosClient.CreateDatabaseAsync создает исключение, если база данных с тем же именем уже существует.

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

Метод CosmosClient.CreateDatabaseIfNotExistsAsync проверяет, существует ли база данных, и, если нет, создает ее. Для проверки наличия существующей базы данных используется только база id данных.

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

Чтение базы данных по идентификатору

Считывает базу данных из службы Azure Cosmos DB как асинхронную операцию.

DatabaseResponse readResponse = await database.ReadAsync();

Удаление базы данных

Удаление базы данных с помощью асинхронной операции.

await database.DeleteAsync();

Примеры контейнеров

Создание контейнера

Метод Database.CreateContainerIfNotExistsAsync проверяет, существует ли контейнер, и, если нет, он создает его. Только контейнер id используется для проверки наличия существующего контейнера.

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

Получение контейнера по идентификатору

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

Удаление контейнера

Удаление контейнера с помощью асинхронной операции.

await database.GetContainer(containerId).DeleteContainerAsync();

Примеры элементов

Создание элемента

Используйте метод Container.CreateItemAsync для создания элемента. Для вызова этого метода требуется сериализуемый объект JSON, который должен иметь свойство id, и объект partitionKey.

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

Чтение элемента

Используйте метод Container.ReadItemAsync для чтения элемента. Этому методу требуется передать тип для сериализации элемента, а также свойство id и объект partitionKey.

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

Запрос элемента

Метод Container.GetItemQueryIterator создает запрос элементов в контейнере, находящемся в базе данных Azure Cosmos, используя инструкцию SQL с параметризованными значениями. В результате возвратится FeedIterator.

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

Другие ресурсы