Kurz: Vytvoření aplikace Node.js konzolou se sadou JavaScript SDK pro správu Azure Cosmos DB dat rozhraní SQL APITutorial: Build a Node.js console app with the JavaScript SDK to manage Azure Cosmos DB SQL API data

Jako vývojář můžete mít aplikace, které používají data dokumentů NoSQL.As a developer, you might have applications that use NoSQL document data. K ukládání a přístupu k datům v dokumentu můžete použít účet rozhraní SQL API v Azure Cosmos DB.You can use a SQL API account in Azure Cosmos DB to store and access this document data. V tomto kurzu se dozvíte, jak vytvořit konzolovou aplikaci Node.js k vytváření prostředků Azure Cosmos DB a dotazování na ně.This tutorial shows you how to build a Node.js console application to create Azure Cosmos DB resources and query them.

V tomto kurzu provedete následující:In this tutorial, you will:

  • Vytvořte účet Azure Cosmos DB a připojte se k němu.Create and connect to an Azure Cosmos DB account.
  • Nastavte svoji aplikaci.Set up your application.
  • Vytvořte databázi.Create a database.
  • Vytvořte kontejner.Create a container.
  • Přidejte položky do kontejneru.Add items to the container.
  • Provede základní operace s položkami, kontejnerem a databází.Perform basic operations on the items, container, and database.

PožadavkyPrerequisites

Ujistěte se, že máte následující prostředky:Make sure you have the following resources:

Vytvořit účet Azure Cosmos DBCreate Azure Cosmos DB account

Vytvořme účet služby Azure Cosmos DB.Let's create an Azure Cosmos DB account. Pokud již máte účet, který chcete použít, můžete přeskočit k části Nastavení aplikace Node.js.If you already have an account you want to use, you can skip ahead to Set up your Node.js application. Pokud používáte emulátor služby Azure Cosmos DB, nastavte emulátor pomocí postupu v tématu Emulátor služby Azure Cosmos DB a přeskočte k části Nastavení aplikace Node.js.If you are using the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator and skip ahead to Set up your Node.js application.

  1. V nabídce Azure Portal nebo na domovské stráncevyberte vytvořit prostředek.From the Azure portal menu or the Home page, select Create a resource.

  2. Na nové stránce vyhledejte a vyberte Azure Cosmos DB.On the New page, search for and select Azure Cosmos DB.

  3. Na stránce Azure Cosmos DB vyberte vytvořit.On the Azure Cosmos DB page, select Create.

  4. Na stránce vytvořit Azure Cosmos DB účet zadejte základní nastavení pro nový účet Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    NastaveníSetting HodnotaValue PopisDescription
    PředplatnéSubscription Název předplatnéhoSubscription name Vyberte předplatné Azure, které chcete použít pro tento účet Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Skupina prostředkůResource Group Název skupiny prostředkůResource group name Vyberte skupinu prostředků nebo vyberte vytvořit novéa zadejte jedinečný název nové skupiny prostředků.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Account NameAccount Name Jedinečný názevA unique name Zadejte název, který identifikuje váš účet Azure Cosmos.Enter a name to identify your Azure Cosmos account. Vzhledem k tomu, že Documents.Azure.com je připojen k názvu, který zadáte k vytvoření identifikátoru URI, použijte jedinečný název.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Název může obsahovat jenom malá písmena, číslice a znak spojovníku (-).The name can only contain lowercase letters, numbers, and the hyphen (-) character. Musí mít délku 3-44 znaků.It must be between 3-44 characters in length.
    Rozhraní APIAPI Typ účtu, který se má vytvořitThe type of account to create Vyberte Core (SQL) pro vytvoření databáze dokumentů a dotaz pomocí syntaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    Rozhraní API určuje typ účtu, který se má vytvořit.The API determines the type of account to create. Azure Cosmos DB poskytuje pět rozhraní API: Core (SQL) a MongoDB pro data dokumentů, Gremlin pro data grafu, tabulku Azure a Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. V současné době musíte pro každé rozhraní API vytvořit samostatný účet.Currently, you must create a separate account for each API.
    Použít slevu úrovně FreeApply Free Tier Discount Použít nebo nepoužítApply or Do not apply U Azure Cosmos DB úrovně Free získáte v účtu první 400 RU/s a 5 GB úložiště zdarma.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Přečtěte si další informace o bezplatné úrovni.Learn more about free tier.
    UmístěníLocation Oblast nejbližší vašim uživatelůmThe region closest to your users Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat.Select a geographic location to host your Azure Cosmos DB account. Použijte umístění, které je nejblíže vašim uživatelům, a poskytněte jim tak nejrychlejší přístup k datům.Use the location that is closest to your users to give them the fastest access to the data.
    Typ účtuAccount Type Produkční nebo neprodukčníProduction or Non-Production Vyberte možnost produkce , pokud se účet bude používat pro produkční úlohy.Select Production if the account will be used for a production workload. Vyberte neprodukční , pokud se účet bude používat pro neprodukční, třeba pro vývoj, testování, kontrolu kvality nebo přípravu.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Toto je nastavení značky prostředku Azure, které vystavuje možnosti portálu, ale nemá vliv na příslušný účet Azure Cosmos DB.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. Tuto hodnotu můžete kdykoli změnit.You can change this value anytime.

    Poznámka

    V rámci předplatného Azure můžete mít až jednu úroveň bezplatného Azure Cosmos DB účtu a při vytváření účtu musíte souhlasit.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Pokud nevidíte možnost použít slevu úrovně Free, znamená to, že v předplatném už je povolený jiný účet s úrovní Free.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Stránka nového účtu pro službu Azure Cosmos DB

  5. Vyberte Zkontrolovat a vytvořit.Select Review + create. Můžete přeskočit oddíly síť a značky .You can skip the Network and Tags sections.

  6. Zkontrolujte nastavení účtu a pak vyberte vytvořit.Review the account settings, and then select Create. Vytvoření účtu trvá několik minut.It takes a few minutes to create the account. Počkejte, než se na stránce portálu zobrazí dokončené vaše nasazení.Wait for the portal page to display Your deployment is complete.

    Podokno Oznámení portálu Azure Portal

  7. Vyberte Přejít k prostředku a přejdete na stránku Azure Cosmos DB účet.Select Go to resource to go to the Azure Cosmos DB account page.

    Stránka Azure Cosmos DB účtu

Nastavení aplikace Node.jsSet up your Node.js application

Než začnete psát kód pro sestavení aplikace, můžete sestavit rozhraní pro vaši aplikaci.Before you start writing code to build the application, you can build the framework for your app. Spusťte následující postup pro nastavení Node.js aplikace s kódem rozhraní:Run the following steps to set up your Node.js application that has the framework code:

  1. Otevřete svůj oblíbený terminál.Open your favorite terminal.

  2. Vyhledejte složku nebo adresář, do kterého chcete uložit aplikaci Node.js.Locate the folder or directory where you'd like to save your Node.js application.

  3. Vytvořte prázdné soubory JavaScriptu pomocí následujících příkazů:Create empty JavaScript files with the following commands:

    • Windows:Windows:

      • fsutil file createnew app.js 0
      • fsutil file createnew config.js 0
      • md data
      • fsutil file createnew data\databaseContext.js 0
    • Linux nebo OS X:Linux/OS X:

      • touch app.js
      • touch config.js
      • mkdir data
      • touch data/databaseContext.js
  4. Vytvoří a inicializuje package.json soubor.Create and initialize a package.json file. Použijte následující příkaz:Use the following command:

    • npm init -y
  5. Nainstalujte přes npm modul @azure/cosmos.Install the @azure/cosmos module via npm. Použijte následující příkaz:Use the following command:

    • npm install @azure/cosmos --save

Nastavení konfigurací aplikaceSet your app's configurations

Teď, když aplikace existuje, musíte se ujistit, že může komunikovat s Azure Cosmos DB.Now that your app exists, you need to make sure it can talk to Azure Cosmos DB. Aktualizací několika nastavení konfigurace, jak je znázorněno v následujících krocích, můžete nastavit, aby aplikace komunikovala s Azure Cosmos DB:By updating a few configuration settings, as shown in the following steps, you can set your app to talk to Azure Cosmos DB:

  1. Otevřete config.js soubor ve svém oblíbeném textovém editoru.Open the config.js file in your favorite text editor.

  2. Zkopírujte a vložte následující fragment kódu do souboru config.js a nastavte vlastnosti endpoint a key na identifikátor URI koncového bodu Azure Cosmos DB a primární klíč.Copy and paste the following code snippet into the config.js file and set the properties endpoint and key to your Azure Cosmos DB endpoint URI and primary key. Databáze, názvy kontejnerů jsou nastaveny na úlohy a položky.The database, container names are set to Tasks and Items. Klíč oddílu, který budete používat pro tuto aplikaci, je /Category.The partition key you will use for this application is /category.

    // @ts-check
    
    const config = {
      endpoint: "<Your Azure Cosmos account URI>",
      key: "<Your Azure Cosmos account key>",
      databaseId: "Tasks",
      containerId: "Items",
      partitionKey: { kind: "Hash", paths: ["/category"] }
    };
    
    module.exports = config;
    

    Koncový bod a podrobnosti klíče najdete v podokně klíče Azure Portal.You can find the endpoint and key details in the Keys pane of the Azure portal.

    Snímek obrazovky se získáním klíčů z webu Azure Portal

Sada JavaScript SDK používá obecný pojem kontejner a položka.The JavaScript SDK uses the generic terms container and item. Kontejner může být kolekce, graf nebo tabulka.A container can be a collection, graph, or table. Položka představuje obsah uvnitř kontejneru a může to být dokument, pár hrany a vrcholu nebo řádek.An item can be a document, edge/vertex, or row, and is the content inside a container. V předchozím fragmentu kódu se module.exports = config; kód používá k exportu konfiguračního objektu, abyste na něj mohli odkazovat v souboru app.js .In the previous code snippet, the module.exports = config; code is used to export the config object, so that you can reference it within the app.js file.

Vytvoření databáze a kontejneruCreate a database and a container

  1. Otevřete databaseContext.js soubor ve svém oblíbeném textovém editoru.Open the databaseContext.js file in your favorite text editor.

  2. Zkopírujte a vložte následující kód do souboru databaseContext.js .Copy and paste the following code to the databaseContext.js file. Tento kód definuje funkci, která vytvoří databázi Tasks, Items a Container, pokud ještě neexistují v účtu Azure Cosmos:This code defines a function that creates the "Tasks", "Items" database and the container if they don't already exist in your Azure Cosmos account:

    const config = require("../config");
    const CosmosClient = require("@azure/cosmos").CosmosClient;
    
    /*
    // This script ensures that the database is setup and populated correctly
    */
    async function create(client, databaseId, containerId) {
      const partitionKey = config.partitionKey;
    
      /**
       * Create the database if it does not exist
       */
      const { database } = await client.databases.createIfNotExists({
        id: databaseId
      });
      console.log(`Created database:\n${database.id}\n`);
    
      /**
       * Create the container if it does not exist
       */
      const { container } = await client
        .database(databaseId)
        .containers.createIfNotExists(
          { id: containerId, partitionKey },
          { offerThroughput: 400 }
        );
    
      console.log(`Created container:\n${container.id}\n`);
    }
    
    module.exports = { create };
    

    Databáze je logický kontejner položek rozdělených napříč kontejnery.A database is the logical container of items partitioned across containers. Databázi vytvoříte pomocí createIfNotExists funkce nebo pro vytvoření třídy databáze .You create a database by using either the createIfNotExists or create function of the Databases class. Kontejner se skládá z položek, které jsou v případě rozhraní SQL API dokumenty JSON.A container consists of items which in the case of the SQL API is JSON documents. Kontejner vytvoříte pomocí createIfNotExists funkce nebo vytvořit z třídy Containers .You create a container by using either the createIfNotExists or create function from the Containers class. Po vytvoření kontejneru můžete data ukládat a dotazovat na ně.After creating a container, you can store and query the data.

    Upozornění

    Vytvoření kontejneru má vliv na ceny.Creating a container has pricing implications. Navštivte naši stránku s cenami , abyste věděli, co očekávat.Visit our pricing page so you know what to expect.

Import konfiguraceImport the configuration

  1. Otevřete app.js soubor ve svém oblíbeném textovém editoru.Open the app.js file in your favorite text editor.

  2. Zkopírováním a vložením následujícího kódu importujte @azure/cosmos modul, konfiguraci a databaseContext, který jste definovali v předchozích krocích.Copy and paste the code below to import the @azure/cosmos module, the configuration, and the databaseContext that you defined in the previous steps.

    const CosmosClient = require("@azure/cosmos").CosmosClient;
    const config = require("./config");
    const dbContext = require("./data/databaseContext");
    

Připojení k účtu Azure CosmosConnect to the Azure Cosmos account

V souboru app.js zkopírujte a vložte následující kód pro použití dříve uloženého koncového bodu a klíče k vytvoření nového objektu CosmosClient.In the app.js file, copy and paste the following code to use the previously saved endpoint and key to create a new CosmosClient object.

const { endpoint, key, databaseId, containerId } = config;

const client = new CosmosClient({ endpoint, key });

const database = client.database(databaseId);
const container = database.container(containerId);

// Make sure Tasks database is already setup. If not, create it.
await dbContext.create(client, databaseId, containerId);

Poznámka

Pokud se připojujete k emulátoru Cosmos DB, zakažte ověřování TLS pro váš proces uzlu:If connecting to the Cosmos DB Emulator, disable TLS verification for your node process:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
const client = new CosmosClient({ endpoint, key });

Teď, když máte kód pro inicializaci klienta Azure Cosmos DB, se budeme věnovat práci s prostředky Azure Cosmos DB.Now that you have the code to initialize the Azure Cosmos DB client, let's take a look at how to work with Azure Cosmos DB resources.

Položky dotazuQuery items

Azure Cosmos DB podporuje formátované dotazy proti položkám JSON uloženým v každém kontejneru.Azure Cosmos DB supports rich queries against JSON items stored in each container. Následující vzorový kód ukazuje dotaz, který lze spustit pro položky ve vašem kontejneru. Můžete zadat dotaz na položky pomocí funkce dotazu Items třídy.The following sample code shows a query that you can run against the items in your container.You can query the items by using the query function of the Items class. Přidejte následující kód do souboru app.js pro dotazování položek z vašeho účtu Azure Cosmos:Add the following code to the app.js file to query the items from your Azure Cosmos account:

console.log(`Querying container: Items`);

// query to return all items
const querySpec = {
  query: "SELECT * from c"
};

// read all items in the Items container
const { resources: items } = await container.items
  .query(querySpec)
  .fetchAll();

items.forEach(item => {
  console.log(`${item.id} - ${item.description}`);
});

Vytvořit položkuCreate an item

Položku lze vytvořit pomocí funkce Create Items třídy.An item can be created by using the create function of the Items class. Pokud používáte rozhraní API SQL, položky se procházejí jako dokumenty, které jsou uživatelsky definovaným (libovolným) obsahem JSON.When you're using the SQL API, items are projected as documents, which are user-defined (arbitrary) JSON content. V tomto kurzu vytvoříte novou položku v rámci databáze Tasks.In this tutorial, you create a new item within the tasks database.

  1. V app.js souboru definujte definici položky:In the app.js file, define the item definition:

    const newItem = {
      id: "3",
      category: "fun",
      name: "Cosmos DB",
      description: "Complete Cosmos DB Node.js Quickstart ⚡",
      isComplete: false
    };
    
  2. Přidejte následující kód pro vytvoření dříve definované položky:Add the following code to create the previously defined item:

    /** Create new item
     * newItem is defined at the top of this file
     */
    const { resource: createdItem } = await container.items.create(newItem);
    
    console.log(`\r\nCreated new item: ${createdItem.id} - ${createdItem.description}\r\n`);
    

Aktualizace položkyUpdate an item

Azure Cosmos DB podporuje nahrazování obsahu položek.Azure Cosmos DB supports replacing the contents of items. Zkopírujte a vložte následující kód do souboru app.js .Copy and paste the following code to app.js file. Tento kód získá položku z kontejneru a aktualizuje pole po dokončení na hodnotu true.This code gets an item from the container and updates the isComplete field to true.

/** Update item
 * Pull the id and partition key value from the newly created item.
 * Update the isComplete field to true.
 */
const { id, category } = createdItem;

createdItem.isComplete = true;

const { resource: updatedItem } = await container
  .item(id, category)
  .replace(createdItem);

console.log(`Updated item: ${updatedItem.id} - ${updatedItem.description}`); 
console.log(`Updated isComplete to ${updatedItem.isComplete}\r\n`);

Odstranění položkyDelete an item

Azure Cosmos DB podporuje odstraňování položek JSON.Azure Cosmos DB supports deleting JSON items. Následující kód ukazuje, jak získat položku podle jejího ID a odstranit ji.The following code shows how to get an item by its ID and delete it. Zkopírujte a vložte následující kód do souboru app.js :Copy and paste the following code to app.js file:

/**
 * Delete item
 * Pass the id and partition key value to delete the item
 */
const { resource: result } = await container.item(id, category).delete();
console.log(`Deleted item with id: ${id}`);

Spuštění aplikace Node.jsRun your Node.js application

Jako celek by váš kód měl vypadat přibližně takto:Altogether, your code should look like this:

// @ts-check
//  <ImportConfiguration>
const CosmosClient = require("@azure/cosmos").CosmosClient;
const config = require("./config");
const dbContext = require("./data/databaseContext");
//  </ImportConfiguration>

//  <DefineNewItem>
const newItem = {
  id: "3",
  category: "fun",
  name: "Cosmos DB",
  description: "Complete Cosmos DB Node.js Quickstart ⚡",
  isComplete: false
};
//  </DefineNewItem>

async function main() {
  
  // <CreateClientObjectDatabaseContainer>
  const { endpoint, key, databaseId, containerId } = config;

  const client = new CosmosClient({ endpoint, key });

  const database = client.database(databaseId);
  const container = database.container(containerId);

  // Make sure Tasks database is already setup. If not, create it.
  await dbContext.create(client, databaseId, containerId);
  // </CreateClientObjectDatabaseContainer>
  
  try {
    // <QueryItems>
    console.log(`Querying container: Items`);

    // query to return all items
    const querySpec = {
      query: "SELECT * from c"
    };
    
    // read all items in the Items container
    const { resources: items } = await container.items
      .query(querySpec)
      .fetchAll();

    items.forEach(item => {
      console.log(`${item.id} - ${item.description}`);
    });
    // </QueryItems>
    
    // <CreateItem>
    /** Create new item
     * newItem is defined at the top of this file
     */
    const { resource: createdItem } = await container.items.create(newItem);
    
    console.log(`\r\nCreated new item: ${createdItem.id} - ${createdItem.description}\r\n`);
    // </CreateItem>
    
    // <UpdateItem>
    /** Update item
     * Pull the id and partition key value from the newly created item.
     * Update the isComplete field to true.
     */
    const { id, category } = createdItem;

    createdItem.isComplete = true;

    const { resource: updatedItem } = await container
      .item(id, category)
      .replace(createdItem);

    console.log(`Updated item: ${updatedItem.id} - ${updatedItem.description}`); 
    console.log(`Updated isComplete to ${updatedItem.isComplete}\r\n`);
    // </UpdateItem>
    
    // <DeleteItem>    
    /**
     * Delete item
     * Pass the id and partition key value to delete the item
     */
    const { resource: result } = await container.item(id, category).delete();
    console.log(`Deleted item with id: ${id}`);
    // </DeleteItem>  
    
  } catch (err) {
    console.log(err.message);
  }
}

main();

V terminálu vyhledejte soubor app.js a spusťte příkaz:In your terminal, locate your app.js file and run the command:

node app.js

Měl by se zobrazit výstup počáteční aplikace.You should see the output of your get started app. Výstup by měl odpovídat ukázkovému textu níže.The output should match the example text below.

Created database:
Tasks

Created container:
Items

Querying container: Items
1 - Pick up apples and strawberries.

Created new item: 3 - Complete Cosmos DB Node.js Quickstart ⚡

Updated item: 3 - Complete Cosmos DB Node.js Quickstart ⚡
Updated isComplete to true

Deleted item with id: 3

Získání úplného řešení kurzu k Node.jsGet the complete Node.js tutorial solution

Pokud jste neměli dostatek času k dokončení kroků v tomto kurzu nebo si jenom chcete stáhnout kód, můžete ho získat z GitHubu.If you didn't have time to complete the steps in this tutorial, or just want to download the code, you can get it from GitHub.

Chcete-li spustit řešení Začínáme, které obsahuje veškerý kód v tomto článku, budete potřebovat:To run the getting started solution that contains all the code in this article, you will need:

Nainstalujte závislosti projektu přes npm.Install the project's dependencies via npm. Použijte následující příkaz:Use the following command:

  • npm install

Dále v config.js souboru aktualizujte hodnoty config. Endpoint a config. Key, jak je popsáno v kroku 3: nastavení konfigurací aplikace.Next, in the config.js file, update the config.endpoint and config.key values as described in Step 3: Set your app's configurations.

Potom v terminálu vyhledejte soubor app.js a spusťte příkaz:Then in your terminal, locate your app.js file and run the command:

node app.js 

Vyčištění prostředkůClean up resources

Když už tyto prostředky nepotřebujete, můžete odstranit skupinu prostředků, účet Azure Cosmos DB a všechny související prostředky.When these resources are no longer needed, you can delete the resource group, Azure Cosmos DB account, and all the related resources. Provedete to tak, že vyberete skupinu prostředků, kterou jste použili pro účet Azure Cosmos DB, vyberte Odstranita pak potvrďte název skupiny prostředků, která se má odstranit.To do so, select the resource group that you used for the Azure Cosmos DB account, select Delete, and then confirm the name of the resource group to delete.

Další krokyNext steps