O POWER BI É PARA VOCÊ

Ter visão 360º de sua empresa já é possível com
o Microsoft Power BI.

Maio 02, 2022

Como criar um aplicativo de console .NET do Azure Cosmos DB

Por Azure

Introdução à biblioteca de clientes da API do SQL do Azure Cosmos DB para .NET. Siga as etapas neste documento para instalar o pacote .NET, criar um aplicativo e experimentar o código de exemplo para operações CRUD básicas nos dados armazenados no Azure Cosmos DB.

O Azure Cosmos DB é o banco de dados NoSQL rápido da Microsoft com APIs abertas para qualquer escala. É possível usar o Azure Cosmos DB para criar e consultar rapidamente chaves/valores, documentos e bancos de dados de grafos. Use a biblioteca de clientes da API do SQL do Azure Cosmos DB para .NET para:

Criar um banco de dados e um contêiner do Azure Cosmos
Adicionar dados de exemplo ao contêiner
Consultar os dados
Excluir o banco de dados

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet)

Pré-requisitos

Assinatura do Azure – crie uma gratuitamente ou você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, sem ônus e sem compromisso.
SDK do .NET Core 2.1 ou posterior.

Configurando

Esta seção orienta a criação de uma conta do Azure Cosmos e a configuração de um projeto que usa a biblioteca de cliente da API do SQL do Azure Cosmos DB para .NET a fim de gerenciar recursos. O código de exemplo descrito neste artigo cria o banco de dados FamilyDatabase e os membros da família (cada membro da família é um item) dentro desse banco de dados. Cada membro da família tem propriedades como Id, FamilyName, FirstName, LastName, Parents, Children, Address,. A propriedade LastName é usada como a chave de partição para o contêiner.

Criar uma conta do Azure Cosmos

Se usar a opção Experimentar o Azure Cosmos DB gratuitamente para criar uma conta do Azure Cosmos, você deverá criar uma conta do Azure Cosmos DB do tipo API do SQL. Uma conta de teste do Azure Cosmos DB já foi criada para você. Você não precisa criar a conta explicitamente, portanto, você pode ignorar esta seção e ir para a próxima.

Se tiver sua própria assinatura do Azure ou tiver criado uma gratuitamente, você deverá criar uma conta do Azure Cosmos explicitamente. O código a seguir criará uma conta do Azure Cosmos com consistência de sessão. A conta é replicada no South Central US e no North Central US.

Você pode usar o Azure Cloud Shell para criar a conta do Azure Cosmos. O Azure Cloud Shell é um shell interativo, autenticado e acessível pelo navegador para o gerenciamento de recursos do Azure. Ele dá a você a flexibilidade de escolher a experiência de shell que melhor se adequa ao modo como você trabalha, seja com o Bash ou o PowerShell. Para este guia de início rápido, escolha o modo Bash. O Azure Cloud Shell também requer uma conta de armazenamento, a qual você pode criar quando solicitado.

Selecione o botão Experimentar ao lado do código a seguir, escolha o modo Bash, selecione criar uma conta de armazenamento e faça logon no Cloud Shell. Em seguida, copie e cole o código a seguir no Azure Cloud Shell e execute-o. O nome da conta do Azure Cosmos deve ser globalmente exclusivo, certifique-se de atualizar o valor mysqlapicosmosdb antes de executar o comando.

CLI do AzureCopiarExperimente


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'

# The Azure Cosmos account name must be globally unique, make sure to update the `mysqlapicosmosdb` value before you run the command
accountName='mysqlapicosmosdb'

# Create a resource group
az group create \
    --name $resourceGroupName \
    --location $location

# Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --kind GlobalDocumentDB \
    --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
    --default-consistency-level "Session" \
    --enable-multiple-write-locations true

A criação da conta do Azure Cosmos demora um pouco. Quando a operação for bem-sucedida, você verá a saída de confirmação. Após o comando ser concluído com êxito, entre no portal do Azure e verifique se a conta do Azure Cosmos com o nome especificado existe. Você pode fechar a janela de Azure Cloud Shell após a criação do recurso.

Criar um novo aplicativo .NET

Crie um novo aplicativo .NET em seu IDE ou editor preferido. Abra o prompt de comando do Windows ou uma janela do Terminal no computador local. Você executará todos os comandos nas próximas seções no prompt de comando ou no terminal. Execute o novo comando dotnet a seguir para criar um novo aplicativo com o nome todo. O parâmetro --langVersion define a propriedade LangVersion no arquivo de projeto criado.

ConsoleCopiar

dotnet new console --langVersion 7.1 -n todo

Altere o diretório para a pasta do aplicativo recém-criado. É possível criar o aplicativo com:

ConsoleCopiar

cd todo
dotnet build

A saída esperada da compilação deve ser algo como:

ConsoleCopiar

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.dll
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.Views.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Instalar pacote Azure Cosmos DB

Ainda no diretório do aplicativo, instale a biblioteca de clientes do Azure Cosmos DB para .NET Core usando o comando para adicionar pacote do dotnet.

ConsoleCopiar

dotnet add package Microsoft.Azure.Cosmos

Copiar suas credenciais da conta do Azure Cosmos no portal do Azure

O aplicativo de exemplo precisa autenticar sua conta do Azure Cosmos. Para autenticar, você deve passar as credenciais da conta do Azure Cosmos para o aplicativo. Obtenha suas credenciais da conta do Azure Cosmos seguindo estas etapas:

Entre no portal do Azure.
Navegue até a conta do Azure Cosmos.
Abra o painel Chaves e copie o URI e a CHAVE PRIMÁRIA da sua conta. Você adicionará os valores do URI e das chaves em uma variável de ambiente da próxima etapa.

Definir as variáveis de ambiente

Depois de copiar o URI e a CHAVE PRIMÁRIA da sua conta, salve-os em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela de console e execute o comando a seguir. Certifique-se de substituir os valores <Your_Azure_Cosmos_account_URI> e <Your_Azure_Cosmos_account_PRIMARY_KEY>.

Windows

ConsoleCopiar

setx EndpointUrl "<Your_Azure_Cosmos_account_URI>"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Linux

BashCopiar

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

macOS

BashCopiar

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Modelo de objeto

Antes de começar a criar o aplicativo, vamos examinar a hierarquia de recursos no Azure Cosmos DB e o modelo de objeto usado para criar e acessar esses recursos. O Azure Cosmos DB cria recursos na seguinte ordem:

Conta do Azure Cosmos
Bancos de dados
Contêineres
Itens

Para saber mais sobre a hierarquia de diferentes entidades, confira o artigo Trabalhando com bancos de dados, contêineres e itens no Azure Cosmos DB. Use as seguintes classes .NET para interagir com esses recursos:

CosmosClient – fornece a representação lógica do lado do cliente para o serviço do Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.
CreateDatabaseIfNotExistsAsync – esse método cria (se não existir) ou obtém (se já existir) um recurso de banco de dados como uma operação assíncrona.
CreateContainerIfNotExistsAsync – esse método cria (se não existir) ou obtém (se já existir) um contêiner como uma operação assíncrona. Você pode verificar o código de status da resposta para determinar se o contêiner foi criado recentemente (201) ou se um contêiner existente foi retornado (200).
CreateItemAsync – esse método cria um item dentro do contêiner.
UpsertItemAsync – esse método criará um item dentro do contêiner se ainda não existir ou substituirá o item se ele já existir.
GetItemQueryIterator – esse método cria uma consulta para itens em contêiner em um banco de dados do Azure Cosmos usando uma instrução SQL com valores parametrizados.
DeleteAsync – exclui o banco de dados especificado de sua conta Azure Cosmos. O método DeleteAsync exclui somente o banco de dados. O descarte da instância Cosmosclient deve ocorrer separadamente (o que é feito no método DeleteDatabaseAndCleanupAsync).

Exemplos de código

O código de exemplo descrito neste artigo cria um banco de dados de família em Azure Cosmos DB. O banco de dados da família contém detalhes da família, como nome, endereço, local, pais associados, filhos e animais de estimação. Antes de preencher os dados de sua conta do Azure Cosmos, defina as propriedades de um item da família. Crie uma nova classe chamada Family.cs no nível raiz do seu aplicativo de exemplo e adicione o seguinte código a ela:

C#Copiar

using Newtonsoft.Json;

namespace todo
{
    public class Family
    {
        [JsonProperty(PropertyName = "id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        // The ToString() method is used to format the output, it's used for demo purpose only. It's not required by Azure Cosmos DB
        public override string ToString()
        {
            return JsonConvert.SerializeObject(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

Adicionar usando as diretivas e definir o objeto de cliente

No diretório do projeto, abra o arquivo Program.cs em seu editor e adicione o seguinte usando as diretivas na parte superior do seu aplicativo:

C#Copiar


using System;
using System.Threading.Tasks;
using System.Configuration;
using System.Collections.Generic;
using System.Net;
using Microsoft.Azure.Cosmos;

Para Program.cs, adicione o código para ler as variáveis de ambiente que você definiu na etapa anterior. Defina os objetos CosmosClient, Database e Container. Em seguida, adicione o código ao método principal que chama o método GetStartedDemoAsync com o qual você gerencia os recursos da conta do Azure Cosmos.

C#Copiar

namespace todo
{
public class Program
{

    /// The Azure Cosmos DB endpoint for running this GetStarted sample.
    private string EndpointUrl = Environment.GetEnvironmentVariable("EndpointUrl");

    /// The primary key for the Azure DocumentDB account.
    private string PrimaryKey = Environment.GetEnvironmentVariable("PrimaryKey");

    // The Cosmos client instance
    private CosmosClient cosmosClient;

    // The database we will create
    private Database database;

    // The container we will create.
    private Container container;

    // The name of the database and container we will create
    private string databaseId = "FamilyDatabase";
    private string containerId = "FamilyContainer";

    public static async Task Main(string[] args)
    {
       try
       {
           Console.WriteLine("Beginning operations...\n");
           Program p = new Program();
           await p.GetStartedDemoAsync();

        }
        catch (CosmosException de)
        {
           Exception baseException = de.GetBaseException();
           Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
}
}

Criar um banco de dados

Defina o método CreateDatabaseAsync dentro da classe program.cs. Esse método cria o FamilyDatabase, caso ainda não exista.

C#Copiar

private async Task CreateDatabaseAsync()
{
    // Create a new database
    this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
    Console.WriteLine("Created Database: {0}\n", this.database.Id);
}

Criar um contêiner

Defina o método CreateContainerAsync dentro da classe program.cs. Esse método cria o FamilyContainer, caso ainda não exista.

C#Copiar

/// Create the container if it does not exist. 
/// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
private async Task CreateContainerAsync()
{
    // Create a new container
    this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", this.container.Id);
}

Criar um item

Crie um item de família adicionando o método AddItemsToContainerAsync com o código a seguir. Você pode usar os métodos CreateItemAsync ou UpsertItemAsync para criar um item:

C#Copiar

private async Task AddItemsToContainerAsync()
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
           new Parent { FirstName = "Thomas" },
           new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
           new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
    };

    try
    {
        // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen".
        ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
        // Note that after creating the item, we can access the body of the item with the Resource property of the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
        Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
    }
    catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
    {
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamily.Id);                
    }
}

Consultar os itens

Depois de inserir um item, você pode executar uma consulta para obter os detalhes da família "Martins". O código a seguir mostra como executar a consulta usando diretamente a consulta SQL. A consulta SQL para obter os detalhes da família "Martins" é: SELECT * FROM c WHERE c.LastName = 'Andersen'. Defina o método QueryItemsAsync dentro da classe program.cs e adicione o seguinte código:

C#Copiar

private async Task QueryItemsAsync()
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
    FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);

    List<Family> families = new List<Family>();

    while (queryResultSetIterator.HasMoreResults)
    {
        FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
        foreach (Family family in currentResultSet)
        {
            families.Add(family);
            Console.WriteLine("\tRead {0}\n", family);
        }
    }
}

Excluir o banco de dados

Por fim, você pode excluir o banco de dados adicionando o método DeleteDatabaseAndCleanupAsync com o seguinte código:

C#Copiar

private async Task DeleteDatabaseAndCleanupAsync()
{
   DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
   // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();

   Console.WriteLine("Deleted Database: {0}\n", this.databaseId);

   //Dispose of CosmosClient
    this.cosmosClient.Dispose();
}

Executar as operações CRUD

Depois de definir todos os métodos necessários, execute-os com o método GetStartedDemoAsync. O método DeleteDatabaseAndCleanupAsync foi retirado do comentário deste código porque você não verá nenhum recurso se esse método for executado. Você pode remover os comentários após validar que seus recursos do Azure Cosmos DB foram criados no portal do Azure.

C#Copiar

public async Task GetStartedDemoAsync()
{
    // Create a new instance of the Cosmos Client
    this.cosmosClient = new CosmosClient(EndpointUrl, PrimaryKey);
    await this.CreateDatabaseAsync();
    await this.CreateContainerAsync();
    await this.AddItemsToContainerAsync();
    await this.QueryItemsAsync();
}

Depois de adicionar todos os métodos necessários, salve o arquivo Program.cs.

Executar o código

Em seguida, compile e execute o aplicativo para criar os recursos do Azure Cosmos DB. Abra uma nova janela de prompt de comando, não utilize a mesma instância usada para definir as variáveis de ambiente, porque as variáveis de ambiente não estão definidas na janela aberta no momento. Será necessário abrir um novo prompt de comando para ver as atualizações.

ConsoleCopiar

dotnet build

ConsoleCopiar

dotnet run

A saída a seguir é gerada quando você executa o aplicativo. Você também pode entrar no portal do Azure e validar que os recursos foram criados:

ConsoleCopiar

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.62 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

End of demo, press any key to exit.

Você pode validar que os dados foram criados entrando no portal do Azure e olhando os itens necessários em sua conta do Azure Cosmos.

Limpar os recursos

Quando não for mais necessária, você poderá usar o CLI do Azure ou o Azure PowerShell para remover a conta do Azure Cosmos e o grupo de recursos correspondente. O comando a seguir mostra como excluir o grupo de recursos usando o CLI do Azure:

CLI do AzureCopiar

az group delete -g "myResourceGroup"

Próximas etapas

Neste início rápido, você aprendeu a criar uma conta do Azure Cosmos, como criar um banco de dados e um contêiner usando o .NET Core. Agora é possível importar dados adicionais para sua conta do Azure Cosmos usando as instruções do artigo abaixo.

Tentando fazer um planejamento de capacidade para uma migração para o Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.

Se você sabe apenas o número de vCores e servidores no cluster de banco de dados existente, leia sobre como estimar unidades de solicitação com vCores ou vCPUs
Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB

Importar dados no Azure Cosmos DB

Tags: microsoft Azure Azure Cosmos DB