Início Rápido: biblioteca de cliente do Azure Cosmos DB for NoSQL para .NET

  • Artigo

APLICA-SE A: NoSQL

Comece com a biblioteca de clientes do Azure Cosmos DB para .NET para criar bancos de dados, contêineres e itens em sua conta. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Observação

Os trechos de código de exemplo estão disponíveis no GitHub como um projeto .NET.

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

Pré-requisitos

Verificação de pré-requisitos

  • Em um terminal ou janela de comando, executedotnet --version para verificar se o .NET SDK é a versão 6.0 ou posterior.
  • Execute az --version (CLI do Azure) ou Get-Module -ListAvailable AzureRM (Azure PowerShell) para verificar se você tem as ferramentas de linha de comando apropriadas do Azure instaladas.

Configurando

Esta seção orienta a criação de uma conta do Azure Cosmos DB e a configuração de um projeto que usa a biblioteca de cliente do Azure Cosmos DB for NoSQL para .NET a fim de gerenciar recursos.

Criar uma conta do Azure Cosmos DB

Dica

Nenhuma assinatura do Azure? Você pode experimentar o Azure Cosmos DB gratuitamente sem necessidade de cartão de crédito. Se você criar uma conta usando a avaliação gratuita, poderá pular para a seção Criar um aplicativo .NET.

Este guia de início rápido criará uma conta do Azure Cosmos DB usando a API para NoSQL.

Dica

Para este início rápido, recomendamos usar o nome do grupo de recursos msdocs-cosmos-quickstart-rg.

  1. Entre no portal do Azure.

  2. No menu do portal do Azure ou na Home page, selecione Criar um recurso.

  3. Na página Novo, pesquise pelo Azure Cosmos DB e selecione-o.

  4. Na página da opção Selecionar API, clique na opção Criar da seção NoSQL. O Azure Cosmos DB tem seis APIs: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin e Table. Saiba mais sobre a API para NoSQL.

    Captura de tela da página Selecionar uma opção de API para o Azure Cosmos DB.

  5. Na página Criar conta do Azure Cosmos DB, insira as seguintes informações:

    Configuração Valor Descrição
    Subscription Nome da assinatura Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.
    Grupo de recursos Nome do grupo de recursos Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.
    Nome da Conta Um nome exclusivo Insira um nome para identificar a conta do Azure Cosmos. O nome será usado como parte de um nome de domínio totalmente qualificado (FQDN) com um sufixo de documents.azure.com, portanto, o nome deve ser globalmente exclusivo. O nome pode conter apenas letras minúsculas, números e o caractere de hífen (-). O nome também deve ter entre 3 e 44 caracteres.
    Location A região mais próxima dos usuários Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.
    Modo de capacidade Taxa de transferência provisionada ou sem servidor Selecione Taxa de transferência provisionada para criar uma conta no modo taxa de transferência provisionada. Selecione Sem servidor para criar uma conta no modo sem servidor.
    Aplicar o desconto por nível gratuito do Azure Cosmos DB Aplicar ou Não aplicar Habilite a camada gratuita do Azure Cosmos DB. Com a camada gratuita do Azure Cosmos DB, você recebe os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente em uma conta. Saiba mais sobre o nível gratuito.

    Observação

    Você pode ter no máximo uma conta do nível gratuito do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se você não vir a opção de aplicar o desconto por nível gratuito, significa que outra conta da assinatura já foi habilitada com o nível gratuito.

    Captura de tela da página da nova conta para a API para NoSQL.

  6. Selecione Examinar + criar.

  7. Examine as configurações fornecidas e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída antes de continuar.

  8. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.

    Captura de tela da página de implantação de um recurso da API para NoSQL.

  9. Na página da conta da API para NoSQL, selecione a opção do menu de navegação Chaves.

    Captura de tela de uma página de conta da API para NoSQL. A opção Chaves está realçada no menu de navegação.

  10. Registre os valores dos campos do URI e da PRIMARY KEY. Você usará esses valores em uma etapa posterior.

    Captura de tela da página Chaves com várias credenciais para uma conta da API para NoSQL.

Criar um novo aplicativo .NET

Crie um novo aplicativo .NET em uma pasta vazia usando seu terminal de preferência. Use o dotnet new comando que especifica o modelo de console .

dotnet new console

Instalar o pacote

Adicione o pacote NuGet Microsoft.Azure.Cosmos ao projeto .NET. Use o dotnet add package comando que especifica o nome do pacote NuGet.

dotnet add package Microsoft.Azure.Cosmos

Compile o projeto com o dotnet buildcomando.

dotnet build

Verifique se o build foi bem-sucedido sem erros. A saída esperada da compilação deve ser algo como:

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

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

Configurar variáveis de ambiente

Para usar os valores do URI e do PRIMARY KEY no código, persista-os para novas variáveis de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, use seu terminal preferido para executar os seguintes comandos:

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<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. O Azure Cosmos DB tem um modelo de objeto específico usado para criar e acessar recursos. O Azure Cosmos DB cria recursos em uma hierarquia que consiste em contas, bancos de dados, contêineres e itens.

Diagrama da hierarquia do Azure Cosmos DB, incluindo contas, bancos de dados, contêineres e itens.

Para obter mais informações sobre a hierarquia de diferentes recursos, consulte trabalhando com bancos de dados, contêineres e itens no Azure Cosmos DB.

Você usará 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.
  • Database - Esta classe é uma referência a um banco de dados que pode ou não existir no serviço ainda. O banco de dados é validado no lado do servidor quando você tenta acessá-lo ou executa uma operação nele.
  • Container - Essa classe é uma referência a um contêiner que também pode não existir no serviço ainda. O contêiner é validado no lado do servidor quando você tenta trabalhar com ele.
  • QueryDefinition - Essa classe representa uma consulta SQL e todos os parâmetros de consulta.
  • FeedIterator<> - Essa classe representa um iterador que pode rastrear a página atual de resultados e obter uma nova página de resultados.
  • FeedResponse<> - Essa classe representa uma única página de respostas do iterador. Esse tipo pode ser iterado usando um foreach loop.

Exemplos de código

O código de exemplo descrito neste artigo cria um banco de dados chamado cosmicworks com um contêiner chamadoproducts. A products tabela foi projetada para conter detalhes do produto, como nome, categoria, quantidade e um indicador de venda. Cada produto também contém um identificador exclusivo.

Para este código de amostra, o contêiner usará a categoria como uma chave de partição lógica.

Autenticar o cliente

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes de Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no seu código.

Você também pode autorizar solicitações para serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local não seguro. Qualquer pessoa que tenha acesso à senha ou à chave secreta poderá se autenticar. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma classe fornecida pela biblioteca de clientes da Identidade do Azure para .NET. Para saber mais sobre DefaultAzureCredential, confira a Visão geral do DefaultAzureCredential. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Por exemplo, seu aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio ao desenvolver localmente e, em seguida, usar uma identidade gerenciada depois de ser implantado no Azure. Nenhuma alteração de código é necessária para essa transição.

Ao desenvolver localmente com a autenticação sem senha, verifique se a conta de usuário que se conecta ao Cosmos DB recebe uma função com as permissões corretas para executar operações de dados. Atualmente, o Azure Cosmos DB for NoSQL não inclui funções internas para operações de dados, mas você pode criar suas próprias usando a CLI do Azure ou o PowerShell.

As funções consistem em uma coleção de permissões ou ações que um usuário tem permissão para executar, como leitura, gravação e exclusão. Você pode ler mais sobre como configurar o RBAC (controle de acesso baseado em função) na documentação de configuração de segurança do Cosmos DB.

Criar a função personalizada

  1. Crie uma função usando o comando az role definition create. Passe o nome da conta e o grupo de recursos do Cosmos DB, seguido por um corpo de JSON que define a função personalizada. O exemplo a seguir cria uma função chamada PasswordlessReadWrite com permissões para ler e gravar itens em contêineres do Cosmos DB. A função também tem o escopo definido para o nível da conta usando /.

    az cosmosdb sql role definition create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --body '{
    "RoleName": "PasswordlessReadWrite",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}'

  2. Quando o comando for concluído, copie o valor da ID do campo name e cole-o em algum lugar para uso posterior.

  3. Atribua a função que você criou à conta de usuário ou à entidade de serviço que se conectará ao Cosmos DB. Durante o desenvolvimento local, essa geralmente será sua própria conta que está conectada a uma ferramenta de desenvolvimento, como o Visual Studio ou a CLI do Azure. Recupere os detalhes de sua conta usando o comando az ad user.

    az ad user show --id "<your-email-address>"

  4. Copie o valor da propriedade id dos resultados e cole-o em algum lugar para uso posterior.

  5. Atribua a função personalizada que você criou à sua conta de usuário por meio do comando az cosmosdb sql role assignment create e as IDs copiadas anteriormente.

    az cosmosdb sql role assignment create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --scope "/" \
    --principal-id <your-user-id> \
    --role-definition-id <your-custom-role-id>

Autenticar usando DefaultAzureCredential

Para desenvolvimento local, você deve estar autenticado com a mesma conta do Azure AD à qual a função foi atribuída. Você pode autenticar por meio de ferramentas de desenvolvimento populares, como a CLI do Azure ou o Azure PowerShell. As ferramentas de desenvolvimento com as quais você pode autenticar variam entre os idiomas.

Entre no Azure por meio da CLI do Azure usando o seguinte comando:

az login

Você pode autenticar no Cosmos DB for NoSQL usando DefaultAzureCredential ao adicianar o pacote NuGet Azure.Identity ao seu aplicativo. DefaultAzureCredential descobrirá e usará automaticamente a conta com a qual você entrou na etapa anterior.

dotnet add package Azure.Identity

No diretório do projeto, abra o arquivo Program.cs. No editor, adicione o uso de diretivas para Microsoft.Azure.Cosmos e namespaces Azure.Identity.

using Microsoft.Azure.Cosmos;
using Azure.Identity;

Defina uma nova instância da classe CosmosClient usando o construtor e Environment.GetEnvironmentVariable para ler a variável de ambiente COSMOS_ENDPOINT que você criou anteriormente.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
    tokenCredential: new DefaultAzureCredential()
);

Para obter mais informações sobre diferentes maneiras de criar uma instância CosmosClient, consulte Introdução ao Azure Cosmos DB for NoSQL e .NET .

Criar e consultar o banco de dados

Em seguida, você criará um banco de dados e um contêiner para armazenar produtos e executar consultas para inserir e ler esses itens.

As bibliotecas de cliente Microsoft.Azure.Cosmos permitem que você execute operações de dados usando o RBAC do Azure. No entanto, para autenticar operações de gerenciamento, como criar e excluir bancos de dados, você deve usar o RBAC por meio de uma das seguintes opções:

A abordagem da CLI do Azure é usada neste exemplo. Use os comandos az cosmosdb sql database create e az cosmosdb sql container create para criar um banco de dados e um contêiner NoSQL do Cosmos DB.

# Create a SQL API database
az cosmosdb sql database create 
    --account-name msdocs-cosmos-nosql
    --resource-group msdocs
    --name cosmicworks

# Create a SQL API container
az cosmosdb sql container create
    --account-name msdocs-cosmos-nosql 
    --resource-group msdocs
    --database-name cosmicworks
    --name products

Depois que os recursos forem criados, use classes das bibliotecas de cliente Microsoft.Azure.Cosmos para se conectar e consultar o banco de dados.

Obter o banco de dados

Usar o método CosmosClient.GetDatabase retornará uma referência ao banco de dados especificado.

// Database reference with creation if it does not already exist
Database database = client.GetDatabase(id: "cosmicworks");

Console.WriteLine($"New database:\t{database.Id}");

Obter o contêiner

O método Database.GetContainer retornará uma referência ao contêiner especificado.

// Container reference with creation if it does not alredy exist
Container container = database.GetContainer(id: "products");

Console.WriteLine($"New container:\t{container.Id}");

Criar um item

A maneira mais fácil de criar um novo item em um contêiner é primeiro criar uma classe C# ou tipo de registro com todos os membros que você deseja serializar em JSON. Neste exemplo, o registro C# tem um identificador exclusivo, um campo categoryId para a chave de partição e campos extra categoryName, nome, quantidade e venda.

// C# record representing an item in the container
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string name,
    int quantity,
    bool sale
);

Crie um item no contêiner chamando Container.CreateItemAsync.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    categoryName: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.CreateItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");

Para obter mais informações sobre como criar, executar upsert ou substituir itens, consulte Criar um item no Azure Cosmos DB for NoSQL usando .NET.

Obter um item

No Azure Cosmos DB, você pode executar uma operação de leitura de ponto usando o identificador exclusivo (id) e os campos de chave de partição. No SDK, chameContainer.ReadItemAsync<> a passagem de ambos os valores para retornar uma instância desserializada do seu tipo C#.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Para obter mais informações sobre como ler itens e analisar a resposta, consulte Ler um item no Azure Cosmos DB for NoSQL usando o .NET.

Itens de consulta

Depois de inserir um item, você pode executar uma consulta para obter todos os itens que correspondem a um filtro específico. Este exemplo executa a consulta SQL: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". Este exemplo usa o tipo QueryDefinition e uma expressão de consulta parametrizada para o filtro de chave de partição. Depois que a consulta for definida, chame Container.GetItemQueryIterator<> para obter um iterador de resultado que gerenciará as páginas de resultados. Em seguida, use uma combinação de while e foreach loops para recuperar páginas de resultados e, em seguida, iterar sobre os itens individuais.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
    .WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Executar o código

Este aplicativo cria um banco de dados e um contêiner da API para NoSQL. O exemplo cria um item e lê exatamente o mesmo item de volta. Por fim, o exemplo emite uma consulta que só deve retornar esse único item. A cada etapa, o exemplo gera metadados para o console sobre as etapas executadas.

Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e execute o aplicativo.

dotnet run

A saída do aplicativo deve ser semelhante a este exemplo:

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Limpar os recursos

Quando a conta da API para NoSQL não for mais necessária, exclua o grupo de recursos correspondente.

  1. Navegue até o grupo de recursos que você criou anteriormente no portal do Azure.

    Dica

    Neste início rápido, recomendamos o nome msdocs-cosmos-quickstart-rg.

  2. Selecione Excluir grupo de recursos.

    Captura de tela da opção Excluir grupo de recursos na barra de navegação de um grupo de recursos.

  3. Na caixa de diálogo Tem certeza de que deseja excluir, insira o nome do grupo de recursos e selecione Excluir.

    Captura de tela da página de confirmação de exclusão de um grupo de recursos.

Próximas etapas

Neste início rápido, você aprendeu como criar uma conta do Azure Cosmos DB for NoSQL, criar um banco de dados e criar um contêiner usando o SDK do .NET. Agora você pode se aprofundar em um tutorial em que gerencia seus recursos e dados do Azure Cosmos DB for NoSQL usando um aplicativo de console .NET.

Tutorial: Desenvolver um aplicativo de console do .NET com o Azure Cosmos DB for NoSQL