Szybki start: biblioteka Azure Cosmos DB for NoSQL dla Node.js

Artykuł
01/10/2024

DOTYCZY: NoSQL

Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for NoSQL, aby Node.js wykonywać zapytania o dane w kontenerach i wykonywać typowe operacje na poszczególnych elementach. Wykonaj następujące kroki, aby wdrożyć minimalne rozwiązanie w środowisku przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure.

Dokumentacja interfejsu API — pakiet | kodu | źródłowego biblioteki (npm) | Interfejs wiersza polecenia dla deweloperów platformy Azure

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Konto usługi GitHub

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Interfejs wiersza polecenia dla deweloperów platformy Azure
Docker Desktop

Konfigurowanie

Wdróż kontener projektowy w swoim środowisku. Następnie 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.

Ważne

Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.

Otwórz terminal w katalogu głównym projektu.
Uwierzytelnianie w interfejsie wiersza polecenia dla deweloperów platformy Azure przy użyciu 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 polecenia , aby zainicjować projekt.
```
azd init
```
Podczas inicjowania skonfiguruj unikatową nazwę środowiska.

Napiwek

Nazwa środowiska będzie również używana jako nazwa docelowej grupy zasobów. W tym przewodniku Szybki start rozważ użycie polecenia msdocs-cosmos-db-.
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ę i żądaną lokalizację. Poczekaj na zakończenie procesu aprowizacji. 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.

Instalowanie biblioteki klienta

Biblioteka klienta jest dostępna za pośrednictwem Menedżer pakietów Node jako @azure/cosmos pakietu.

Otwórz terminal i przejdź do /src folderu.
```
cd ./src
```
Jeśli pakiet nie został jeszcze zainstalowany, zainstaluj go @azure/cosmos przy użyciu polecenia npm install.
```
npm install --save @azure/cosmos
```
Ponadto zainstaluj @azure/identity pakiet, jeśli nie został jeszcze zainstalowany.
```
npm install --save @azure/identity
```
Otwórz i przejrzyj plik src/package.json , aby sprawdzić, czy azure-cosmos oba wpisy i azure-identity istnieją.

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ń.
`SqlQuerySpec`	Ten interfejs reprezentuje zapytanie SQL i wszystkie parametry zapytania.

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

Uwierzytelnianie użytkownika

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. DefaultAzureCredential Użyj typu jako preferowanego sposobu implementacji połączenia bez hasła między aplikacjami i usługą Azure Cosmos DB for NoSQL. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania.

Ważne

Możesz również autoryzować żądania do usług platformy Azure przy użyciu haseł, parametry połączenia lub innych poświadczeń bezpośrednio. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać tych wpisów tajnych w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do hasła lub klucza tajnego, może uwierzytelnić się w usłudze bazy danych. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła bez ryzyka przechowywania kluczy.

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

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    endpoint,
    aadCredentials: credential
});

Pobieranie bazy danych

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

const database = client.database('cosmicworks');

Pobieranie kontenera

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

const container = database.container('products');

Tworzenie elementu

Skompiluj nowy obiekt ze wszystkimi elementami członkowskimi, które chcesz serializować w formacie JSON. W tym przykładzie typ ma unikatowy identyfikator i pola dla kategorii, nazwy, ilości, ceny i sprzedaży. Utwórz element w kontenerze przy użyciu polecenia container.items.upsert. Ta metoda "upserts" element skutecznie zastępuje element, jeśli już istnieje.

var item = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

var response = await container.items.upsert(item);

Odczytywanie elementu

Wykonaj operację odczytu punktu przy użyciu pól unikatowego identyfikatora (id) i klucza partycji. Służy container.item do pobierania wskaźnika do elementu i item.read wydajnego pobierania określonego elementu.

var id = '70b63682-b93a-4c77-aad2-65501347265f';
var partitionKey = 'gear-surf-surfboards';

var response = await container.item(id, partitionKey).read();
var read_item = response.resource;

Elementy kwerend

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

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

Pobierz wszystkie wyniki zapytania przy użyciu polecenia query.fetchAll. Pętla przez wyniki zapytania.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

var response = await container.items.query(querySpec).fetchAll();
for (var item of response.resources) {

}

Następny krok

Samouczek: tworzenie aplikacji internetowej Node.js