クイック スタート:.NET SDK と Azure Cosmos DB で Table API アプリをビルドするQuickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

このクイックスタートでは、GitHub から例を複製することで、.NET と Azure Cosmos DB の Table API を使用してアプリを構築する方法を示します。This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. このクイックスタートでは、Web ベースの Azure Portal で Azure Cosmos DB アカウントを作成する方法、およびデータ エクスプローラーを使用してテーブルとエンティティを作成する方法も説明します。This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

前提条件Prerequisites

まだ Visual Studio 2019 をインストールしていない場合は、無料Visual Studio 2019 Community エディションをダウンロードして使用できます。If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 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.

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

  1. 新しいブラウザー ウィンドウで、Azure Portal にサインインします。In a new browser window, sign in to the Azure portal.

  2. 左側のナビゲーション ウィンドウで、 [+ リソースの作成] を選択します。In the left navigation pane, select Create a resource. [データベース] を選択してから、 [Azure Cosmos DB] を選択します。Select Databases and then select Azure Cosmos DB.

    その他のサービスと Azure Cosmos DB が強調表示された Azure portal のスクリーンショット

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

    SettingSetting Value 説明Description
    サブスクリプションSubscription 該当するサブスクリプションYour subscription この Azure Cosmos DB アカウントに使用する Azure サブスクリプションを選択します。Select the 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 in ID
    [新規作成] を選択します。Select Create new. その後、自分のアカウントの新しいリソース グループの名前を入力します。Then enter a new resource group name for your account. 簡略化するには、ID と同じ名前を使用します。For simplicity, use the same name as your ID.
    アカウント名Account Name 一意の名前を入力しますEnter a unique name 自分の Azure Cosmos DB アカウントを識別するための一意の名前を入力します。Enter a unique name to identify your Azure Cosmos DB account.

    ID に使用できるのは、英小文字、数字、ハイフン (-) のみです。The ID can use only lowercase letters, numbers, and the hyphen (-) character. 3 から 31 文字の長さにする必要があります。It must be between 3 and 31 characters long.
    APIAPI Azure テーブルAzure Table API によって、作成するアカウントの種類が決まります。The API determines the type of account to create. Azure Cosmos DB には、5 種類の API が用意されています。ドキュメント データベース用の Core(SQL)、グラフ データベース用の Gremlin、ドキュメント データベース用の MongoDB、Azure Table、Cassandra です。Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. 現在は、API ごとに別のアカウントを作成する必要があります。Currently, you must create a separate account for each API.

    このクイックスタートでは Table API に対応するテーブルを作成するので、Azure Table を選択します。Select Azure Table because in this quickstart you're creating a table that works with the Table API.

    Table API の詳細Learn more about the Table API.
    LocationLocation ユーザーに最も近いリージョンを選択Select the region closest to your users Azure Cosmos DB アカウントをホストする地理的な場所を選択します。Select a geographic location to host your Azure Cosmos DB account. データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。Use the location that's closest to your users to give them the fastest access to data.

    追加の RU 料金を回避するために、 [geo 冗長性] オプションと [マルチ リージョン書き込み] オプションは既定値 ( [無効] ) のままにすることができます。You can leave the Geo-Redundancy and Multi-region Writes options at their default values (Disable) to avoid additional RU charges. [ネットワーク] セクションと [タグ] セクションはスキップできます。You can skip the Network and Tags sections.

  4. [確認および作成] を選択します。Select Review+Create. 検証が完了したら、 [作成] を選択してアカウントを作成します。After the validation is complete, select Create to create the account.

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

  5. アカウントの作成には数分かかります。It takes a few minutes to create the account. "デプロイが進行中です" というメッセージが表示されます。You'll see a message that states Your deployment is underway. デプロイが完了するまで待ってから、 [リソースに移動] を選択します。Wait for the deployment to finish and then select Go to resource.

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

テーブルの追加Add a table

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

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

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

    Azure Portal でのデータ エクスプローラー

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

    SettingSetting 推奨値Suggested value 説明Description
    テーブル IDTable Id sample-tablesample-table 新しいテーブルの ID。The ID for your new table. テーブル名の文字要件はデータベース ID と同じです。Table names have the same character requirements as database ids. データベース名は、1 - 255 文字である必要があります。また、/ \ # ? は使えず、末尾にスペースを入れることもできません。Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    スループットThroughput 400 RU400 RUs スループットを 400 要求ユニット (RU/秒) に変更します。Change the throughput to 400 request units per second (RU/s). 待ち時間を短縮する場合、後でスループットをスケールアップできます。If you want to reduce latency, you can scale up the throughput later.
  3. [OK] を選択します。Select OK.

  4. 新しいデータベースとテーブルがデータ エクスプローラーに表示されます。Data Explorer displays the new database and table.

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

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

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

  1. データ エクスプローラーで、sample-table を展開し、 [エンティティ][エンティティの追加] の順に選択します。In Data Explorer, expand sample-table, select Entities, and then select Add Entity.

    Azure Portal のデータ エクスプローラーで新しいエンティティを作成する

  2. PartitionKey 値ボックスと RowKey 値ボックスにデータを追加し、 [エンティティの追加] を選択します。Now add data to the PartitionKey value box and RowKey value box, and select Add Entity.

    新しいエンティティのパーティション キーと行キーを設定する

    これで、テーブルにさらにエンティティを追加したり、エンティティを編集したり、データ エクスプローラーでデータをクエリしたりできます。You can now add more entities to your table, edit your entities, or query your data in Data Explorer. データ エクスプローラーでは、スループットを拡張し、ストアド プロシージャ、ユーザー定義関数、およびトリガーをテーブルに追加することもできます。Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

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

GitHub で Table アプリの複製を作成し、接続文字列を設定して実行します。Now let's clone a Table 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/azure-cosmos-table-dotnet-core-getting-started.git
    

Visual Studio でサンプル アプリケーションを開くOpen the sample application in Visual Studio

  1. Visual Studio で、 [ファイル] メニューから [開く] を選択して、 [プロジェクト/ソリューション] を選択します。In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    ソリューションを開く

  2. サンプル アプリケーションを複製したフォルダーに移動し、TableStorage.sln ファイルを開きます。Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

接続文字列を更新する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. これでアプリが、ホストされているデータベースと通信できます。This enables your app to communicate with your hosted database.

  1. Azure Portal[接続文字列] をクリックします。In the Azure portal, click Connection String. ウィンドウの右側にある [コピー] ボタンを使ってプライマリ接続文字列をコピーします。Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

    [接続文字列] ウィンドウでプライマリ接続文字列を確認してコピーする

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

  3. ポータルのプライマリ接続文字列を StorageConnectionString に貼り付けます。Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. 引用符の内側に文字列を貼り付けます。Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. CTRL キーを押しながら S キーを押して Settings.json ファイルを保存します。Press CTRL+S to save the Settings.json file.

これで、Azure Cosmos DB と通信するために必要なすべての情報でアプリを更新しました。You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

アプリを構築してデプロイするBuild and deploy the app

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

    NuGet パッケージの管理

  2. NuGet の [参照] ボックスに「Microsoft.Azure.Cosmos.Table」と入力します。In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. これで、Cosmos DB テーブル API のクライアント ライブラリが見つかります。This will find the Cosmos DB Table API client library. このライブラリは、現在 .NET Framework と .NET Standard で使用できることにご留意ください。Note that this library is currently available for .NET Framework and .NET Standard.

    NuGet の [参照] タブ

  3. [インストール] をクリックして Microsoft.Azure.Cosmos.Table ライブラリをインストールします。Click Install to install the Microsoft.Azure.Cosmos.Table library. これにより、Azure Cosmos DB Table API パッケージとすべての依存関係がインストールされます。This installs the Azure Cosmos DB Table API package and all dependencies.

  4. アプリ全体を実行すると、サンプル データがテーブル エンティティに挿入され、終わりのところで削除されます。そのため、サンプル全体を実行した場合、データが挿入されても表示されません。When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. ただし、ブレークポイントを挿入することでデータを表示できます。However you can insert some breakpoints to view the data. BasicSamples.cs ファイルを開き、52 行目を右クリックし、 [ブレークポイント][ブレークポイントの挿入] を順に選択します。Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. 55 行目にもブレークポイントを挿入します。Insert another breakpoint on line 55.

    Add a breakpoint

  5. F5 キーを押してアプリケーションを実行します。Press F5 to run the application. コンソール ウィンドウに、Azure Cosmos DB の新しいテーブル データベースの名前 (この場合は demoa13b1) が表示されます。The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    コンソール出力

    最初のブレークポイントにヒットしたら、Azure Portal のデータ エクスプローラーに戻ります。When you hit the first breakpoint, go back to Data Explorer in the Azure portal. [最新の情報に更新] ボタンをクリックし、demo* table を展開して [エンティティ] をクリックします。Click the Refresh button, expand the demo* table, and click Entities. 右側の [エンティティ] タブに、追加された Walter Harp の新しいエンティティが表示されます。The Entities tab on the right shows the new entity that was added for Walter Harp. 新しいエンティティの電話番号が 425-555-0101 であることを確認します。Note that the phone number for the new entity is 425-555-0101.

    新しいエンティティ

    プロジェクトを実行するときに Settings.json ファイルが見つからないというエラーが発生した場合は、次の XML エントリをプロジェクトの設定に追加することで解決できます。If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. CosmosTableSamples を右クリックし、[CosmosTableSamples.csproj の編集] を選択して、次の itemGroup を追加します。Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. データ エクスプローラーの [エンティティ] タブを閉じます。Close the Entities tab in Data Explorer.

  7. F5 キーを押して、次のブレークポイントまでアプリを実行します。Press F5 to run the app to the next breakpoint.

    ブレークポイントにヒットしたら、Azure Portal に戻り、 [エンティティ] を再びクリックして [エンティティ] タブを開き、電話番号が 425-555-0105 に更新されていることを確認します。When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. F5 キーを押して、アプリを実行します。Press F5 to run the app.

    アプリによって高度なサンプル アプリで使用するためのエンティティが追加されますが、これらはテーブル API では現在サポートされていません。The app adds entities for use in an advanced sample app that the Table API currently does not support. その後、アプリは、サンプル アプリによって作成されたテーブルを削除します。The app then deletes the table created by the sample app.

  9. コンソール ウィンドウで Enter キーを押してアプリの実行を終了します。In the console window, press Enter to end the execution of the app.

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.

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

アプリと Azure Cosmos DB アカウントの使用を完了したら、それ以上料金がかからないように、作成した Azure リソースを削除できます。When you're done with your app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. リソースを削除するには、次の手順に従います。To delete the resources:

  1. Azure portal の検索バーで、「リソース グループ」を検索して選択します。In the Azure portal Search bar, search for and select Resource groups.

  2. 一覧から、このクイック スタートで作成したリソース グループを選択します。From the list, select the resource group you created for this quickstart.

    削除するリソース グループを選択する

  3. リソース グループの [概要] ページで、 [リソース グループの削除] を選択します。On the resource group Overview page, select Delete resource group.

    リソース グループを削除します

  4. 次のウィンドウで、削除するリソース グループの名前を入力し、 [削除] を選択します。In the next window, enter the name of the resource group to delete, and then select Delete.

次の手順Next steps

このクイック スタートでは、Azure Cosmos DB アカウントを作成し、データ エクスプローラーを使用してテーブルを作成し、アプリを実行する方法を説明しました。In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. これで、Table API を使用して、データをクエリできます。Now you can query your data using the Table API.