Szybki start: używanie usługi Azure Cosmos DB for NoSQL z zestawem Azure SDK dla platformy .NET

Dotyczy: ✅ NoSQL

W tym przewodniku szybkiego startu podstawowa aplikacja Azure Cosmos DB for NoSQL zostanie wdrożona przy użyciu zestawu Azure SDK dla .NET. Usługa Azure Cosmos DB for NoSQL to bez schematu magazyn danych, który umożliwia aplikacjom przechowywanie danych bez struktury w chmurze. Wykonywanie zapytań dotyczących danych w kontenerach i wykonywanie typowych operacji na poszczególnych elementach przy użyciu zestawu Azure SDK dla platformy .NET.

Dokumentacja referencyjna interfejsu API | Kod źródłowy biblioteki | Pakiet (NuGet) | Azure Developer CLI

Wymagania wstępne

Azure Developer CLI
Docker Desktop
.NET 9.0

Jeśli nie masz jeszcze konta platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Inicjowanie projektu

Użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć konto usługi Azure Cosmos DB for NoSQL i wdrożyć konteneryzowaną przykładową aplikację. Przykładowa aplikacja używa biblioteki klienta do zarządzania, tworzenia, odczytywania i wykonywania zapytań dotyczących przykładowych danych.

Otwórz terminal w pustym katalogu.
Jeśli nie jesteś jeszcze uwierzytelniony, uwierzytelnij się w Azure Developer CLI, używając polecenia azd auth login. Wykonaj kroki określone przez narzędzie, aby uwierzytelnić się w interfejsie wiersza polecenia przy użyciu preferowanych poświadczeń platformy Azure.
```
azd auth login
```

Użyj azd init aby zainicjować projekt.

azd init --template cosmos-db-nosql-dotnet-quickstart

Podczas inicjowania skonfiguruj unikatową nazwę środowiska.
Wdróż konto usługi Azure Cosmos DB przy użyciu polecenia azd up. Szablony Bicep wdrażają również przykładową aplikację internetową.
```
azd up
```
Podczas procesu aprowizacji wybierz subskrypcję, żądaną lokalizację i docelową grupę zasobów. Poczekaj na zakończenie procesu prowizjonowania. Proces może potrwać około pięciu minut.

Po zakończeniu aprowizacji zasobów platformy Azure adres URL uruchomionej aplikacji internetowej zostanie uwzględniony w danych wyjściowych.

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.

Użyj adresu URL w konsoli, aby przejść do aplikacji internetowej w przeglądarce. Obserwuj dane wyjściowe uruchomionej aplikacji.

Zrzut ekranu przedstawiający uruchomioną aplikację internetową.

Instalowanie biblioteki klienta

Biblioteka klienta jest dostępna w NuGet jako pakiet Microsoft.Azure.Cosmos.

Otwórz terminal i przejdź do /src/web folderu.
```
cd ./src/web
```
Jeśli pakiet nie jest jeszcze zainstalowany, zainstaluj go, używając Microsoft.Azure.Cosmos i dotnet add package.
```
dotnet add package Microsoft.Azure.Cosmos --version 3.*
```
Ponadto zainstaluj Azure.Identity pakiet, jeśli nie został jeszcze zainstalowany.
```
dotnet add package Azure.Identity --version 1.12.*
```
Otwórz i przejrzyj plik src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj , aby sprawdzić, czy Microsoft.Azure.CosmosAzure.Identity oba wpisy istnieją.

Importowanie bibliotek

Zaimportuj przestrzenie nazw Azure.Identity i Microsoft.Azure.Cosmos do swojego kodu aplikacji.

using Azure.Identity;

using Microsoft.Azure.Cosmos;

Model obiektów

Nazwa/nazwisko	opis
CosmosClient	Ta klasa jest podstawową klasą klienta i służy do zarządzania metadanymi lub bazami danych dla całego konta.
Database	Ta klasa reprezentuje bazę danych w ramach konta.
Container	Ta klasa jest używana głównie do wykonywania operacji odczytu, aktualizacji i usuwania w kontenerze lub elementach przechowywanych w kontenerze.
PartitionKey	Ta klasa reprezentuje klucz partycji logicznej. Ta klasa jest wymagana w przypadku wielu typowych operacji i zapytań.

Przykładowy kod w szablonie używa bazy danych o nazwie cosmicworks i kontenera o nazwie products. Kontener products zawiera szczegóły, takie jak nazwa, kategoria, ilość, unikatowy identyfikator i flaga sprzedaży dla każdego produktu. Kontener używa właściwości /category jako logicznego klucza partycji.

Uwierzytelnianie użytkownika

Ten przykład tworzy nowe wystąpienie klasy CosmosClient i uwierzytelnia się przy użyciu instancji DefaultAzureCredential.

DefaultAzureCredential credential = new();

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

Pobieranie bazy danych

Użyj client.GetDatabase polecenia , aby pobrać istniejącą bazę danych o nazwie cosmicworks.

Database database = client.GetDatabase("cosmicworks");

Weź kontener

Pobierz istniejący products kontener przy użyciu polecenia database.GetContainer.

Container container = database.GetContainer("products");

Tworzenie elementu

Zbuduj typ rekordu w języku C# ze wszystkimi składnikami, które chcesz zserializować do formatu JSON. W tym przykładzie typ ma unikatowy identyfikator i pola dla kategorii, nazwy, ilości, ceny i sprzedaży.

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

Utwórz element w kontenerze przy użyciu polecenia container.UpsertItem. Ta metoda dodaje lub aktualizuje przedmiot, skutecznie zastępując go, jeśli już istnieje.

Product item = new(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    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")
);

Przeczytaj element

Do wykonania operacji odczytu punktu użyj pól unikatowego identyfikatora (id) i klucza partycji. Użyj container.ReadItem do wydajnego pobierania określonego elementu.

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Elementy zapytań

Wykonaj zapytanie dotyczące wielu elementów w kontenerze przy użyciu polecenia container.GetItemQueryIterator. Znajdź wszystkie elementy w określonej kategorii przy użyciu tego sparametryzowanego zapytania:

SELECT * FROM products p WHERE p.category = @category

string query = "SELECT * FROM products p WHERE p.category = @category"

var query = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

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

Przeanalizuj wyniki zapytania podzielonego na strony, wykonując pętlę na każdej stronie wyników przy użyciu polecenia feed.ReadNextAsync. Użyj feed.HasMoreResults, aby określić, czy na początku każdej pętli istnieją jakiekolwiek wyniki.

List<Product> items = new();
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
}

Eksplorowanie danych

Użyj rozszerzenia programu Visual Studio Code dla usługi Azure Cosmos DB, aby eksplorować dane NoSQL. Możesz wykonywać podstawowe operacje bazy danych, które obejmują na przykład:

Wykonywanie zapytań przy użyciu narzędzia scrapbook lub edytora zapytań
Modyfikowanie, aktualizowanie, tworzenie i usuwanie elementów
Importowanie danych zbiorczych z innych źródeł
Zarządzanie bazami danych i kontenerami

Aby uzyskać więcej informacji, zobacz How-to use Visual Studio Code extension to explore Azure Cosmos DB for NoSQL data (Jak używać rozszerzenia programu Visual Studio Code do eksplorowania danych usługi Azure Cosmos DB for NoSQL).

Czyszczenie zasobów

Jeśli nie potrzebujesz już przykładowej aplikacji lub zasobów, usuń odpowiednie wdrożenie i wszystkie zasoby.

azd down

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-06-11