クイック スタート:Node.js を使用して Azure Cosmos DB の SQL API アカウントに接続してデータを照会するQuickstart: Use Node.js to connect and query data from Azure Cosmos DB SQL API account

このクイックスタートでは、Azure portal から Azure Cosmos DB のSQL API アカウントを作成して管理し、また GitHub から複製された Node.js アプリを使用します。In this quickstart, you create and manage an Azure Cosmos DB SQL API account from the Azure portal, and by using a Node.js app cloned from GitHub. Azure Cosmos DB は、マルチモデル データベース サービスです。グローバルな分散と水平方向のスケーリング機能により、ドキュメント データベースやテーブル データベース、キーと値のデータベース、グラフ データベースをすばやく作成し、クエリを実行することができます。Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities.

チュートリアル ビデオWalkthrough video

この記事の内容の完全なチュートリアルについては、こちらのビデオをご覧ください。Watch this video for a complete walkthrough of the content in this article.

前提条件Prerequisites

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

このクイックスタートの用途であれば、[Azure Cosmos DB を無料で試す] オプションを使用して Azure Cosmos アカウントを作成することができます。For this quickstart purpose, you can use the try Azure Cosmos DB for free option to create an Azure Cosmos account.

  1. Azure Cosmos DB を無料で試す」ページに移動します。Navigate to the try Azure Cosmos DB for free page.

  2. SQL API アカウントを選択し、 [作成] を選択します。Choose the SQL API account and select Create. Microsoft アカウントを使用してサインインしてください。Sign-in using your Microsoft account.

  3. サインインに成功すれば、Azure Cosmos アカウントの準備は完了です。After the sign-in is successful, your Azure Cosmos account should be ready. [Open in the Azure portal](Azure portal で開く) を選択して、新しく作成したアカウントを開きます。Select Open in the Azure portal to open the newly created account.

[Azure Cosmos DB を無料で試す] オプションには、Azure サブスクリプションは不要です。30 日の期間限定で Azure Cosmos アカウントが提供されます。The "try Azure Cosmos DB for free" option doesn't require an Azure subscription and it offers you an Azure Cosmos account for a limited period of 30 days. もっと長い期間 Azure Cosmos アカウントを使用する場合は、ご利用の Azure サブスクリプション内からアカウントを作成する必要があります。If you want to use the Azure Cosmos account for a longer period, you should instead create the account within your Azure subscription.

コンテナーの追加Add a container

Azure portal でデータ エクスプローラー ツールを使用してデータベースとコンテナーを作成できるようになりました。You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. [データ エクスプローラー] > [新しいコンテナー] の順に選択します。Select Data Explorer > New Container.

    [コンテナーの追加] 領域が右端に表示されます。表示するには、右へスクロールする必要がある場合があります。The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Azure portal の [データ エクスプローラー] の [コンテナーの追加] ウィンドウ

  2. [コンテナーの追加] ページで、新しいコンテナーの設定を入力します。In the Add container page, enter the settings for the new container.

    設定Setting 推奨値Suggested value 説明Description
    データベース IDDatabase ID タスクTasks 新しいデータベースの名前として_タスク_を入力します。Enter Tasks as the name for the new database. データベース名は 1 文字以上 255 文字以内にする必要があります。/, \\, #, ? は使えず、末尾にスペースを入れることもできません。Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. [Provision database throughput](データベース スループットをプロビジョニングする) オプションをオンにすると、データベースにプロビジョニングされたスループットをデータベース内のすべてのコンテナーにわたって共有できます。Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. このオプションは、コストの削減にも役立ちます。This option also helps with cost savings.
    スループットThroughput 400400 スループットを 400 要求ユニット/秒 (RU/秒) のままにします。Leave the throughput at 400 request units per second (RU/s). 待ち時間を短縮する場合、後でスループットをスケールアップできます。If you want to reduce latency, you can scale up the throughput later.
    コンテナー IDContainer ID アイテムItems 新しいコンテナーの名前として「項目」と入力します。Enter Items as the name for your new container. コンテナー ID には、データベース名と同じ文字要件があります。Container IDs have the same character requirements as database names.
    パーティション キーPartition key /category/category この記事で説明するサンプルでは、 /category をパーティション キーとして使用します。The sample described in this article uses /category as the partition key.

    上記の設定に加え、必要に応じて、このコンテナー用に一意なキーを追加できます。In addition to the preceding settings, you can optionally add Unique keys for the container. この例では、このフィールドを空のままにしましょう。Let's leave the field empty in this example. 一意なキーを使用すると、開発者はデータベースにデータ整合性のレイヤーを追加できます。Unique keys provide developers with the ability to add a layer of data integrity to the database. コンテナーの作成中に一意キー ポリシーを作成すると、パーティション キーごとに 1 つ以上の値の一意性が保証されます。By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. 詳細については、記事「Azure Cosmos DB における一意なキー」を参照してください。To learn more, refer to the Unique keys in Azure Cosmos DB article.

    [OK] を選択します。Select OK. 新しいデータベースとコンテナーがデータ エクスプローラーに表示されます。The Data Explorer displays the new database and container.

サンプル データの追加Add sample data

これで、データ エクスプローラーを使用して、新しいコンテナーにデータを追加できます。You can now add data to your new container using Data Explorer.

  1. データ エクスプローラーで、Tasks データベースを展開し、Items コンテナーを展開します。From the Data Explorer, expand the Tasks database, expand the Items container. [項目] を選択し、 [新しい項目] を選択します。Select Items, and then select New Item.

    Azure Portal のデータ エクスプローラーで新しいドキュメントを作成する

  2. ここで、次の構造のドキュメントをコンテナーに追加します。Now add a document to the container with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. json を [ドキュメント] タブに追加したら、 [保存] を選択します。Once you've added the json to the Documents tab, select Save.

    json データをコピーし、Azure portal のデータ エクスプローラーで [保存] を選択する

  4. もう 1 つドキュメントを作成して保存します。id プロパティには一意の値を挿入し、その他のプロパティについては適宜変更してください。Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Azure Cosmos DB では、データにスキーマを課さないため、新しいドキュメントは必要な任意の構造にすることができます。Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

データのクエリQuery your data

データ エクスプローラーでクエリを使用して、データを取得しフィルター処理できます。You can use queries in Data Explorer to retrieve and filter your data.

  1. データ エクスプローラーの [Items](項目) タブの上部で、既定のクエリ SELECT * FROM c を確認します。At the top of the Items tab in Data Explorer, review the default query SELECT * FROM c. このクエリは、コンテナーからすべてのドキュメントを取得して ID 順に表示します。This query retrieves and displays all documents from the container ordered by ID.

    データ エクスプローラーの既定のクエリは SELECT * FROM c

  2. クエリを変更するには、 [フィルターの編集] を選択し、既定のクエリを ORDER BY c._ts DESC に置き換えてから、 [フィルターの適用] を選択します。To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    ORDER BY c._ts DESC を追加し [フィルターの適用] をクリックすることで既定のクエリを変更

    この変更したクエリでは、ドキュメントがそのタイムスタンプの降順に一覧表示されるので、ここでは 2 番目のドキュメントが最初に表示されます。The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    クエリを ORDER BY c._ts DESC に変更し、[フィルターの適用] をクリックする

SQL 構文に慣れている場合は、サポートされている任意の SQL クエリをクエリ述語ボックスに入力できます。If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. さらに、データ エクスプローラーを使用して、サーバー側ビジネス ロジックのためのストアド プロシージャ、UDF、トリガーを作成することもできます。You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

データ エクスプローラーは、API で利用可能なすべての組み込みのプログラムによるデータ アクセス機能への簡単な Azure portal アクセスを提供します。Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. また、ポータルを使用して、スループットのスケーリング、キーと接続文字列の取得、および Azure Cosmos DB アカウントのメトリックと SLA の確認を行うこともできます。You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

サンプル アプリケーションの複製Clone the sample application

ここで、GitHub から Node.js アプリの複製を作成し、接続文字列を設定して実行します。Now let's clone a Node.js app from GitHub, set the connection string, and run it.

  1. 次のコマンドを実行して、サンプル レポジトリを複製します。Run the following command to clone the sample repository. このコマンドは、コンピューター上にサンプル アプリのコピーを作成します。This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
    

コードの確認Review the code

この手順は省略可能です。This step is optional. コード内の Azure Cosmos データベース リソースの作成方法に関心がある場合は、次のスニペットを確認できます。If you're interested in learning how the Azure Cosmos database resources are created in the code, you can review the following snippets. 関心がない場合は、「接続文字列の更新」に進んでください。Otherwise, you can skip ahead to Update your connection string.

以前のバージョンの SQL JavaScript SDK に慣れている方は、"コレクション" や "ドキュメント" といった用語をよく目にしたかと思います。If you're familiar with the previous version of the SQL JavaScript SDK, you may be used to seeing the terms collection and document. Azure Cosmos DB は複数の API モデルをサポートしているため、バージョン 2.0 以上の JavaScript SDK では、コレクション、グラフ、テーブルを表す用語として "コンテナー" が、またコンテナーの内容を表す用語として "項目" が一般的に使用されます。Because Azure Cosmos DB supports multiple API models, version 2.0+ of the JavaScript SDK uses the generic terms container, which may be a collection, graph, or table, and item to describe the content of the container.

Cosmos DB JavaScript SDK は "@azure/cosmos" と呼ばれ、npm からインストールできます。The Cosmos DB JavaScript SDK is called "@azure/cosmos" and can be installed from npm...

npm install @azure/cosmos

次のスニペットはすべて app.js ファイルからのものです。The following snippets are all taken from the app.js file.

  • CosmosClient@azure/cosmos npm パッケージからインポートされます。The CosmosClient is imported from the @azure/cosmos npm package.

    const CosmosClient = require("@azure/cosmos").CosmosClient;
    
  • 新しい CosmosClient オブジェクトが初期化されます。A new CosmosClient object is initialized.

    const client = new CosmosClient({ endpoint, key });
    
  • "タスク" データベースを選択します。Select the "Tasks" database.

    const database = client.database(databaseId);
    
  • "アイテム" コンテナーまたはコレクションを選択します。Select the "Items" container/collection.

    const container = database.container(containerId);
    
  • "アイテム" コンテナー内のすべての項目を選択します。Select all the items in the "Items" container.

    // query to return all items
    const querySpec = {
      query: "SELECT * from c"
    };
    
    const { resources: items } = await container.items
      .query(querySpec)
      .fetchAll();
    
  • 新しい項目を作成しますCreate a new item

    const { resource: createdItem } = await container.items.create(newItem);
    
  • 項目を更新しますUpdate an item

    const { id, category } = createdItem;
    
    createdItem.isComplete = true;
    const { resource: updatedItem } = await container
      .item(id, category)
      .replace(createdItem);
    
  • 項目を削除するDelete an item

    const { resource: result } = await container.item(id, category).delete();
    

注意

"更新" メソッドと "削除" メソッドの両方で、container.item() を呼び出してデータベースから項目を選択する必要があります。In both the "update" and "delete" methods, the item has to be selected from the database by calling container.item(). 渡される 2 つのパラメーターは、項目の ID と項目のパーティション キーです。The two parameters passed in are the id of the item and the item's partition key. この場合、パーティション キーは "category" フィールドの値です。In this case, the parition key is the value of the "category" field.

接続文字列を更新するUpdate your connection string

次に、Azure portal に戻って、Azure Cosmos アカウントの接続文字列情報を取得します。Now go back to the Azure portal to get the connection string details of your Azure Cosmos account. アプリからデータベースに接続できるよう、接続文字列をアプリにコピーします。Copy the connection string into the app so that it can connect to your database.

  1. Azure portal の Azure Cosmos DB アカウントで、左のナビゲーションの [キー] を選択してから [読み取り/書き込みキー] を選択します。In your Azure Cosmos DB account in the Azure portal, select Keys from the left navigation, and then select Read-write Keys. 次の手順では、画面の右側にあるコピー ボタンを使用して、URI と主キーを app.js ファイルにコピーします。Use the copy buttons on the right side of the screen to copy the URI and Primary Key into the app.js file in the next step.

    Azure portal の [キー] ブレードでアクセス キーを表示およびコピーする

  2. config.js ファイルを開きます。In Open the config.js file.

  3. ポータルから (コピー ボタンを使用して) URI 値をコピーし、config.js の endpoint キーの値に設定します。Copy your URI value from the portal (using the copy button) and make it the value of the endpoint key in config.js.

    endpoint: "<Your Azure Cosmos account URI>"

  4. 次に、ポータルから [プライマリ キー] 値をコピーし、config.js 内の config.key の値に設定します。Then copy your PRIMARY KEY value from the portal and make it the value of the config.key in config.js. これで、Azure Cosmos DB と通信するために必要なすべての情報でアプリを更新しました。You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

    key: "<Your Azure Cosmos account key>"

アプリを実行するRun the app

  1. ターミナルで npm install を実行して、"@azure/cosmos" npm パッケージをインストールします。Run npm install in a terminal to install the "@azure/cosmos" npm package

  2. ターミナルで node app.js を実行し、node アプリケーションを起動します。Run node app.js in a terminal to start your node application.

  3. 先ほどこのクイックスタートで作成した 2 つの項目が列挙されます。新しい項目が作成されます。The two items that you created earlier in this quickstart are listed out. A new item is created. その項目の "isComplete" フラグが "true" に更新された後、最終的にその項目は削除されます。The "isComplete" flag on that item is updated to "true" and then finally, the item is deleted.

このサンプル アプリケーションの実験を続けるか、Data Explorer に戻ってデータに変更を加えたりデータを操作したりすることができます。You can continue to experiment with this sample application or go back to Data Explorer, modify, and work with your data.

Azure Portal での SLA の確認Review SLAs in the Azure portal

Azure portal では、Cosmos DB アカウントのスループット、ストレージ、可用性、待ち時間、および一貫性が監視されます。The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Azure Cosmos DB サービス レベル アグリーメント (SLA) に関連付けられたメトリックのグラフに、実際のパフォーマンスと比較された SLA の値が示されます。Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. この一連のメトリックによって、SLA の監視が透明化されます。This suite of metrics makes monitoring your SLAs transparent.

メトリックと SLA を確認するには:To review metrics and SLAs:

  1. Cosmos DB アカウントのナビゲーション メニューで [メトリック] を選択します。Select Metrics in your Cosmos DB account's navigation menu.

  2. [遅延時間] など、タブを選択し、右側で期間を選択します。Select a tab such as Latency, and select a timeframe on the right. グラフ上の [実際][SLA] の線を比較します。Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB の一連のメトリック

  3. 他のタブでメトリックを確認します。Review the metrics on the other tabs.

次のステップNext steps

このクイック スタートでは、Azure Cosmos DB アカウントを作成し、データ エクスプローラーを使用してコンテナーを作成し、Node.js アプリを実行する方法を説明しました。In this quickstart, you've learned how to create an Azure Cosmos DB account, create a container using the Data Explorer, and run a Node.js app. これで、Azure Cosmos DB アカウントに追加のデータをインポートできるようになりました。You can now import additional data to your Azure Cosmos DB account.