Quickstart: Azure Cosmos DB para biblioteca de clientes NoSQL para .NET

APLICA-SE A: NoSQL

Começa com a biblioteca de clientes Azure Cosmos DB para .NET para criar bases de dados, contentores e itens dentro da tua conta. Siga estes passos para instalar a embalagem e experimente o código de exemplo para tarefas básicas.

Nota

Os snippets de código 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) | Amostras

Pré-requisitos

Verificação prévia

  • Numa janela de terminal ou comando, corra dotnet --version para verificar se o .NET SDK é a versão 6.0 ou posterior.
  • Executar az --version (Azure CLI) ou Get-Module -ListAvailable AzureRM (Azure PowerShell) para verificar se tem as ferramentas apropriadas da linha de comando Azure instaladas.

Configuração

Esta secção acompanha-o através da criação de uma conta DB Azure Cosmos e da criação de um projeto que utiliza a Azure Cosmos DB para biblioteca de clientes NoSQL para .NET para gerir recursos.

Criar uma conta do Azure Cosmos DB

Dica

Nenhuma assinatura do Azure? Pode experimentar gratuitamente a Azure Cosmos DB sem necessidade de cartão de crédito. Se criar uma conta utilizando o teste gratuito, pode avançar com segurança para a secção Criar uma nova secção de aplicações .NET .

Este quickstart criará uma única conta DB Azure Cosmos utilizando a API para NoSQL.

Dica

Para este arranque rápido, recomendamos a utilização do nome msdocs-cosmos-quickstart-rgdo grupo de recursos .

  1. Inicie sessão no portal do Azure.

  2. A partir do menu portal do Azure ou da página Inicial, selecione Criar um recurso.

  3. Na página Nova , procure e selecione Azure Cosmos DB.

  4. Na página de opção API Select , selecione a opção Criar dentro da secção NoSQL . Azure Cosmos DB tem seis APIs: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin e Table. Saiba mais sobre a API para NoSQL.

    Screenshot da página de opção API selecionada para Azure Cosmos DB.

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

    Definição Valor Descrição
    Subscrição Nome da subscrição Selecione a subscrição Azure que deseja utilizar para esta conta Azure Cosmos.
    Grupo de Recursos Nome do grupo de recursos Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
    Nome da Conta Um nome exclusivo Introduza 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, pelo que o nome deve ser globalmente único. O nome só pode conter letras minúsculas, números e o caráter de hífen (-). O nome também deve ter entre 3-44 caracteres de comprimento.
    Localização A região mais próxima dos seus utilizadores Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
    Modo de capacidade Produção provisida ou sem servidor Selecione A produção provisida para criar uma conta no modo de produção previsto. Selecione Serverless para criar uma conta no modo sem servidor .
    Aplicar desconto de nível gratuito Azure Cosmos DB Aplicar ou não aplicar Ativar o nível livre de DB Azure Cosmos. Com o nível livre de DB Azure Cosmos, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente numa conta. Saiba mais sobre o free tier.

    Nota

    Pode ter até uma conta DB Azure Cosmos de nível gratuito por subscrição Azure e deve optar pela criação da conta. Se não vir a opção de aplicar o desconto de nível livre, isto significa que outra conta na subscrição já foi ativada com nível gratuito.

    Screenshot de nova página de conta para API para NoSQL.

  6. Selecione Rever + criar.

  7. Reveja as definições que fornece e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde que a página do portal seja exibida A sua implantação está completa antes de seguir em frente.

  8. Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

    Screenshot da página de implementação para API para recurso NoSQL.

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

    Screenshot de uma página de conta NoSQL da API para OSQL. A opção Chaves está em destaque no menu de navegação.

  10. Registar os valores dos campos URI e PRIMARY KEY . Usará estes valores num passo posterior.

    Screenshot da página Keys com várias credenciais para uma conta API para noSQL.

Criar uma nova aplicação .NET

Crie uma nova aplicação .NET numa pasta vazia utilizando o seu terminal preferido. Utilize o dotnet new comando especificando o modelo da consola .

dotnet new console

Instale o pacote

Adicione o Microsoft. Pacote Azure.Cosmos NuGet para o projeto .NET. Utilize o dotnet add package comando especificando o nome da embalagem NuGet.

dotnet add package Microsoft.Azure.Cosmos

Construa o projeto com o dotnet build comando.

dotnet build

Certifique-se de que a construção foi bem sucedida sem erros. A produção esperada da construção deve ser algo assim:

  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 as variáveis de ambiente

Para utilizar os valores URI e KEY PRIMÁRIO dentro do seu código, persista-os em novas variáveis ambientais na máquina local que executa a aplicação. Para definir a variável ambiente, utilize o 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 construir a aplicação, vamos olhar para a hierarquia de recursos em Azure Cosmos DB. A Azure Cosmos DB tem um modelo de objeto específico usado para criar e aceder a recursos. O Azure Cosmos DB cria recursos numa hierarquia que consiste em contas, bases de dados, contentores e itens.

Diagrama da hierarquia DB do Azure Cosmos, incluindo contas, bases de dados, contentores e itens.

Diagrama hierárquico mostrando uma conta DB Azure Cosmos no topo. A conta tem dois nós de base de dados infantil. Um dos nós da base de dados inclui dois nós de recipientes para crianças. O outro nó de base de dados inclui um único nó de recipiente para crianças. O nó de um único recipiente tem três nós de objetos infantis.

Para obter mais informações sobre a hierarquia de diferentes recursos, consulte trabalhar com bases de dados, contentores e itens em Azure Cosmos DB.

Utilizará as seguintes classes .NET para interagir com estes recursos:

  • CosmosClient - Esta classe proporciona uma representação lógica do lado do cliente para o serviço DB Azure Cosmos. O objeto cliente é usado para configurar e executar pedidos contra o serviço.
  • Database - Esta classe é uma referência a uma base de dados que pode, ou não, existir ainda no serviço. A base de dados é validada do lado do servidor quando tenta aceder a ela ou efetuar uma operação contra ela.
  • Container - Esta classe é uma referência a um recipiente que também pode ainda não existir no serviço. O recipiente é validado do lado do servidor quando se tenta trabalhar com ele.
  • QueryDefinition - Esta classe representa uma consulta SQL e quaisquer parâmetros de consulta.
  • FeedIterator<> - Esta classe representa um iterador que pode acompanhar a página atual dos resultados e obter uma nova página de resultados.
  • FeedResponse<> - Esta classe representa uma única página de respostas do iterador. Este tipo pode ser iterado através de um foreach loop.

Exemplos de código

O código de amostra descrito neste artigo cria uma base de dados com adventureworks um contentor denominado products. O products quadro foi concebido para conter detalhes do produto, tais como nome, categoria, quantidade e um indicador de venda. Cada produto também contém um identificador único.

Para este código de amostra, o recipiente utilizará a categoria como uma chave de partição lógica.

Autenticar o cliente

A partir do diretório do projeto, abra o arquivo .cs Programa . No seu editor, adicione uma diretiva de utilização para Microsoft.Azure.Cosmos.

using Microsoft.Azure.Cosmos;

Defina um novo exemplo da CosmosClient classe usando o construtor, e Environment.GetEnvironmentVariable leia as duas variáveis ambientais que criou anteriormente.

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

Para obter mais informações sobre diferentes formas de criar um CosmosClient exemplo, consulte Começar com Azure Cosmos DB para NoSQL e .NET.

Criar uma base de dados

Use o CosmosClient.CreateDatabaseIfNotExistsAsync método para criar uma nova base de dados se já não existir. Este método devolverá uma referência à base de dados existente ou recém-criada.

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

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

Para obter mais informações sobre a criação de uma base de dados, consulte Criar uma base de dados em Azure Cosmos DB para NoSQL utilizando .NET.

Criar um contentor

Criará Database.CreateContainerIfNotExistsAsync um novo recipiente se já não existir. Este método também devolverá uma referência ao recipiente.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/categoryId",
    throughput: 400
);

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

Para obter mais informações sobre a criação de um recipiente, consulte Criar um recipiente em Azure Cosmos DB para NoSQL utilizando .NET.

Criar um item

A maneira mais fácil de criar um novo item num recipiente é primeiro construir uma classe C# ou gravar tipo com todos os membros que pretende serializar em JSON. Neste exemplo, o registo C# tem um identificador único, um campo categoriaId para a chave de partição, e categoria extraName, nome, quantidade e campos de 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 recipiente ligando.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 a criação, a ampliação ou substituição de itens, consulte Criar um item em Azure Cosmos DB para NoSQL utilizando .NET.

Obter um item

Em Azure Cosmos DB, você pode executar uma operação de leitura de ponto usando tanto os campos chave de identificaçãoid () e partição únicos. No SDK, ligue Container.ReadItemAsync<> para passar em ambos os valores para devolver uma instância deserializada 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 a leitura de itens e a análise da resposta, consulte um item em Azure Cosmos DB para NoSQL usando .NET.

Artigos de consulta

Depois de inserir um item, pode executar uma consulta para obter todos os itens que correspondam 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 utiliza o tipo de QueryDefinition e uma expressão de consulta parametrizada para o filtro da chave de partição. Uma vez definida a consulta, ligue Container.GetItemQueryIterator<> para obter um iterador de resultados que irá gerir as páginas dos resultados. Em seguida, use uma combinação de while loops foreach 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

Esta aplicação cria uma base de dados e contentor NoSQL para API. O exemplo cria então um item e, em seguida, lê o mesmo item de volta. Finalmente, o exemplo emite uma consulta que só deve devolver esse item único. A cada passo, o exemplo produz metadados para a consola sobre os passos que executou.

Para executar a aplicação, utilize um terminal para navegar no diretório de aplicações e executar a aplicação.

dotnet run

A saída da app deve ser semelhante a este exemplo:

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

Limpar os recursos

Quando já não precisar da conta API para a conta NoSQL, pode eliminar o grupo de recursos correspondente.

  1. Navegue para o grupo de recursos que criou anteriormente no portal do Azure.

    Dica

    Neste arranque rápido, recomendamos o nome msdocs-cosmos-quickstart-rg.

  2. Selecione Eliminar grupo de recursos.

    Screenshot da opção grupo de recursos Delete na barra de navegação para um grupo de recursos.

  3. No Caso se tem a certeza de que pretende eliminar o diálogo, introduzir o nome do grupo de recursos e, em seguida, selecionar Eliminar.

    Screenshot da página de confirmação de excluir para um grupo de recursos.

Passos seguintes

Neste arranque rápido, aprendeu a criar uma conta Azure Cosmos DB para noSQL, criar uma base de dados e criar um recipiente utilizando o .NET SDK. Agora pode mergulhar mais profundamente num tutorial onde gere o seu Azure Cosmos DB para recursos e dados NoSQL utilizando uma aplicação de consola .NET.