クイック スタート: SQL API と Azure Portal を使って Azure Cosmos DB による .NET Web アプリを作るQuickstart: Build a .NET web app with Azure Cosmos DB using the SQL API and the Azure portal

Azure Cosmos DB は、Microsoft のグローバルに配布されるマルチモデル データベース サービスです。Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. Azure Cosmos DB の中核をなすグローバル配布と水平方向のスケール機能を活用して、ドキュメント、キー/値、およびグラフ データベースをすばやく作成および照会できます。You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

このクイック スタートでは、Azure Portal を使用して、Azure Cosmos DB SQL API アカウント、ドキュメント データベース、コレクションを作成する方法を説明します。This quick start demonstrates how to create an Azure Cosmos DB SQL API account, document database, and collection using the Azure portal. さらに、次のスクリーンショットに示すように、SQL .NET API 上に todo リスト Web アプリをビルドしてデプロイします。You'll then build and deploy a todo list web app built on the SQL .NET API, as shown in the following screenshot.

todo アプリとサンプル データ

前提条件Prerequisites

まだ Visual Studio 2017 をインストールしていない場合は、無料Visual Studio 2017 Community エディションをダウンロードして使用できます。If you don’t already have Visual Studio 2017 installed, you can download and use the free Visual Studio 2017 Community Edition. Visual Studio のセットアップ中に、必ず [Azure の開発] を有効にしてください。Make sure that you enable Azure development during the Visual Studio setup.

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。If you don't have an Azure subscription, create a free account before you begin.

Azure サブスクリプションを必要とせず、課金や契約もなしに Azure Cosmos DB を無料で試すことができます。You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. または、https://localhost:8081 の URI で Azure Cosmos DB Emulator を使用することもできます。Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. 主キーは、要求の認証で与えられます。The Primary Key is provided in Authenticating requests.

データベース アカウントの作成Create a database account

  1. 新しいブラウザー ウィンドウで、Azure Portal にサインインします。In a new browser window, sign in to the Azure portal.
  2. [リソースの作成] > [データベース] > [Azure Cosmos DB] の順にクリックします。Click Create a resource > Databases > Azure Cosmos DB.

    Azure Portal の [データベース] ウィンドウ

  3. [新しいアカウント] ページで、新しい Azure Cosmos DB アカウントの設定を入力します。In the New account page, enter the settings for the new Azure Cosmos DB account.

    SettingSetting Value 説明Description
    IDID <一意の名前を入力>Enter a unique name この Azure Cosmos DB アカウントを識別するための一意の名前を入力します。Enter a unique name to identify this Azure Cosmos DB account. 指定した ID に documents.azure.com が付加されて URI が作成されるので、ID は一意であっても識別可能なものを使用してください。Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique but identifiable ID.

    ID に含めることができるのは英小文字、数字、ハイフン (-) のみ、3 文字以上で 50 文字以内にする必要があります。The ID can contain only lowercase letters, numbers, and the hyphen (-) character, and it must contain 3 to 50 characters.
    APIAPI SQLSQL API によって、作成するアカウントの種類が決まります。The API determines the type of account to create. Azure Cosmos DB には、アプリケーションのニーズに応じて、SQL (ドキュメント データベース)、Gremlin (グラフ データベース)、MongoDB (ドキュメント データベース)、Azure Table、および Cassandra の 5 つの API が用意されています。現時点では、それぞれ別個のアカウントが必要です。Azure Cosmos DB provides five APIs to suits the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, each which currently require a separate account.

    このクイックスタートでは、SQL 構文を使ってクエリを実行し、SQL API でアクセスできるドキュメント データベースを作成しているので、[SQL] を選びます。Select SQL because in this quickstart you are creating a document database that is queryable using SQL syntax and accessible with the SQL API.

    SQL API について詳しくは、こちらをご覧くださいLearn more about the SQL API
    サブスクリプションSubscription 該当するサブスクリプションYour subscription この Azure Cosmos DB アカウントに使用する Azure サブスクリプションを選択します。Select Azure subscription that you want to use for this Azure Cosmos DB account.
    リソース グループResource Group 新規作成Create new

    上記の ID で指定したものと同じ一意の名前を入力Then enter the same unique name as provided above in ID
    新規作成を選択してから、自分のアカウントの新しいリソースグループの名前を入力します。Select Create New, then enter a new resource-group name for your account. 簡略化のため、ID と同じ名前を使用することができます。For simplicity, you can use the same name as your ID.
    LocationLocation <ユーザーに最も近いリージョンを選択>Select the region closest to your users Azure Cosmos DB アカウントをホストする地理的な場所を入力します。Select geographic location in which to host your Azure Cosmos DB account. データに最も高速にアクセスできる、ユーザーに最も近い場所を使用します。Use the location that's closest to your users to give them the fastest access to the data.
    Geo 冗長の有効化Enable geo-redundancy 空白Leave blank データベースのレプリケート バージョンが 2 番目 (ペア) のリージョンに作成されます。This creates a replicated version of your database in a second (paired) region. 空白のままにします。Leave this blank.
    [ダッシュボードにピン留めする]Pin to dashboard electSelect このボックスを選択すると、新しいデータベース アカウントが、アクセスしやすいようにポータルのダッシュボードに追加されます。Select this box so that your new database account is added to your portal dashboard for easy access.

    [Create] をクリックします。Then click Create.

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

  4. アカウントの作成には数分かかります。The account creation takes a few minutes. ポータルに "Azure Cosmos DB アカウントが作成されました" ページが表示されるまで待機します。Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    Azure Portal の [通知] ウィンドウ

コレクションの追加Add a collection

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

  1. [データ エクスプローラー] > [新しいコレクション] をクリックします。Click Data Explorer > New Collection.

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

    Azure Portal の [データ エクスプローラー] の [コレクションの追加] ブレード

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

    SettingSetting 推奨値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.
    コレクション IDCollection id 項目Items 新しいコレクションの名前として項目を入力します。Enter Items as the name for your new collection. コレクション ID には、データベース名と同じ文字要件があります。Collection ids have the same character requirements as database names.
    ストレージの容量Storage capacity 固定 (10 GB)Fixed (10 GB) 既定値の [固定 (10 GB)] を使用します。Use the default value of Fixed (10 GB). この値は、データベースの記憶域容量です。This value is the storage capacity of the database.
    ThroughputThroughput 400 RU400 RU スループットを 400 要求ユニット (RU/秒) に変更します。Change the throughput to 400 request units per second (RU/s). スループットを 400 RU/秒に設定するには、記憶域容量を固定 (10 GB) に設定する必要があります。Storage capacity must be set to Fixed (10 GB) in order to set throughput to 400 RU/s. 待ち時間を短縮する場合、後でスループットをスケールアップできます。If you want to reduce latency, you can scale up the throughput later.

    上記の設定に加え、必要に応じて、このコレクション用に一意なキーを追加できます。In addition to the preceding settings, you can optionally add Unique keys for the collection. この例では、このフィールドを空のままにしましょう。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 collection, 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.

    Click OK.Click OK.

    新しいデータベースとコレクションがデータ エクスプローラーに表示されます。Data Explorer displays the new database and collection.

    新しいデータベースとコレクションを示す Azure Portal のデータ エクスプローラー

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

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

  1. データ エクスプローラーで新しいデータベースが [コレクション] ウィンドウに表示されます。In Data Explorer, the new database appears in the Collections pane. [タスク] データベースを展開し、[項目] コレクションを展開して、[ドキュメント] をクリックし、[新しいドキュメント] をクリックします。Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

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

  2. ここで、次の構造のドキュメントをコレクションに追加します。Now add a document to the collection 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, click 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 now use queries in Data Explorer to retrieve and filter your data.

  1. 既定では、クエリは SELECT * FROM c と設定されていることを確認してください。See that by default, the query is set to SELECT * FROM c. この既定のクエリでは、コレクション内のすべてのドキュメントを取得し、表示します。This default query retrieves and displays all documents in the collection.

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

  2. 引き続き [ドキュメント] タブで [フィルターの編集] ボタンをクリックし、クエリの述語のボックスに ORDER BY c._ts DESC を追加してから、[フィルターの適用] をクリックすることでクエリを変更します。Stay on the Documents tab, and change the query by clicking the Edit Filter button, adding ORDER BY c._ts DESC to the query predicate box, and then clicking Apply Filter.

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

この変更したクエリでは、ドキュメントがそのタイムスタンプの降順に一覧表示されるので、ここでは 2 番目のドキュメントが最初に表示されます。This modified query lists the documents in descending order based on their time stamp, so now your second document is listed first. SQL 構文に慣れている場合は、サポートされている任意の SQL クエリをこのボックスに入力できます。If you're familiar with SQL syntax, you can enter any of the supported SQL queries in this box.

以上でデータ エクスプローラーでの作業は完了です。That completes our work in Data Explorer. コードにとりかかる前に、データ エクスプローラーを使用すると、ストアド プロシージャ、UDF、トリガーを作成し、サーバー側ビジネス ロジックを実行できるほか、スループットのスケールもできることに注目してください。Before we move on to working with code, note that you can also use Data Explorer to create stored procedures, UDFs, and triggers to perform server-side business logic as well as scale throughput. データ エクスプローラーでは、API で使用可能な、組み込みのプログラムによるデータ アクセスがすべて公開されていますが、Azure Portal でデータに簡単にアクセスできます。Data Explorer exposes all of the built-in programmatic data access available in the APIs, but provides easy access to your data in the Azure portal.

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

次は、コードを使った作業に移りましょう。Now let's switch to working with code. GitHub から SQL API アプリの複製を作成し、接続文字列を設定して実行します。Let's clone a SQL API app from GitHub, set the connection string, and run it. プログラムでデータを処理することが非常に簡単であることがわかります。You'll see how easy it is to work with data programmatically.

  1. コマンド プロンプトを開いて git-samples という名前の新しいフォルダーを作成し、コマンド プロンプトを閉じます。Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. git bash などの git ターミナル ウィンドウを開いて、cd コマンドを使用して、サンプル アプリをインストールする新しいフォルダーに変更します。Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. 次のコマンドを実行して、サンプル レポジトリを複製します。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/documentdb-dotnet-todo-app.git
    
  4. 次に、Visual Studio で todo ソリューション ファイルを開きます。Then open the todo solution file in Visual Studio.

コードの確認Review the code

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

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

  • 76 行目では、DocumentClient が初期化されます。The DocumentClient is initialized on line 76.

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
    
  • 91 行目では、新しいデータベースが作成されます。A new database is created on line 91.

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
    
  • 110 行目では、新しいコレクションが作成されます。A new collection is created on line 110.

    await client.CreateDocumentCollectionAsync(
        UriFactory.CreateDatabaseUri(DatabaseId),
        new DocumentCollection
            {
               Id = CollectionId
            },
        new RequestOptions { OfferThroughput = 400 });
    

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

ここで Azure Portal に戻り、接続文字列情報を取得し、アプリにコピーします。Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. Azure Portal で、Azure Cosmos DB アカウントの左のナビゲーションから、[キー] をクリックしてから [読み取り/書き込みキー] をクリックします。In the Azure portal, in your Azure Cosmos DB account, in the left navigation click Keys, and then click Read-write Keys. 次の手順では、画面の右側のコピー ボタンを使用して、URI とプライマリ キーを web.config ファイルにコピーします。You'll use the copy buttons on the right side of the screen to copy the URI and Primary Key into the web.config file in the next step.

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

  2. Visual Studio 2017 で web.config ファイルを開きます。In Visual Studio 2017, open the web.config file.

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

    <add key="endpoint" value="FILLME" />

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

    <add key="authKey" value="FILLME" />

Web アプリの実行Run the web app

  1. Visual Studio のソリューション エクスプローラーでプロジェクトを右クリックし、[NuGet パッケージの管理] をクリックします。In Visual Studio, right-click on the project in Solution Explorer and then click Manage NuGet Packages.

  2. NuGet の [参照] ボックスに「DocumentDB」と入力します。In the NuGet Browse box, type DocumentDB.

  3. 結果から、Microsoft.Azure.DocumentDB ライブラリをインストールします。From the results, install the Microsoft.Azure.DocumentDB library. これにより、Microsoft.Azure.DocumentDB パッケージとすべての依存関係がインストールされます。This installs the Microsoft.Azure.DocumentDB package as well as all dependencies.

  4. Ctrl + F5 キーを押してアプリケーションを実行します。Click CTRL + F5 to run the application. ブラウザーにアプリが表示されます。Your app displays in your browser.

  5. ブラウザーで、[新規作成] をクリックし、to-do アプリで、いくつか新しいタスクを作成します。Click Create New in the browser and create a few new tasks in your to-do app.

    todo アプリとサンプル データ

これで、データ エクスプローラーに戻って、この新しいデータの表示、クエリ、変更、操作を行うことができます。You can now go back to Data Explorer and see query, modify, and work with this new data.

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

Azure ポータルでは、アカウント内のスループット、ストレージ、可用性、待機時間、およびリソースの整合性が監視されます。The throughput, storage, availability, latency, and consistency of the resources in your account are monitored in the Azure portal. これらのメトリックを簡単に見てみましょう。Let's take a quick look at these metrics.

  1. ナビゲーション メニューで [メトリック] をクリックします。Click Metrics in the navigation menu.

    Azure Portal のメトリック

  2. 各タブをクリックして、Azure Cosmos DB が提供するメトリックを確認します。Click through each of the tabs so you're aware of the metrics Azure Cosmos DB provides.

    Azure Cosmos DB サービス レベル アグリーメント (SLA) に関連付けられているそれぞれのグラフは、SLA のいずれかに違反していることを示す情報を提供します。Each chart that's associated with the Azure Cosmos DB Service Level Agreements (SLAs) provides a line that shows if any of the SLAs have been violated. Azure Cosmos DB は、この一連のメトリックを使用して SLA の監視を透明化します。Azure Cosmos DB makes monitoring your SLAs transparent with this suite of metrics.

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

リソースのクリーンアップClean up resources

このアプリの使用を続けない場合は、次の手順に従って、このクイック スタートで作成したすべてのリソースを削除して、課金が発生しないようにします。If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. Azure Portal の左端で [リソース グループ] を選択し、作成したリソース グループを選択します。In the Azure portal, select Resource groups on the far left, and then select the resource group you created.

    左側のメニューが折りたたまれている場合は、If the left menu is collapsed, click 展開ボタン をクリックして展開します。to expand it.

    Azure ポータルのメトリック

  2. 新しいウィンドウでリソース グループを選択し、[リソース グループの削除] をクリックします。In the new window select the resource group, and then click Delete resource group.

    Azure ポータルのメトリック

  3. 新しいウィンドウで、削除するリソース グループの名前を入力し、[削除] をクリックします。In the new window, type the name of the resource group to delete, and then click Delete.

次の手順Next steps

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