マイクロソフトは、Azure SDK の 2 回目のプレビューの提供を開始しました。最新の Azure API ガイドラインとパターンに沿って作成された、.Net (英語)、Java (英語)、JavaScript (英語)、Python (英語) 用の SDK です。このプレビューには、バグ修正と新機能が含まれているほか、ガイドライン準拠のための追加の処理がされています。

新機能

この SDK には、多くの新機能、バグ修正、機能強化が含まれています。以下はその新機能の一部です。詳細については、上の各リンク先のリリース ノートや変更ログを確認してください。

• Java 用ストレージ ライブラリに、ファイルとキューのサポートを追加
• Python 用ストレージ ライブラリに、ファイル、キュー、BLOB 用の非同期バージョンの API を追加
• 各言語の Event Hubs ライブラリで、単一呼び出しで複数のメッセージを送信する場合のサポートを拡張。呼び出しがサイズ制限を越えるというエラー シナリオを回避するバッチの作成機能を追加し、帯域幅を懸念している開発者がバッチ サイズを制御できるようにしました。
• 各言語の Event Hubs ライブラリに、EventProcessor クラスを介してイベントを消費するための新しいモデルを導入。これにより、現在のチェックポイント処理のプロセスが簡素化されます。また今後のプレビューでは、パーティション間で負荷分散が処理されるようになります。

ガイドラインの詳細: 一貫性について

この Azure SDK には、さまざまなプラットフォームを使用するすべての開発者に人間工学に基づくエクスペリエンスを提供するために、組織をまたいで行った取り組みの成果が反映されています。以前のブログ記事でお伝えしたとおり、開発者からのフィードバックを参考に、次の原則を定義しました。

• 自然さ
• 一貫性
• 使いやすさ
• 診断可能性
• 互換性

今回は、一貫性について取り上げたいと思います。

一貫性

開発者からのフィードバックやユーザーへの調査の結果、各種 API の一貫性が高いほど学習がしやすく、覚えたことを忘れにくいことがわかりました。これを受け、Azure SDK の一貫性を高めるために、ガイドラインに次の一貫性の原則 (英語) を盛り込みました。

• クライアント ライブラリは、その言語内で一貫性が維持され、そのサービスとの一貫性が維持され、すべてのターゲット言語間で一貫性が維持されるようにする。矛盾が生じる場合は、言語内の一貫性を最優先し、すべてのターゲット言語間での一貫性は優先度を最も低くする。
• ログ、HTTP 通信、エラー処理などのサービスに依存しない概念の一貫性を維持する。これにより、開発者が別のクライアント ライブラリに切り替えても、概念を学習し直さずに済む。
• 診断しやすくするために、クライアント ライブラリとサービスの間で用語の一貫性を維持する。
• サービスとクライアント ライブラリの間で違いが生じる場合は、これまで自然に使われてきたという正当かつ明確な理由が存在する必要がある。
• 各ターゲット言語用の Azure SDK は、1 つのチームが開発した単一の製品であると認識されるようにする。
• どのターゲット言語でも、機能を同等にする。これは、サービスと機能が同等であるよりも重要。

では、2 つ目に掲げられている、「ログ、HTTP 通信、エラー処理などのサービスに依存しない概念の一貫性」について詳しく見ていきましょう。開発者が指摘したのは、各 API はそれぞれ問題なく機能するものの、API 間では必ずしも概念が一貫しているわけではないという点でした。以下はその一例です。

Blob Storage: Skip/Take のページングを使用して、結果セットとして同期反復子を返した

let marker = undefined;
do {
   const listBlobsResponse = await containerURL.listBlobFlatSegment(
     Aborter.none,
     marker
   );

  marker = listBlobsResponse.nextMarker;
   for (const blob of listBlobsResponse.segment.blobItems) {
     console.log(`Blob: ${blob.name}`);
   }
} while (marker);

 

Cosmos DB: 非同期反復子を使用して、結果を返した

for await (const results of this.container.items.query(querySpec).getAsyncIterator()){
         console.log(results.result)
      }

 

Event Hubs: 「Take」方式の呼び出しを使用して、指定されたサイズの結果の配列を返した

const myEvents = await client.receiveBatch("my-partitionId", 10);

 

これら 3 つのサービスを利用する開発者は、サービスごとにコード サンプルをチェックするなどして、仕様を思い出したり、新たに覚え直したりする必要がありました。

SDK の一貫性ガイドライン

JavaScript のガイドライン (英語) の「Modern & Idiomatic JavaScript」セクションには、このような場合にどう処理すべきかが示されています。

☑️ 非同期ライブラリ API を実装する際は、非同期関数を使用すること

ES5 をサポートする必要があり、ライブラリ サイズを気にする場合は、非同期コードと制御フロー構造を組み合わせるときに非同期関数を使用します。コード フローをよりシンプルにするには、Promise を使用してください。  非同期関数はトランスパイリング時にコードが肥大化します (特に ES5 をターゲットとする場合)。

☑️ あらゆる種類のシーケンスとストリームに、反復子と非同期反復子を使用すること

反復子と非同期反復子はどちらも JavaScript に組み込まれており、簡単に使用できます。他のストリーミング インターフェイス (ノード ストリームなど) は、普段から使用している場合に限り、使用してもかまいません。

つまり、非同期呼び出しがシーケンス (リスト) となっている場合は、非同期反復子が推奨されます。

実際に、Blob Storage、Cosmos DB、Event Hubs の最新の Azure SDK ライブラリにこの原則を適用したところ、次のようになりました。

Blob Storage: 非同期反復子を使用して、BLOB をリスト化
for await (const blob of containerClient.listBlobsFlat()) {
   console.log(`Blob: ${blob.name}`);
}

 

Cosmos, still using async iterators to list items:
for await (const resources of resources.
                                 container.
                                 items.
                                 readAll({ maxItemCount: 20 }).
                                 getAsyncIterator()) {
     console.log(resources.doc.id)
}

 

Event Hubs: 非同期反復子を使用して、イベントを処理
for await (const events of consumer.getEventIterator()){
     console.log(`${events}`)
   }

このように、「サービスに依存しない概念」 (このケースでは、ページング) が、3 つのサービスで統一されました。

フィードバックにご協力ください

今回の一貫性の記事についてぜひフィードバックをお寄せください。また、2019 年 8 月のプレビュー (英語) (.Net、Java、JavaScript、Python) を試してバグを見つけた場合は、GitHub (ガイドライン、.Net、Java、JavaScript、Python) で Issue を作成するかプル リクエストを使ってご報告ください。最新情報は、Twitter (@AzureSDK) でもご確認ください。ガイドラインとライブラリの改善にぜひご協力をお願いいたします。