ASP.NET Web API 2.1 での BSON サポート

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

このトピックでは、Web API コントローラー (サーバー側) と .NET クライアントアプリで BSON を使用する方法について説明します。 Web API 2.1 では、BSON のサポートが導入されています。

BSON とは

BSON はバイナリシリアル化形式です。 "BSON" は "バイナリ JSON" を表しますが、BSON と JSON は非常に異なる方法でシリアル化されます。オブジェクトは JSON と同様に名前と値のペアとして表されるため、BSON は "JSON に似ています"。 JSON とは異なり、数値データ型は文字列ではなくバイトとして格納されます

BSON は、軽量でスキャンが簡単で、エンコード/デコードが高速に行われるよう設計されています。

BSON のサイズは JSON に相当します。データによっては、BSON ペイロードのサイズが、JSON ペイロードより増減する可能性があります。イメージファイルなどのバイナリデータをシリアル化する場合、バイナリデータは base64 でエンコードされていないため、BSON は JSON よりも小さくなります。
BSON ドキュメントは、要素の前に長さフィールドが付いているため、スキャンが簡単であるため、パーサーは要素をデコードせずにスキップできます。
数値データ型は文字列ではなく数値として格納されるため、エンコードとデコードは効率的です。

.NET クライアントアプリなどのネイティブクライアントでは、JSON や XML などのテキストベースの形式の代わりに BSON を使用するとメリットがあります。 JavaScript は JSON ペイロードを直接変換できるため、ブラウザークライアントの場合は、JSON を使用する必要があります。

幸いなことに、Web API はコンテンツネゴシエーションを使用するため、API は両方の形式をサポートし、クライアントが選択できるようにします。

サーバーでの BSON の有効化

Web API 構成で、BsonMediaTypeFormatter をフォーマッタコレクションに追加します。

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Formatters.Add(new BsonMediaTypeFormatter());

        // Other Web API configuration not shown...
    }
}

クライアントが "application/bson" を要求すると、Web API は BSON フォーマッタを使用します。

BSON を他のメディアの種類に関連付けるには、それらを SupportedMediaTypes コレクションに追加します。次のコードは、サポートされているメディアの種類に "application/vnd.contoso" を追加します。

var bson = new BsonMediaTypeFormatter();
bson.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/vnd.contoso"));
config.Formatters.Add(bson);

HTTP セッションの例

この例では、次のモデルクラスと単純な Web API コントローラーを使用します。

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
    public decimal Price { get; set; }
    public DateTime PublicationDate { get; set; }
}

public class BooksController : ApiController
{
    public IHttpActionResult GetBook(int id)
    {
        var book = new Book()
        {
            Id = id,
            Author = "Charles Dickens",
            Title = "Great Expectations",
            Price = 9.95M,
            PublicationDate = new DateTime(2014, 1, 20)
        };

        return Ok(book);
    }
}

クライアントは、次の HTTP 要求を送信する場合があります。

GET http://localhost:15192/api/books/1 HTTP/1.1
User-Agent: Fiddler
Host: localhost:15192
Accept: application/bson

応答を次に示します。

HTTP/1.1 200 OK
Content-Type: application/bson; charset=utf-8
Date: Fri, 17 Jan 2014 01:05:40 GMT
Content-Length: 111

.....Id......Title.....Great Expectations..Author.....Charles Dickens..Price..........PublicationDate.........

ここでは、バイナリデータを "." 文字に置き換えます。 Fiddler の次のスクリーンショットは、生の 16 進値を示しています。

HttpClient での BSON の使用

.NET クライアントアプリでは、HttpClientで BSON フォーマッタを使用できます。 HttpClient の詳細については、「.NET クライアントからの Web API の呼び出し」を参照してください。

次のコードは、BSON を受け入れる GET 要求を送信し、応答で BSON ペイロードを逆シリアル化します。

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost");

        // Set the Accept header for BSON.
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        // Send GET request.
        result = await client.GetAsync("api/books/1");
        result.EnsureSuccessStatusCode();

        // Use BSON formatter to deserialize the result.
        MediaTypeFormatter[] formatters = new MediaTypeFormatter[] {
            new BsonMediaTypeFormatter()
        };

        var book = await result.Content.ReadAsAsync<Book>(formatters);
    }
}

サーバーから BSON を要求するには、Accept ヘッダーを "application/bson" に設定します。

client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new  
    MediaTypeWithQualityHeaderValue("application/bson"));

応答本文を逆シリアル化するには、BsonMediaTypeFormatter を使用します。このフォーマッタは既定のフォーマッタコレクションに含まれていないため、応答本文を読み取るときに指定する必要があります。

MediaTypeFormatter[] formatters = new MediaTypeFormatter[] {
    new BsonMediaTypeFormatter()
};

var book = await result.Content.ReadAsAsync<Book>(formatters);

次の例では、BSON を含む POST 要求を送信する方法を示します。

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost:15192");

        // Set the Accept header for BSON.
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        var book = new Book()
        {
            Author = "Jane Austen",
            Title = "Emma",
            Price = 9.95M,
            PublicationDate = new DateTime(1815, 1, 1)
        };

        // POST using the BSON formatter.
        MediaTypeFormatter bsonFormatter = new BsonMediaTypeFormatter();
        var result = await client.PostAsync("api/books", book, bsonFormatter);
        result.EnsureSuccessStatusCode();
    }
}

このコードの多くは、前の例と同じです。ただし、PostAsync メソッドでは、フォーマッタとして BsonMediaTypeFormatter を指定します。

MediaTypeFormatter bsonFormatter = new BsonMediaTypeFormatter();
var result = await client.PostAsync("api/books", book, bsonFormatter);

最上位プリミティブ型のシリアル化

すべての BSON ドキュメントは、キーと値のペアの一覧です。BSON 仕様では、整数や文字列などの 1 つの生の値をシリアル化するための構文は定義されていません。

この制限を回避するために、BsonMediaTypeFormatter はプリミティブ型を特殊なケースとして扱います。シリアル化する前に、値をキー "Value" を使用してキーと値のペアに変換します。たとえば、API コントローラーから整数が返されたとします。

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return Ok(42);
    }
}

シリアル化する前に、BSON フォーマッタはこれを次のキーと値のペアに変換します。

{ "Value": 42 }

逆シリアル化すると、フォーマッタはデータを元の値に戻します。ただし、Web API が生の値を返す場合は、別の BSON パーサーを使用するクライアントがこのケースを処理する必要があります。一般に、生の値ではなく、構造化データを返すことを検討する必要があります。

その他のリソース

Web API BSON サンプル

メディアフォーマッタ

次の方法で共有

ASP.NET Web API 2.1 での BSON サポート

BSON とは

サーバーでの BSON の有効化

HTTP セッションの例

HttpClient での BSON の使用

最上位プリミティブ型のシリアル化

その他のリソース

フィードバック

その他のリソース