Explorar o SDK do Microsoft .NET v3 para Azure Cosmos DB

  • 3 minutos

Esta unidade se concentra no SDK v3 do .NET do Azure Cosmos DB para API para NoSQL. (Pacote NuGet Microsoft.Azure.Cosmos.) Caso você já conheça a versão anterior do SDK do .NET, talvez esteja familiarizado com a coleção de termos e o documento.

O repositório de GitHub azure-cosmos-dotnet-v3 inclui as soluções de exemplo .NET mais recentes. Você usa essas soluções para executar CRUD (criar, ler, atualizar e excluir) e outras operações comuns nos recursos Azure Cosmos DB.

Como o Azure Cosmos DB dá suporte a vários modelos de API, a versão 3 do SDK do .NET usa os termos genéricos contêiner e item. Um contêiner pode ser uma coleção, um grafo ou uma tabela. Um item pode ser um documento, uma borda/vértice ou uma linha e é o conteúdo dentro de um contêiner.

Veja a seguir exemplos que mostram algumas das principais operações que você deve conhecer. Para obter mais exemplos, visite o link do GitHub mostrado anteriormente. Todos os exemplos abaixo usam a versão assíncrona dos métodos.

CosmosClient

Cria um CosmosClient com uma cadeia de conexão. CosmosClient é thread-safe. A recomendação é manter uma só instância de CosmosClient durante todo o tempo de vida do aplicativo, o que permite a eficiência do gerenciamento e do desempenho da conexão.

CosmosClient client = new CosmosClient(endpoint, key);

Exemplos de banco de dados

Criar um banco de dados

O método CosmosClient.CreateDatabaseAsync lança uma exceção se já existir um banco de dados com o mesmo nome.

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

O CosmosClient.CreateDatabaseIfNotExistsAsync verifica se um banco de dados existe e, quando não existe, cria um. Somente a id do banco de dados é usada para verificar se há um banco de dados existente.

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

Ler um banco de dados pela ID

Lê um banco de dados do serviço Azure Cosmos DB como uma operação assíncrona.

DatabaseResponse readResponse = await database.ReadAsync();

Excluir um banco de dados

Exclua um banco de dados como uma operação assíncrona.

await database.DeleteAsync();

Exemplos de contêiner

Criar um contêiner

O método Database.CreateContainerIfNotExistsAsync verifica se um contêiner existe e, quando não existe, cria um. Somente a id do contêiner é usada para verificar se há um contêiner existente.

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

Obter um contêiner por ID

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

Excluir um contêiner

Exclua um contêiner como uma operação assíncrona.

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

Exemplos de item

Criar um item

Use o método Container.CreateItemAsync para criar um item. O método requer um objeto JSON serializável que precisa conter uma propriedade id e uma partitionKey.

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

Ler um item

Use o método Container.ReadItemAsync para ler um item. O método requer o tipo para serializar o item para junto com uma propriedade id e um partitionKey.

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

Consultar um item

O método Container.GetItemQueryIterator cria uma consulta para itens em um contêiner em um banco de dados Azure Cosmos usando uma instrução SQL com valores parametrizados. Ele retorna um 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
    });

Outros recursos