Xamarin.Forms での Azure Cosmos DB ドキュメントデータベースの使用

[アーティクル]
04/29/2024

Azure Cosmos DB ドキュメントデータベースは、JSON ドキュメントへの低待機時間アクセスを提供する NoSQL データベースであり、シームレスなスケールとグローバルレプリケーションを必要とするアプリケーションに対して、高速、高可用性、スケーラブルなデータベースサービスを提供します。この記事では、Azure Cosmos DB .NET Standard クライアントライブラリを使用して、Azure Cosmos DB ドキュメントデータベースを Xamarin.Forms アプリケーションに統合する方法について説明します。

Microsoft Azure Cosmos DB の動画

Azure Cosmos DB ドキュメントデータベースアカウントは、Azure サブスクリプションを使用してプロビジョニングできます。各データベースアカウントは、0 個以上のデータベースを持つことができます。 Azure Cosmos DB のドキュメントデータベースは、ドキュメントコレクションとユーザーの論理コンテナーです。

Azure Cosmos DB ドキュメントデータベースには、0 個以上のドキュメントコレクションが含まれている場合があります。ドキュメントコレクションごとに異なるパフォーマンスレベルを持つ可能性があり、頻繁にアクセスされるコレクションに対してより高いスループットを指定でき、アクセス頻度の低いコレクションのスループットは低くなります。

各ドキュメントコレクションは、0 個以上の JSON ドキュメントで構成されます。コレクション内のドキュメントはスキーマフリーであるため、同じ構造またはフィールドを共有する必要はありません。ドキュメントがドキュメントコレクションに追加されると、Azure Cosmos DB によって自動的にインデックスが作成され、クエリを実行できるようになります。

開発目的で、ドキュメントデータベースをエミュレーターを介して使用することもできます。エミュレーターを使用すると、Azure サブスクリプションを作成したり、コストを発生させたりすることなく、アプリケーションをローカルで開発およびテストできます。エミュレーターの詳細については、Azure Cosmos DB エミュレーターを使用したローカルでの開発に関するページを参照してください。

この記事とそれに付随するサンプルアプリケーションでは、タスクが Azure Cosmos DB ドキュメントデータベースに格納されている Todo リストアプリケーションを示します。サンプルアプリケーションの詳細については、サンプルについての理解に関するページを参照してください。

Azure Cosmos DB の詳細については、「Azure Cosmos DB のドキュメント」を参照してください。

Note

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

段取り

Azure Cosmos DB ドキュメントデータベースを Xamarin.Forms アプリケーションに統合するプロセスは次のとおりです。

Azure Cosmos DB アカウントを作成する。詳細については、Azure Cosmos DB アカウントの作成に関する記事を参照してください。
Xamarin.Forms ソリューション内のプラットフォームプロジェクトに Azure Cosmos DB .NET Standard クライアントライブラリの NuGet パッケージを追加します。
Azure Cosmos DB アカウントにアクセスするクラスに、Microsoft.Azure.Documents、Microsoft.Azure.Documents.Client、Microsoft.Azure.Documents.Linq 名前空間の using ディレクティブを追加します。

これらの手順を実行した後、Azure Cosmos DB .NET Standard クライアントライブラリを使用して、ドキュメントデータベースに対する要求を構成および実行できます。

Note

Azure Cosmos DB .NET Standard クライアントライブラリは、プラットフォームプロジェクトにのみインストールでき、ポータブルクラスライブラリ (PCL) プロジェクトにはインストールできません。そのため、コードの重複を避けるために、サンプルアプリケーションは共有アクセスプロジェクト (SAP) になっています。ただし、このDependencyService クラスを PCL プロジェクトで使用して、プラットフォーム固有のプロジェクトに含まれる Azure Cosmos DB .NET Standard クライアントライブラリコードを呼び出すことができます。

Azure Cosmos DB アカウントを使用する

この DocumentClient 型は、Azure Cosmos DB アカウントへのアクセスに使用されるエンドポイント、資格情報、接続ポリシーをカプセル化し、アカウントに対する要求を構成および実行できます。次のコード例は、このクラスのインスタンスを作成する方法について示しています。

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

Azure Cosmos DB URI と主キーを DocumentClient コンストラクターに提供する必要があります。これらは、Azure Portal で取得できます。詳細については、Azure Cosmos DB アカウントへの接続に関するページを参照してください。

データベースの作成

ドキュメントデータベースは、ドキュメントコレクションとユーザーの論理コンテナーであり、Azure Portal で作成することも、次のように DocumentClient.CreateDatabaseIfNotExistsAsync メソッドを使用してプログラムで作成することもできます。

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

この CreateDatabaseIfNotExistsAsync メソッドは、Database オブジェクトを引数として指定し、Database オブジェクトはデータベース名をその Id プロパティとして指定します。この CreateDatabaseIfNotExistsAsync メソッドは、データベースが存在しない場合は作成し、既に存在する場合はそのデータベースを返します。ただし、サンプルアプリケーションでは、CreateDatabaseIfNotExistsAsync メソッドによって返されるデータはすべて無視されます。

Note

この CreateDatabaseIfNotExistsAsync メソッドは Task<ResourceResponse<Database>> オブジェクトを返し、応答の状態コードをチェックして、データベースが作成されたか、既存のデータベースが返されたかを判断できます。

ドキュメントコレクションを作成する

ドキュメントコレクションは JSON ドキュメントのコンテナーであり、Azure Portal で作成することも、次のように DocumentClient.CreateDocumentCollectionIfNotExistsAsync メソッドを使用してプログラムで作成することもできます。

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

この CreateDocumentCollectionIfNotExistsAsync メソッドには、必須の 2 つの引数 (Uri として指定されたデータベース名と DocumentCollection オブジェクト) が必要です。 DocumentCollection オブジェクトは、Id プロパティで名前が指定されたドキュメントコレクションを表します。この CreateDocumentCollectionIfNotExistsAsync メソッドは、ドキュメントコレクションが存在しない場合は作成し、既に存在する場合はそのドキュメントコレクションを返します。ただし、サンプルアプリケーションでは、CreateDocumentCollectionIfNotExistsAsync メソッドによって返されるデータはすべて無視されます。

Note

この CreateDocumentCollectionIfNotExistsAsync メソッドは Task<ResourceResponse<DocumentCollection>> オブジェクトを返し、応答の状態コードをチェックして、ドキュメントコレクションが作成されたか、既存のドキュメントコレクションが返されたかを判断できます。

必要に応じて、この CreateDocumentCollectionIfNotExistsAsync メソッドは、Azure Cosmos DB アカウントに発行された要求に対して指定できるオプションをカプセル化する RequestOptions オブジェクトを指定することもできます。この RequestOptions.OfferThroughput プロパティは、ドキュメントコレクションのパフォーマンスレベルを定義するために使用され、サンプルアプリケーションでは 1 秒あたり 400 要求ユニットに設定されます。コレクションに頻繁にアクセスするか、アクセス頻度が低いかに応じて、この値を増減する必要があります。

重要

CreateDocumentCollectionIfNotExistsAsync メソッドでは、予約済みスループットを使って新しいコレクションが作成されることに注意してください。これは、価格に影響します。

ドキュメントコレクションのドキュメントの取得

ドキュメントコレクションの内容は、ドキュメントクエリを作成して実行することで取得できます。ドキュメントクエリは、次のように DocumentClient.CreateDocumentQuery メソッドを使用して作成されます。

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

このクエリは、指定したコレクションからすべてのドキュメントを非同期で取得し、ドキュメントを List<TodoItem> コレクションに配置して表示します。

この CreateDocumentQuery<T> メソッドは、ドキュメントに対してクエリを実行する必要があるコレクションを表す Uri 引数を指定します。この例では、collectionLink 変数は、ドキュメントを取得するドキュメントコレクションを表す Uri を指定するクラスレベルのフィールドです。

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

この CreateDocumentQuery<T> メソッドは、同期的に実行されるクエリを作成し、IQueryable<T> オブジェクトを返します。しかし、AsDocumentQuery メソッドは、IQueryable<T> オブジェクトを非同期で実行できる IDocumentQuery<T> オブジェクトに変換します。非同期クエリは、クエリから返される追加の結果があるかどうかを示す IDocumentQuery<T>.HasMoreResults プロパティとともに、ドキュメントデータベースから結果の次のページを取得する IDocumentQuery<T>.ExecuteNextAsync メソッドを使用して実行されます。

ドキュメントは、ドキュメントコレクションに対するクエリにフィルター述語を適用する Where 句をクエリに含めることで、サーバー側でフィルター処理できます。

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

このクエリは、Done プロパティが false と等しいコレクションからすべてのドキュメントを取得します。

ドキュメントコレクションにドキュメントを挿入する

ドキュメントはユーザー定義の JSON コンテンツであり、DocumentClient.CreateDocumentAsync メソッドを使用してドキュメントコレクションに挿入できます。

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

この CreateDocumentAsync メソッドは、ドキュメントを挿入するコレクションを表す Uri 引数と、挿入するドキュメントを表す object 引数を指定します。

ドキュメントコレクション内のドキュメントを置き換える

ドキュメントコレクション内のドキュメントは、次の DocumentClient.ReplaceDocumentAsync メソッドで置き換えることができます。

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

この ReplaceDocumentAsync メソッドは、置き換える必要があるコレクション内のドキュメントを表す Uri 引数と、更新されたドキュメントデータを表す object 引数を指定します。

ドキュメントコレクションからドキュメントを削除する

ドキュメントは、次の DocumentClient.DeleteDocumentAsync メソッドを使用してドキュメントコレクションから削除できます。

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

この DeleteDocumentAsync メソッドは、削除する必要があるコレクション内のドキュメントを表す Uri 引数を指定します。

ドキュメントコレクションを削除する

ドキュメントコレクションは、次の DocumentClient.DeleteDocumentCollectionAsync メソッドを使用してデータベースから削除できます。

await client.DeleteDocumentCollectionAsync(collectionLink);

この DeleteDocumentCollectionAsync メソッドは、削除するドキュメントコレクションを表す Uri 引数を指定します。このメソッドを呼び出すと、コレクションに格納されているドキュメントも削除されることに注意してください。

データベースを削除する

データベースは、DocumentClient.DeleteDatabaesAsync メソッドを使用して Azure Cosmos DB データベースアカウントから削除できます。

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

この DeleteDatabaseAsync メソッドは、削除するデータベースを表す Uri 引数を指定します。このメソッドを呼び出すと、データベースに格納されているドキュメントコレクションと、ドキュメントコレクションに格納されているドキュメントも削除されることに注意してください。

まとめ

この記事では、Azure Cosmos DB .NET Standard クライアントライブラリを使用して、Azure Cosmos DB ドキュメントデータベースを Xamarin.Forms アプリケーションに統合する方法について説明しました。 Azure Cosmos DB ドキュメントデータベースは、JSON ドキュメントへの低待機時間アクセスを提供する NoSQL データベースであり、シームレスなスケールとグローバルレプリケーションを必要とするアプリケーションに対して、高速、高可用性、スケーラブルなデータベースサービスを提供します。

Xamarin.Forms での Azure Cosmos DB ドキュメント データベースの使用

段取り

Azure Cosmos DB アカウントを使用する

データベースの作成

ドキュメント コレクションを作成する

ドキュメント コレクションのドキュメントの取得

ドキュメント コレクションにドキュメントを挿入する

ドキュメント コレクション内のドキュメントを置き換える

ドキュメント コレクションからドキュメントを削除する

ドキュメント コレクションを削除する

データベースを削除する

まとめ

関連リンク

その他のリソース

Xamarin.Forms での Azure Cosmos DB ドキュメントデータベースの使用

ドキュメントコレクションを作成する

ドキュメントコレクションのドキュメントの取得

ドキュメントコレクションにドキュメントを挿入する

ドキュメントコレクション内のドキュメントを置き換える

ドキュメントコレクションからドキュメントを削除する

ドキュメントコレクションを削除する