Guia de início rápido: biblioteca do Azure Cosmos DB para NoSQL para .NET
APLICA-SE A: NoSQL
Comece a usar a biblioteca de cliente do Azure Cosmos DB para NoSQL para .NET para consultar dados em seus contêineres e executar operações comuns em itens individuais. Siga estas etapas para implantar uma solução mínima em seu ambiente usando a CLI do Azure Developer.
Documentação | de referência da API Pacote de código-fonte | da biblioteca (NuGet) | CLI do desenvolvedor do Azure
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- Conta do GitHub
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- CLI do desenvolvedor do Azure
- Área de trabalho do Docker
Configuração
Implante o contêiner de desenvolvimento deste projeto em seu ambiente. Em seguida, use a CLI do Desenvolvedor do Azure (azd
) para criar uma conta do Azure Cosmos DB para NoSQL e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente para gerenciar, criar, ler e consultar dados de exemplo.
Importante
As contas do GitHub incluem um direito de armazenamento e horas essenciais sem nenhum custo. Para obter mais informações, consulte armazenamento incluído e horas principais para contas do GitHub.
Abra um terminal no diretório raiz do projeto.
Autentique-se na CLI do Desenvolvedor do Azure usando
azd auth login
o . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.azd auth login
Use
azd init
para inicializar o projeto.azd init --template cosmos-db-nosql-dotnet-quickstart
Nota
Este guia de início rápido usa o repositório GitHub azure-samples/cosmos-db-nosql-dotnet-quickstart . A CLI do Desenvolvedor do Azure clonará automaticamente esse projeto para sua máquina se ela ainda não estiver lá.
Durante a inicialização, configure um nome de ambiente exclusivo.
Gorjeta
O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar
msdocs-cosmos-db
o .Implante a conta do Azure Cosmos DB usando
azd up
o . Os modelos Bicep também implantam um aplicativo Web de exemplo.azd up
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.
Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
Use o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.
Instalar a biblioteca de cliente
A biblioteca do cliente está disponível através do NuGet, como o Microsoft.Azure.Cosmos
pacote.
Abra um terminal e navegue até a
/src/web
pasta.cd ./src/web
Se ainda não estiver instalado, instale o pacote usando
dotnet add package
oMicrosoft.Azure.Cosmos
.dotnet add package Microsoft.Azure.Cosmos
Além disso, instale o
Azure.Identity
pacote se ainda não estiver instalado.dotnet add package Azure.Identity
Abra e revise o arquivo src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj para validar se as
Microsoft.Azure.Cosmos
entradas eAzure.Identity
existem.
Modelo de objeto
Nome | Descrição |
---|---|
CosmosClient | Essa classe é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta. |
Database | Essa classe representa um banco de dados dentro da conta. |
Container | Essa classe é usada principalmente para executar operações de leitura, atualização e exclusão no contêiner ou nos itens armazenados dentro do contêiner. |
PartitionKey | Esta classe representa uma chave de partição lógica. Essa classe é necessária para muitas operações e consultas comuns. |
Exemplos de código
- Autenticar o cliente
- Obter uma base de dados
- Obter um contentor
- Criar um item
- Obter um item
- Itens de consulta
O código de exemplo no modelo usa um banco de dados chamado cosmicworks
e um contêiner chamado products
. O products
recipiente contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a /category
propriedade como uma chave de partição lógica.
Autenticar o cliente
As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Use o tipo como a maneira preferida de implementar uma conexão sem senha entre seus aplicativos e o DefaultAzureCredential
Azure Cosmos DB para NoSQL. DefaultAzureCredential
suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução.
Importante
Você também pode autorizar solicitações aos serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local inseguro. Qualquer pessoa que obtenha acesso à senha ou chave secreta pode se autenticar no serviço de banco de dados. DefaultAzureCredential
oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha sem o risco de armazenar chaves.
Este exemplo cria uma nova instância da CosmosClient
classe e autentica usando uma DefaultAzureCredential
instância.
CosmosClient client = new(
accountEndpoint: builder.Configuration["AZURE_COSMOS_DB_NOSQL_ENDPOINT"]!,
tokenCredential: new DefaultAzureCredential()
);
Obter uma base de dados
Use client.GetDatabase
para recuperar o banco de dados existente chamado cosmicworks
.
Database database = client.GetDatabase("cosmicworks");
Obter um contentor
Recupere o contêiner existente products
usando database.GetContainer
o .
Container container = database.GetContainer("products");
Criar um item
Crie um tipo de registro C# com todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo e campos para categoria, nome, quantidade, preço e venda.
public record Product(
string id,
string category,
string name,
int quantity,
decimal price,
bool clearance
);
Crie um item no contêiner usando container.UpsertItem
o . Este método "upserts" o item efetivamente substituindo o item se ele já existe.
Product item = new(
id: "68719518391",
category: "gear-surf-surfboards",
name: "Yamba Surfboard",
quantity: 12,
price: 850.00m,
clearance: false
);
ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
item: item,
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Ler um item
Execute uma operação de leitura pontual usando os campos identificador exclusivo (id
) e chave de partição. Use container.ReadItem
para recuperar eficientemente o item específico.
ItemResponse<Product> response = await container.ReadItemAsync<Product>(
id: "68719518391",
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Itens de consulta
Execute uma consulta sobre vários itens em um contêiner usando container.GetItemQueryIterator
o . Encontre todos os itens dentro de uma categoria especificada usando esta consulta parametrizada:
SELECT * FROM products p WHERE p.category = @category
var query = new QueryDefinition(
query: "SELECT * FROM products p WHERE p.category = @category"
)
.WithParameter("@category", "gear-surf-surfboards");
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
queryDefinition: query
);
Analise os resultados paginados da consulta fazendo um loop em cada página de resultados usando feed.ReadNextAsync
. Use feed.HasMoreResults
para determinar se há algum resultado restante no início de cada loop.
List<Product> items = new();
double requestCharge = 0d;
while (feed.HasMoreResults)
{
FeedResponse<Product> response = await feed.ReadNextAsync();
foreach (Product item in response)
{
items.Add(item);
}
requestCharge += response.RequestCharge;
}
Clean up resources (Limpar recursos)
Quando você não precisar mais do aplicativo ou recursos de exemplo, remova a implantação correspondente e todos os recursos.
azd down
No GitHub Codespaces, exclua o espaço de código em execução para maximizar seu armazenamento e direitos principais.
Conteúdos relacionados
- Guia de início rápido Node.js
- Início Rápido do Java
- Início Rápido do Python
- Ir Guia de início rápido