Rychlý start: Knihovna Azure Cosmos DB for NoSQL pro Node.js

Článek
01/10/2024

PLATÍ PRO: NoSQL

Začínáme s klientskou knihovnou Azure Cosmos DB for NoSQL pro Node.js dotazovat data v kontejnerech a provádět běžné operace s jednotlivými položkami. Pomocí následujícího postupu nasaďte do svého prostředí minimální řešení pomocí Azure Developer CLI.

Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (npm) | Azure Developer CLI

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Účet GitHub

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Azure Developer CLI
Docker Desktop

Nastavení

Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd) vytvořte účet Azure Cosmos DB for NoSQL a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.

Důležité

Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.

Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí azd auth loginrozhraní příkazového řádku . Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.
```
azd auth login
```
Slouží azd init k inicializaci projektu.
```
azd init
```
Během inicializace nakonfigurujte jedinečný název prostředí.

Tip

Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .msdocs-cosmos-db-
Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.
```
azd up
```
Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.

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.

Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

Instalace klientské knihovny

Klientská knihovna je k dispozici prostřednictvím Správce balíčků Node jako @azure/cosmos balíček.

Otevřete terminál a přejděte do /src složky.
```
cd ./src
```
Pokud ještě není nainstalovaný, nainstalujte @azure/cosmos balíček pomocí npm install.
```
npm install --save @azure/cosmos
```
Pokud ještě není nainstalovaný, nainstalujte @azure/identity balíček.
```
npm install --save @azure/identity
```
Otevřete a zkontrolujte soubor src/package.json a ověřte, že azure-cosmosazure-identity obě položky existují.

Objektový model

Název	Popis
`CosmosClient`	Tato třída je primární klientskou třídou a slouží ke správě metadat nebo databází pro celý účet.
`Database`	Tato třída představuje databázi v rámci účtu.
`Container`	Tato třída se primárně používá k provádění operací čtení, aktualizace a odstraňování v kontejneru nebo v položkách uložených v kontejneru.
`PartitionKey`	Tato třída představuje klíč logického oddílu. Tato třída se vyžaduje pro mnoho běžných operací a dotazů.
`SqlQuerySpec`	Toto rozhraní představuje dotaz SQL a všechny parametry dotazu.

Vzorový kód v šabloně používá databázi pojmenovanou cosmicworks a kontejner s názvem products. Kontejner products obsahuje podrobnosti, jako je název, kategorie, množství, jedinečný identifikátor a příznak prodeje pro každý produkt. Kontejner používá /category vlastnost jako klíč logického oddílu.

Ověření klienta

Žádosti o aplikace na většinu služeb Azure musí být autorizované. Tento DefaultAzureCredential typ použijte jako upřednostňovaný způsob implementace bez hesla mezi vašimi aplikacemi a Službou Azure Cosmos DB for NoSQL. DefaultAzureCredential podporuje více metod ověřování a určuje, která metoda se má použít za běhu.

Důležité

Žádosti o služby Azure můžete také autorizovat pomocí hesel, připojovací řetězec nebo jiných přihlašovacích údajů přímo. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby tyto tajné kódy nikdy nezpřístupnili v nezabezpečeném umístění. Každý, kdo získá přístup k heslu nebo tajnému klíči, se může ověřit v databázové službě. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla bez rizika ukládání klíčů.

Tato ukázka vytvoří novou instanci CosmosClient typu a ověří se pomocí DefaultAzureCredential instance.

const credential = new DefaultAzureCredential();

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

Získání databáze

Slouží client.database k načtení existující databáze s názvem cosmicworks.

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

Získání kontejneru

Načtení existujícího products kontejneru pomocí database.container.

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

Vytvoření položky

Sestavte nový objekt se všemi členy, které chcete serializovat do formátu JSON. V tomto příkladu má typ jedinečný identifikátor a pole pro kategorii, název, množství, cenu a prodej. Vytvoření položky v kontejneru pomocí container.items.upsert. Tato metoda "upserts" položku účinně nahradí položku, pokud již existuje.

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);

Čtení položky

Proveďte operaci čtení bodu pomocí polí jedinečného identifikátoru (id) i klíče oddílu. Umožňuje container.item získat ukazatel na položku a item.read efektivně načíst konkrétní položku.

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;

Dotazování položek

Proveďte dotaz na více položek v kontejneru pomocí container.items.query. Pomocí tohoto parametrizovaného dotazu vyhledejte všechny položky v zadané kategorii:

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

Načtěte všechny výsledky dotazu pomocí query.fetchAll. Projděte výsledky dotazu.

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) {

}

Další krok

Kurz: Vytvoření webové aplikace Node.js