チュートリアル:JavaScript SDK を使用して、Azure Cosmos DB SQL API データを管理するための Node.js コンソール アプリを構築するTutorial: Build a Node.js console app with the JavaScript SDK to manage Azure Cosmos DB SQL API data

適用対象: SQL API

お客様は開発者として、NoSQL ドキュメント データが使用されるアプリケーションをお持ちかもしれません。As a developer, you might have applications that use NoSQL document data. Azure Cosmos DB の SQL API アカウントを使用して、このドキュメント データを格納し、それにアクセスできます。You can use a SQL API account in Azure Cosmos DB to store and access this document data. このチュートリアルでは、Azure Cosmos DB リソースを作成してそれらに対するクエリを実行する Node.js コンソール アプリケーションを構築する方法について説明します。This tutorial shows you how to build a Node.js console application to create Azure Cosmos DB resources and query them.

このチュートリアルでは、次のことについて説明します。In this tutorial, you will:

  • Azure Cosmos DB アカウントを作成して接続する。Create and connect to an Azure Cosmos DB account.
  • アプリケーションを設定する。Set up your application.
  • データベースを作成します。Create a database.
  • コンテナーを作成します。Create a container.
  • コンテナーに項目を追加する。Add items to the container.
  • 項目、コンテナー、およびデータベースに対する基本的な操作を実行する。Perform basic operations on the items, container, and database.

前提条件Prerequisites

以下のリソースがそろっていることを確認してください。Make sure you have the following resources:

Azure Cosmos DB アカウントを作成するCreate Azure Cosmos DB account

それでは、Azure Cosmos DB アカウントを作成してみましょう。Let's create an Azure Cosmos DB account. 使用するアカウントが既にある場合は、「Node.js アプリケーションをセットアップする」に進んでかまいません。If you already have an account you want to use, you can skip ahead to Set up your Node.js application. Azure Cosmos DB Emulator を使用する場合は、Azure Cosmos DB Emulator に関する記事に記載されている手順に従ってエミュレーターをセットアップし、「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. Azure portal のメニューまたは [ホーム] ページで、 [リソースの作成] を選択します。From the Azure portal menu or the Home page, select Create a resource.

  2. [新規] ページで、 [Azure Cosmos DB] を検索して選択します。On the New page, search for and select Azure Cosmos DB.

  3. [Azure Cosmos DB] ページで、 [作成] を選択します。On the Azure Cosmos DB page, select Create.

  4. [Azure Cosmos DB アカウントの作成] ページで、新しい Azure Cosmos アカウントの基本的な設定を入力します。On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    設定Setting Value 説明Description
    サブスクリプションSubscription サブスクリプション名Subscription name この Azure Cosmos アカウントに使用する Azure サブスクリプションを選択します。Select the Azure subscription that you want to use for this Azure Cosmos account.
    リソース グループResource Group リソース グループ名Resource group name リソース グループを選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。Select a resource group, or select Create new, then enter a unique name for the new resource group.
    アカウント名Account Name 一意の名前A unique name 自分の Azure Cosmos アカウントを識別するための名前を入力します。Enter a name to identify your Azure Cosmos account. 指定した名前に documents.azure.com が付加されて URI が作成されるので、一意の名前を使用してください。Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    名前に含めることができるのは、英小文字、数字、ハイフン (-) のみです。The name can only contain lowercase letters, numbers, and the hyphen (-) character. 長さは 3 文字から 44 文字でなければなりません。It must be between 3-44 characters in length.
    APIAPI 作成するアカウントの種類。The type of account to create ドキュメント データベースを作成し、SQL 構文を使用してクエリを実行するには、 [コア (SQL)] を選択します。Select Core (SQL) to create a document database and query by using SQL syntax.

    API によって、作成するアカウントの種類が決まります。The API determines the type of account to create. Azure Cosmos DB には、5 種類の API が用意されています。ドキュメント データ用のコア (SQL) と MongoDB、グラフ データ用の Gremlin、Azure Table、Cassandra です。Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 現在は、API ごとに別のアカウントを作成する必要があります。Currently, you must create a separate account for each API.
    容量モードCapacity mode プロビジョニング スループットまたはサーバーレスProvisioned throughput or Serverless プロビジョニング スループット モードでアカウントを作成するには、 [Provisioned throughput](プロビジョニング スループット) を選択します。Select Provisioned throughput to create an account in provisioned throughput mode. サーバーレス モードでアカウントを作成するには、 [サーバーレス] を選択します。Select Serverless to create an account in serverless mode.
    Apply Free Tier Discount (Free レベルの割引の適用)Apply Free Tier Discount [適用] または [適用しない]Apply or Do not apply Azure Cosmos DB Free レベルのアカウントでは、最初の 400 RU/秒と 5 GB のストレージを無料でご利用いただけます。With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Free レベルの詳細を確認してください。Learn more about free tier.
    場所Location ユーザーに最も近いリージョンThe region closest to your users Azure Cosmos DB アカウントをホストする地理的な場所を選択します。Select a geographic location to host your Azure Cosmos DB account. データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。Use the location that is closest to your users to give them the fastest access to the data.
    アカウントの種類Account Type [運用] または [Non-Production](非運用)Production or Non-Production アカウントが運用ワークロードに使用される場合は、 [運用] を選択します。Select Production if the account will be used for a production workload. アカウントが非運用環境 (開発、テスト、QA、ステージングなど) に使用される場合は、 [Non-Production](非運用) を選択します。Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. これは、ポータルでの操作を調整する Azure リソース タグの設定ですが、基になる 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. この値は、いつでも変更できます。You can change this value anytime.

    注意

    Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Free レベルの割引を適用するオプションが表示されない場合は、サブスクリプション内の別のアカウントが 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.

    注意

    [Capacity mode](容量モード) として [サーバーレス] を選択した場合、以下のオプションは利用できません。The following options are not available if you select Serverless as the Capacity mode:

    • Apply Free Tier Discount (Free レベルの割引の適用)Apply Free Tier Discount
    • geo 冗長Geo-redundancy
    • マルチリージョン ライターMulti-region Writes

    Azure Cosmos DB の新しいアカウント ページ

  5. [Review + create](レビュー + 作成) を選択します。Select Review + create. [ネットワーク] セクションと [タグ] セクションはスキップできます。You can skip the Network and Tags sections.

  6. アカウントの設定を確認し、 [作成] を選択します。Review the account settings, and then select Create. アカウントの作成には数分かかります。It takes a few minutes to create the account. ポータル ページに "デプロイが完了しました" と表示されるまで待ちます。Wait for the portal page to display Your deployment is complete.

    Azure portal の [通知] ペイン

  7. [リソースに移動] を選択し、Azure Cosmos DB アカウント ページに移動します。Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB アカウント ページ

Node.js アプリケーションを設定するSet up your Node.js application

アプリケーションを構築するコードを書く前に、アプリケーションのフレームワークを構築することができます。Before you start writing code to build the application, you can build the framework for your app. 次の手順を実行して、フレームワーク コードを含む Node.js アプリケーションを設定します。Run the following steps to set up your Node.js application that has the framework code:

  1. お使いのターミナルを開きます。Open your favorite terminal.

  2. Node.js アプリケーションを保存するフォルダーまたはディレクトリを見つけます。Locate the folder or directory where you'd like to save your Node.js application.

  3. 次のコマンドを使用して、空の JavaScript ファイルを作成します。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/OS X:Linux/OS X:

      • touch app.js
      • touch config.js
      • mkdir data
      • touch data/databaseContext.js
  4. package.json ファイルを作成して初期化します。Create and initialize a package.json file. 次のコマンドを使用します。Use the following command:

    • npm init -y
  5. npm で @azure/cosmos モジュールをインストールします。Install the @azure/cosmos module via npm. 次のコマンドを使用します。Use the following command:

    • npm install @azure/cosmos --save

アプリの構成を設定するSet your app's configurations

アプリができたら、Azure Cosmos DB と対話できることを確認する必要があります。Now that your app exists, you need to make sure it can talk to Azure Cosmos DB. 次の手順のようにいくつかの構成設定を更新することで、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. 使い慣れたテキスト エディターで config.js ファイルを開きます。Open the config.js file in your favorite text editor.

  2. 次のコード スニペットをコピーして config.js ファイルに貼り付け、プロパティ endpointkey をそれぞれ Azure Cosmos DB エンドポイント URI と主キーに設定します。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. データベース名とコンテナー名は、それぞれ TasksItems に設定されます。The database, container names are set to Tasks and Items. このアプリケーションに使用するパーティション キーは /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;
    

    エンドポイントとキーの詳細については、Azure portal[キー] ペインを参照してください。You can find the endpoint and key details in the Keys pane of the Azure portal.

    Azure portal からキーを取得するスクリーンショット

JavaScript SDK では、"コンテナー" と "項目" という一般的な用語を使用しています。The JavaScript SDK uses the generic terms container and item. コンテナーは、コレクション、グラフ、またはテーブルを表します。A container can be a collection, graph, or table. 項目は、ドキュメント、エッジ/頂点、行など、コンテナー内の内容を表します。An item can be a document, edge/vertex, or row, and is the content inside a container. 前のコード スニペットでは、module.exports = config; コードを使用して config オブジェクトをエクスポートし、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.

データベースとコンテナーを作成するCreate a database and a container

  1. 使い慣れたテキスト エディターで databaseContext.js ファイルを開きます。Open the databaseContext.js file in your favorite text editor.

  2. 次のコードをコピーし、databaseContext.js ファイルに貼り付けます。Copy and paste the following code to the databaseContext.js file. このコードでは、Azure Cosmos アカウントに "Tasks" データベースと "Items" コンテナーがまだ存在しない場合に、これらを作成する関数を定義しています。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 };
    

    データベースは、コンテナーに分割された項目の論理上のコンテナーです。A database is the logical container of items partitioned across containers. データベースは、Databases クラスの createIfNotExists または create 関数を使用して作成します。You create a database by using either the createIfNotExists or create function of the Databases class. コンテナーは、項目 (SQL API の場合は JSON ドキュメント) で構成されます。A container consists of items which in the case of the SQL API is JSON documents. コンテナーは、Containers クラスの createIfNotExists または create 関数を使用して作成します。You create a container by using either the createIfNotExists or create function from the Containers class. コンテナーを作成したら、データを格納してクエリを実行できます。After creating a container, you can store and query the data.

    警告

    コンテナーを作成すると、料金に影響があります。Creating a container has pricing implications. かかる料金については、料金ページを参照してください。Visit our pricing page so you know what to expect.

構成をインポートするImport the configuration

  1. 使い慣れたテキスト エディターで app.js ファイルを開きます。Open the app.js file in your favorite text editor.

  2. 次のコードをコピーして貼り付け、前の手順で定義した @azure/cosmos モジュール、構成、および databaseContext をインポートします。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");
    

Azure Cosmos アカウントに接続するConnect to the Azure Cosmos account

次のコードをコピーして app.js ファイルに貼り付け、前に保存したエンドポイントとキーを使用して、新しい 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);

注意

Cosmos DB エミュレーター に接続する場合は、ノード プロセスの TLS 検証を無効にします。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 });

Azure Cosmos DB クライアントを初期化するためのコードは以上で完成です。続いて、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.

クエリ項目Query items

Azure Cosmos DB では、各コンテナーに格納された JSON 項目に対する豊富なクエリがサポートされています。Azure Cosmos DB supports rich queries against JSON items stored in each container. 次のサンプル コードは、コンテナー内の項目に対して実行できるクエリを示しています。Items クラスの query 関数を使用して、項目に対してクエリを実行できます。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. 次のコードを app.js ファイルに追加し、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}`);
});

項目を作成するCreate an item

項目は、Items クラスの create 関数を使用して作成できます。An item can be created by using the create function of the Items class. SQL API を使用している場合、項目はドキュメントとして投影されます。これは、ユーザー定義の (任意の) JSON コンテンツです。When you're using the SQL API, items are projected as documents, which are user-defined (arbitrary) JSON content. このチュートリアルでは、Tasks データベース内に新しい項目を作成します。In this tutorial, you create a new item within the tasks database.

  1. app.js ファイルで、次のように項目定義を定義します。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. 次のコードを追加して、前に定義した項目を作成します。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`);
    

項目を更新するUpdate an item

Azure Cosmos DB は、項目の内容の置換をサポートしています。Azure Cosmos DB supports replacing the contents of items. 次のコードをコピーして、app.js ファイルに貼り付けます。Copy and paste the following code to app.js file. このコードは、コンテナーから項目を取得し、isComplete フィールドを 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`);

項目を削除するDelete an item

Azure Cosmos DB は、JSON 項目の削除をサポートします。Azure Cosmos DB supports deleting JSON items. 次のコードは、ID で項目を取得し、削除する方法を示しています。The following code shows how to get an item by its ID and delete it. 次のコードをコピーして、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}`);

Node.js アプリケーションを実行するRun your Node.js application

全体的なコードは次のようになります。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();

ターミナルで、app.js ファイルを見つけ、コマンドを実行します。In your terminal, locate your app.js file and run the command:

node app.js

開始したアプリケーションの出力が表示されます。You should see the output of your get started app. 出力は、次のテキスト例のようなものになるはずです。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

完全な Node.js チュートリアル ソリューションを入手するGet the complete Node.js tutorial solution

このチュートリアルの手順を実行する時間がない場合や、コードをダウンロードするだけの場合は、GitHub から入手できます。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.

この記事のすべてのコードを含む使用の開始ソリューションを実行するには、以下が必要です。To run the getting started solution that contains all the code in this article, you will need:

npm でプロジェクトの依存関係をインストールします。Install the project's dependencies via npm. 次のコマンドを使用します。Use the following command:

  • npm install

次に、config.js ファイルで、config.endpoint と config.key の値を更新します。このとき、「手順 3:アプリの構成を設定する」の説明に従います。Next, in the config.js file, update the config.endpoint and config.key values as described in Step 3: Set your app's configurations.

次に、ターミナルで app.js ファイルを見つけ、次のコマンドを実行します。Then in your terminal, locate your app.js file and run the command:

node app.js 

リソースをクリーンアップするClean up resources

これらのリソースが必要なくなったら、リソース グループ、Azure Cosmos DB アカウント、およびすべての関連リソースを削除できます。When these resources are no longer needed, you can delete the resource group, Azure Cosmos DB account, and all the related resources. そうするには、Azure Cosmos DB アカウントのためにお客様が使用したリソース グループを選択し、 [削除] を選択した後、削除するリソース グループの名前を確認します。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.

次のステップNext steps