チュートリアル:.NET コンソール アプリをビルドして Azure Cosmos DB SQL API アカウントのデータを管理する

適用対象: SQL API

Azure Cosmos DB SQL API を実際に使ってみるチュートリアルへようこそ。 このチュートリアルに従うことで、Azure Cosmos DB リソースを作成し、クエリするコンソール アプリケーションを準備することができます。

このチュートリアルでは、Azure Cosmos DB .NET SDK のバージョン 3.0 以降を使用します。 .NET Framework または .NET Core を使用できます。

このチュートリアルの内容:

  • Azure Cosmos アカウントを作成し、アカウントに接続する
  • Visual Studio でプロジェクトを構成する
  • データベースとコンテナーを作成する
  • コンテナーに項目を追加する
  • コンテナーにクエリを実行する
  • 項目に対して作成、読み取り、更新、および削除 (CRUD) 操作を実行する
  • データベースを削除する

時間がなくても 心配はありません。 GitHub で完全なソリューションを入手できます。 簡単な手順については、「チュートリアル のソリューションの完全版を入手する」のセクションを参照してください。

それでは始めましょう。

前提条件

手順 1:Azure Cosmos DB アカウントを作成する

それでは、Azure Cosmos DB アカウントを作成してみましょう。 使用するアカウントが既にある場合は、このセクションをスキップします。 Azure Cosmos DB エミュレーターを使用するには、Azure Cosmos DB エミュレーターに関する記事に記載されている手順に従ってエミュレーターを設定してください。 その後、「手順 2:Visual Studio プロジェクトをセットアップする」に進みます。

  1. From the Azure portal menu or the Home page, select Create a resource.

  2. On the New page, search for and select Azure Cosmos DB.

  3. On the Azure Cosmos DB page, select Create.

  4. In the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    Setting Value Description
    Subscription Subscription name 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 Enter a name to identify your Azure Cosmos account. 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. It must be between 3-31 characters in length.
    API The type of account to create Select Core (SQL) to create a document database and query by using SQL syntax.

    The API determines the type of account to create. Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Currently, you must create a separate account for each API.

    Learn more about the SQL API.
    Location The region closest to your users 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.
    Capacity mode Provisioned throughput or Serverless Select Provisioned throughput to create an account in provisioned throughput mode. Select Serverless to create an account in serverless mode.
    Apply Azure Cosmos DB free tier discount Apply or Do not apply With Azure Cosmos DB free tier, you will get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about free tier.

    注意

    You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. 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.

    The new account page for Azure Cosmos DB

  5. In the Global Distribution tab, configure the following details. You can leave the default values for the purpose of this quickstart:

    Setting Value Description
    Geo-Redundancy Disable Enable or disable global distribution on your account by pairing your region with a pair region. You can add more regions to your account later.
    Multi-region Writes Disable Multi-region writes capability allows you to take advantage of the provisioned throughput for your databases and containers across the globe.

    注意

    The following options are not available if you select Serverless as the Capacity mode:

    • Apply Free Tier Discount
    • Geo-redundancy
    • Multi-region Writes
  6. Optionally you can configure additional details in the following tabs:

    • Networking - Configure access from a virtual network.
    • Backup Policy - Configure either periodic or continuous backup policy.
    • Encryption - Use either service-managed key or a customer-managed key.
    • Tags - Tags are name/value pairs that enable you to categorize resources and view consolidated billing by applying the same tag to multiple resources and resource groups.
  7. Select Review + create.

  8. 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.

    The Azure portal Notifications pane

  9. Select Go to resource to go to the Azure Cosmos DB account page.

    The Azure Cosmos DB account page

手順 2:Visual Studio プロジェクトをセットアップする

  1. Visual Studio を開き、 [新しいプロジェクトの作成] を選択します。

  2. [新しいプロジェクトの作成] で、C# の [コンソール アプリ (.NET Framework)] を選択してから、 [次へ] を選択します。

  3. プロジェクトに CosmosGettingStartedTutorial という名前を付けて、 [作成] を選択します。

    プロジェクトを構成する

  4. ソリューション エクスプローラー で、Visual Studio ソリューションの下にある新しいコンソール アプリケーションを右クリックし、 [NuGet パッケージの管理] を選択します。

  5. [NuGet パッケージ マネージャー][参照] を選択し、Microsoft.Azure.Cosmos を検索します。 [Microsoft.Azure.Cosmos] を選択し、 [インストール] を選択します。

    Azure Cosmos DB クライアント SDK 用 NuGet のインストール

    Azure Cosmos DB SQL API クライアント ライブラリのパッケージ ID は Microsoft Azure Cosmos DB クライアント ライブラリ です。

これでセットアップは終了です。 いくつかのコードの記述を開始しましょう。 このチュートリアルの完全なプロジェクトについては、「Azure Cosmos DB を使用した .NET コンソール アプリの開発」を参照してください。

手順 3:Azure Cosmos DB アカウントに接続する

  1. Program.cs ファイルで、C# アプリケーションの先頭にある参照を、以下の参照で置き換えます。

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
  2. Program クラスに次の定数と変数を追加します。

    public class Program
    {
        // ADD THIS PART TO YOUR CODE
    
        // The Azure Cosmos DB endpoint for running this sample.
        private static readonly string EndpointUri = "<your endpoint here>";
        // The primary key for the Azure Cosmos account.
        private static readonly string PrimaryKey = "<your primary key>";
    
        // The Cosmos client instance
        private CosmosClient cosmosClient;
    
        // The database we will create
        private Database database;
    
        // The container we will create.
        private Container container;
    
        // The name of the database and container we will create
        private string databaseId = "FamilyDatabase";
        private string containerId = "FamilyContainer";
    }
    

    注意

    以前のバージョンの .NET SDK に慣れている方は、"コレクション" や "ドキュメント" という用語をよく目にしたかと思います。 Azure Cosmos DB では複数の API モデルをサポートしているため、.NET SDK バージョン 3.0 では、"コンテナー" と "項目" という一般的な用語が使用されています。 "コンテナー" は、コレクション、グラフ、またはテーブルを表します。 "項目" は、ドキュメント、エッジ/頂点、行など、コンテナー内の内容を表します。 詳細については、「Azure Cosmos DB のデータベース、コンテナー、項目の操作」を参照してください。

  3. Azure Portalを開きます。 ご使用の Azure Cosmos DB アカウントを探して、 [キー] を選択します。

    Azure portal から Azure Cosmos DB キーを取得する

  4. Program.cs で、<your endpoint URL>URI の値に置き換えます。 <your primary key>PRIMARY KEY の値に置き換えます。

  5. Main メソッドの下に、GetStartedDemoAsync という新しい非同期タスクを追加します。これによって新しい CosmosClient がインスタンス化されます。

    public static async Task Main(string[] args)
    {
    }
    
    // ADD THIS PART TO YOUR CODE
    /*
        Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    */
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    }
    

    Azure Cosmos DB リソース上で実行するメソッドを呼び出すエントリ ポイントとして GetStartedDemoAsync を使用します。

  6. 次のコードを追加して、Main メソッドから GetStartedDemoAsync 非同期タスクを実行します。 Main メソッドは例外をキャッチし、コンソールに書き込みます。

    public static async Task Main(string[] args)
    {
        try
        {
            Console.WriteLine("Beginning operations...\n");
            Program p = new Program();
            await p.GetStartedDemoAsync();
    
        }
        catch (CosmosException de)
        {
            Exception baseException = de.GetBaseException();
            Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
    
  7. F5 キーを押してアプリケーションを実行します。

    コンソールには、次のメッセージが表示されます。End of demo, press any key to exit. (デモはこれで終わりです。終了するには何かキーを押してください。) このメッセージによって、アプリケーションが Azure Cosmos DB に接続したことを確認できます。 表示されたら、コンソール ウィンドウを閉じます。

お疲れさまでした。 これで、Azure Cosmos DB アカウントに接続しました。

手順 4:データベースを作成する

データベースは、コンテナーに分割された項目の論理上のコンテナーです。 CosmosClient クラスの CreateDatabaseIfNotExistsAsync または CreateDatabaseAsync のいずれかのメソッドでデータベースを作成できます。

  1. CreateDatabaseAsync メソッドをコピーし、GetStartedDemoAsync メソッドの下に貼り付けます。

    /// <summary>
    /// Create the database if it does not exist
    /// </summary>
    private async Task CreateDatabaseAsync()
    {
        // Create a new database
        this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
        Console.WriteLine("Created Database: {0}\n", this.database.Id);
    }
    

    CreateDatabaseAsync によって、databaseId フィールドに指定された ID で新しいデータベース (ID FamilyDatabase) が作成されます (このデータベースがまだ存在していない場合)。

  2. CosmosClient をインスタンス化したところに、次のコードをコピーして貼り付けて、追加した CreateDatabaseAsync メソッドを呼び出します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateDatabaseAsync();
    }
    

    Program.cs は次のようになっているはずです (実際のエンドポイントとプライマリ キーが入力されています)。

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
    namespace CosmosGettingStartedTutorial
    {
        class Program
        {
            // The Azure Cosmos DB endpoint for running this sample.
            private static readonly string EndpointUri = "<your endpoint here>";
            // The primary key for the Azure Cosmos account.
            private static readonly string PrimaryKey = "<your primary key>";
    
            // The Cosmos client instance
            private CosmosClient cosmosClient;
    
            // The database we will create
            private Database database;
    
            // The container we will create.
            private Container container;
    
            // The name of the database and container we will create
            private string databaseId = "FamilyDatabase";
            private string containerId = "FamilyContainer";
    
            public static async Task Main(string[] args)
            {
                try
                {
                    Console.WriteLine("Beginning operations...");
                    Program p = new Program();
                    await p.GetStartedDemoAsync();
                }
                catch (CosmosException de)
                {
                    Exception baseException = de.GetBaseException();
                    Console.WriteLine("{0} error occurred: {1}\n", de.StatusCode, de);
                }
                catch (Exception e)
                {
                    Console.WriteLine("Error: {0}\n", e);
                }
                finally
                {
                    Console.WriteLine("End of demo, press any key to exit.");
                    Console.ReadKey();
                }
            }
    
            /// <summary>
            /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
            /// </summary>
            public async Task GetStartedDemoAsync()
            {
                // Create a new instance of the Cosmos Client
                this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
                await this.CreateDatabaseAsync();
            }
    
            /// <summary>
            /// Create the database if it does not exist
            /// </summary>
            private async Task CreateDatabaseAsync()
            {
                // Create a new database
                this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
                Console.WriteLine("Created Database: {0}\n", this.database.Id);
            }
        }
    }
    
  3. F5 キーを押してアプリケーションを実行します。

    注意

    "503 service unavailable exception" (503 サービス利用不可の例外) エラーが表示される場合は、直接接続モードに必要なポートがファイアウォールによってブロックされている可能性があります。 この問題を解決するには、次のコードに示すように、必要なポートを開くか、ゲートウェイ モード接続を使用します。

      // Create a new instance of the Cosmos Client in Gateway mode
      this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey, new CosmosClientOptions()
             {
                 ConnectionMode = ConnectionMode.Gateway
             });
    

お疲れさまでした。 これで、Azure Cosmos データベースが正常に作成されました。

手順 5: コンテナーを作成する

警告

メソッド CreateContainerIfNotExistsAsync によって、価格に影響する新しいコンテナーが作成されます。 詳細については、価格のページを参照してください。

コンテナーは、CosmosDatabase クラスの CreateContainerIfNotExistsAsync または CreateContainerAsync メソッドのいずれかを使用して作成できます。 コンテナーは、項目 (SQL API の場合は JSON ドキュメント) および関連する JavaScript サーバー側アプリケーション ロジック (ストアド プロシージャ、ユーザー定義関数、トリガーなど) で構成されます。

  1. CreateContainerAsync メソッドをコピーし、CreateDatabaseAsync メソッドの下に貼り付けます。 CreateContainerAsync によって、LastName プロパティによってパーティション化されている containerId フィールドに指定された ID で新しいコンテナー (ID FamilyContainer) が作成されます (このコンテナーがまだ存在していない場合)。

    /// <summary>
    /// Create the container if it does not exist. 
    /// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
    /// </summary>
    /// <returns></returns>
    private async Task CreateContainerAsync()
    {
        // Create a new container
        this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
        Console.WriteLine("Created Container: {0}\n", this.container.Id);
    }
    
  2. CosmosClient をインスタンス化したところに、次のコードをコピーして貼り付けて、追加した CreateContainer メソッドを呼び出します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateContainerAsync();
    }
    
  3. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos コンテナーが作成されました。

手順 6: コンテナーに項目を追加する

CosmosContainer クラスの CreateItemAsync メソッドで項目を作成できます。 SQL API を使用すると、項目はドキュメントとして投影されます。これは、ユーザー定義の任意の JSON コンテンツです。 これで、Azure Cosmos コンテナーに項目を挿入できます。

まず、このサンプルの Azure Cosmos DB 内に格納されるオブジェクトを表す Family クラスを作成しましょう。 また、Family 内で使用されるサブクラス ParentChildPetAddress も作成します。 項目には、JSON で id としてシリアル化される Id プロパティが必要です。

  1. Ctrl + Shift + A キーを押して [新しい項目の追加] を開きます。 新しいクラス Family.cs をプロジェクトに追加します。

    プロジェクトに新しい Family.cs クラスを追加する画面のスクリーンショット

  2. FamilyParentChildPet、および Address クラスをコピーして Family.cs に貼り付けます。

    using Newtonsoft.Json;
    
    namespace CosmosGettingStartedTutorial
    {
        public class Family
        {
            [JsonProperty(PropertyName = "id")]
            public string Id { get; set; }
            public string LastName { get; set; }
            public Parent[] Parents { get; set; }
            public Child[] Children { get; set; }
            public Address Address { get; set; }
            public bool IsRegistered { get; set; }
            public override string ToString()
            {
                return JsonConvert.SerializeObject(this);
            }
        }
    
        public class Parent
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
        }
    
        public class Child
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
            public string Gender { get; set; }
            public int Grade { get; set; }
            public Pet[] Pets { get; set; }
        }
    
        public class Pet
        {
            public string GivenName { get; set; }
        }
    
        public class Address
        {
            public string State { get; set; }
            public string County { get; set; }
            public string City { get; set; }
        }
    }
    
  3. Program.cs に戻り、AddItemsToContainerAsync メソッドを CreateContainerAsync メソッドの後に追加します。

    /// <summary>
    /// Add Family items to the container
    /// </summary>
    private async Task AddItemsToContainerAsync()
    {
        // Create a family object for the Andersen family
        Family andersenFamily = new Family
        {
            Id = "Andersen.1",
            LastName = "Andersen",
            Parents = new Parent[]
            {
                new Parent { FirstName = "Thomas" },
                new Parent { FirstName = "Mary Kay" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FirstName = "Henriette Thaulow",
                    Gender = "female",
                    Grade = 5,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Fluffy" }
                    }
                }
            },
            Address = new Address { State = "WA", County = "King", City = "Seattle" },
            IsRegistered = false
        };
    
        try
        {
            // Read the item to see if it exists.  
            ItemResponse<Family> andersenFamilyResponse = await this.container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
            ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
        }
    
        // Create a family object for the Wakefield family
        Family wakefieldFamily = new Family
        {
            Id = "Wakefield.7",
            LastName = "Wakefield",
            Parents = new Parent[]
            {
                new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
                new Parent { FamilyName = "Miller", FirstName = "Ben" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FamilyName = "Merriam",
                    FirstName = "Jesse",
                    Gender = "female",
                    Grade = 8,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Goofy" },
                        new Pet { GivenName = "Shadow" }
                    }
                },
                new Child
                {
                    FamilyName = "Miller",
                    FirstName = "Lisa",
                    Gender = "female",
                    Grade = 1
                }
            },
            Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
            IsRegistered = true
        };
    
        try
        {
            // Read the item to see if it exists
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>(wakefieldFamily.Id, new PartitionKey(wakefieldFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", wakefieldFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.CreateItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", wakefieldFamilyResponse.Resource.Id, wakefieldFamilyResponse.RequestCharge);
        }
    }
    

    コードによって、同じ ID を持つ項目が存在していないことが確認されます。 2 つの項目を挿入します。1 つは Andersen Family の項目、もう 1 つは Wakefield Family の項目です。

  4. GetStartedDemoAsync メソッドに AddItemsToContainerAsync への呼び出しを追加します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.AddItemsToContainerAsync();
    }
    
  5. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos の項目が 2 つ作成されました。

手順 7: Azure Cosmos DB リソースを照会する

Azure Cosmos DB では、各コンテナーに格納された JSON ドキュメントに対する豊富なクエリがサポートされています。 詳細については、「SQL クエリの使用を開始する」をご覧ください。 次のサンプル コードを使用して、前の手順で挿入した項目に対してどのようにクエリを実行するかを説明します。

  1. QueryItemsAsync メソッドをコピーし、AddItemsToContainerAsync メソッドの後に貼り付けます。

    /// <summary>
    /// Run a query (using Azure Cosmos DB SQL syntax) against the container
    /// </summary>
    private async Task QueryItemsAsync()
    {
        var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";
    
        Console.WriteLine("Running query: {0}\n", sqlQueryText);
    
        QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
        FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);
    
        List<Family> families = new List<Family>();
    
        while (queryResultSetIterator.HasMoreResults)
        {
            FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
            foreach (Family family in currentResultSet)
            {
                families.Add(family);
                Console.WriteLine("\tRead {0}\n", family);
            }
        }
    }
    
  2. GetStartedDemoAsync メソッドに QueryItemsAsync への呼び出しを追加します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.QueryItemsAsync();
    }
    
  3. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos コンテナーに対するクエリが実行されました。

手順 8: JSON 項目を置換する

ここでは、Azure Cosmos DB 内の項目を更新します。 FamilyIsRegistered プロパティと子どもの 1 人の Grade を変更します。

  1. ReplaceFamilyItemAsync メソッドをコピーし、QueryItemsAsync メソッドの後に貼り付けます。

    /// <summary>
    /// Replace an item in the container
    /// </summary>
    private async Task ReplaceFamilyItemAsync()
    {
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
        var itemBody = wakefieldFamilyResponse.Resource;
        
        // update registration status from false to true
        itemBody.IsRegistered = true;
        // update grade of child
        itemBody.Children[0].Grade = 6;
    
        // replace the item with the updated content
        wakefieldFamilyResponse = await this.container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
        Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Resource);
    }
    
  2. GetStartedDemoAsync メソッドに ReplaceFamilyItemAsync への呼び出しを追加します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.ReplaceFamilyItemAsync();
    }
    
  3. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos 項目が置換されました。

手順 9: アイテムを削除する

ここでは、Azure Cosmos DB 内の項目を削除します。

  1. DeleteFamilyItemAsync メソッドをコピーし、ReplaceFamilyItemAsync メソッドの後に貼り付けます。

    /// <summary>
    /// Delete an item in the container
    /// </summary>
    private async Task DeleteFamilyItemAsync()
    {
        var partitionKeyValue = "Wakefield";
        var familyId = "Wakefield.7";
    
        // Delete an item. Note we must provide the partition key value and id of the item to delete
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
        Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
    }
    
  2. GetStartedDemoAsync メソッドに DeleteFamilyItemAsync への呼び出しを追加します。

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.DeleteFamilyItemAsync();
    }
    
  3. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos 項目が削除されました。

手順 10: データベースを削除する

ここでは、データベースを削除します。 作成したデータベースを削除すると、データベースとすべての子リソースが削除されます。 リソースには、コンテナー、項目、ストアド プロシージャ、ユーザー定義関数、およびトリガーがあります。 また、CosmosClient インスタンスも破棄します。

  1. DeleteDatabaseAndCleanupAsync メソッドをコピーし、DeleteFamilyItemAsync メソッドの後に貼り付けます。

    /// <summary>
    /// Delete the database and dispose of the Cosmos Client instance
    /// </summary>
    private async Task DeleteDatabaseAndCleanupAsync()
    {
        DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
        // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();
    
        Console.WriteLine("Deleted Database: {0}\n", this.databaseId);
    
        //Dispose of CosmosClient
        this.cosmosClient.Dispose();
    }
    
  2. GetStartedDemoAsync メソッドに DeleteDatabaseAndCleanupAsync への呼び出しを追加します。

    /// <summary>
    /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    /// </summary>
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
        await this.DeleteFamilyItemAsync();
        await this.DeleteDatabaseAndCleanupAsync();
    }
    
  3. F5 キーを押してアプリケーションを実行します。

お疲れさまでした。 これで、Azure Cosmos データベースが削除されました。

手順 11: C# コンソール アプリケーションの全体的な実行の流れ

Visual Studio で F5 キーを押すと、アプリケーションがビルドされデバッグ モードで実行します。

アプリケーション全体の出力がコンソール ウィンドウに表示されます。 出力には、追加したクエリの結果が表示されます。 それは、次のテキスト例のようなものになるはずです。

Beginning operations...

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.43 RUs.

Created item in database with id: Wakefield.7 Operation consumed 14.29 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"},{"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6,"Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1,"Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

お疲れさまでした。 チュートリアルが完了し、実際に動作する C# コンソール アプリケーションが完成しました。

チュートリアルのソリューションの完全版を入手する

このチュートリアルの手順を実行する時間がない場合や、コード サンプルをダウンロードするだけの場合は、それをダウンロードできます。

GetStarted ソリューションを構築するには、次の前提条件を満たしておく必要があります。

  • アクティブな Azure アカウントアカウントがない場合、Azure 試用版にサインアップして、最大 10 件の無料 Mobile Apps を入手できます。 お持ちでない場合は、 無料アカウントにサインアップしてください。
  • Azure Cosmos DB アカウント
  • GitHub で入手可能な GetStarted ソリューション。

Visual Studio で Azure Cosmos DB .NET SDK への参照を復元するには、ソリューション エクスプローラー でソリューションを右クリックし、 [NuGet パッケージの復元] を選択します。 次に、App.config ファイルで、EndPointUriPrimaryKey の値を更新します。この手順については、「手順 3:Azure Cosmos DB アカウントに接続する」を参照してください。

以上です。ビルドすれば完了です。

次のステップ