curl と Visual Studio Code を利用して Microsoft Learn Catalog API の使用を開始する

[アーティクル]
03/30/2023

この記事では、curl と Visual Studio Code を利用して Microsoft Learn Catalog API の使用を開始する方法を説明します。この API の詳細やユースケースについてあまり詳しくない場合は、まず Learn Catalog API の機能の概要の記事をご覧になることをお勧めします。

ここで説明するプロセスの概要は次のとおりです。

Learn Catalog API に対してクエリを実行する
初期応答をレビューする
応答を "整形" する
スプレッドシートに変換する
その他のクエリを試す

Learn Catalog API を自分のニーズに合わせて使用するようになると、使用したいツールセットやニーズに合わせてこの手順に多少の変更を加えることが必要になる場合がありますが、使用のためのプロセスは一般的にどのユースケースでも同じです。

前提条件

この記事で示す手順に従うには、curl と Visual Studio Code が必要です (この 2 つの無料ツールは API に対するクエリの実行によく利用されています)。

curl と Visual Studio Code が既にインストールされている場合は、"Learn Catalog API に対してクエリを実行する" のセクションに進んでください。
まだインストールされていない場合は、次のセクションの手順に従ってください。

curl をダウンロードしてセットアップする

curl は、広く利用されている無料でオープンソースのコマンドラインツールであり、API に対してクエリを実行することができます。

curl ダウンロードのページに移動し、ご自身の環境に適したパッケージをダウンロードします。どれを選択すればよいかが不明の場合は、curl ダウンロードウィザードを使用してください。
アプリケーションをインストールし、プロンプトに従って構成します。この記事のために、あるいは Learn Catalog API に対するクエリ実行のために必要な固有の設定はありません。

Visual Studio Code をダウンロードしてセットアップする

Visual Studio Code は、Microsoft が作成した無料のパワフルなコードエディターです。

Visual Studio Code のサイトに移動し、ご自身の環境に適したパッケージをダウンロードします。
アプリケーションをインストールし、プロンプトに従って構成します。

Learn Catalog API に対してクエリを実行する

Learn Catalog API を使用するにあたって認証は必要ないため、curl 対応の任意のコマンドラインから API エンドポイントに対するクエリを実行できます。この演習では、Visual Studio Code の中のターミナルを使用します。

Visual Studio Code を開きます。
上部のナビゲーションで [ターミナル] を選択します。
[新しいターミナル] を選択して新しいコマンドターミナルを開きます。
好みのターミナル (Bash、CMD など) を選択して、下記のコマンドを入力します。下記のコマンドは、curl を使用することと、フィルター処理なしの Learn Catalog API エンドポイントを呼び出すこと、および応答は "output.json" という名前のファイルに出力することを示しています。このファイルの場所は、ターミナルに表示されるファイルパスで定義されます (例: C:\Users\<username>)。

curl https://learn.microsoft.com/api/catalog >> output.json

要求が成功した場合は、ファイルの合計サイズに関する情報が表示されます (たとえば 13.1 M ですが、サイズは応答のサイズに応じて変化する可能性があります)。失敗した場合は、エラーが返されます。

Note

output.json を使用する作業が完了したらこのファイルを削除するか、より適切な名前に変更してください。同じファイル名を使用して再び API に対するクエリを実行すると、既存のファイル内に応答が追加されます。もう 1 つの選択肢は、ファイルが一意になるような名前を最初のクエリコマンドの実行時に付けて、たとえば、"output-1212.json" または "output-de-de-2022-12-12.json" などとすることです。

初期応答をレビューする

初期応答は JSON 形式であり、"最小化" されます。つまり、ファイルを小さくするために特定のスペース、行、タブが削除されます。

Visual Studio Code で [ファイル] を選択します。
[ファイルを開く] を選択します。
前のセクションで作成された "output.json" ファイルの場所に移動します。

この最小化は標準的に行われていることであり、ファイルを読みやすくするために Visual Studio Code のコマンドで "整形" することができますが、これを次のセクションで行います。

応答を整形する

Visual Studio Code で "output.json" ファイルを開いた状態で、Ctrl + Shift + I キーを押します。

JSON が更新されて複数の行に分割され、より読みやすい形式になるはずです。応答内のさまざまなプロパティと値の情報については、Learn Catalog API 開発者リファレンスの記事でデータディクショナリを参照してください。

応答をスプレッドシートに変換する

Learn Catalog API を使用する人の多くは、システムに統合することではなく、個々のタスクまたはレビューを目的としています。このようなユースケースでは、JSON 応答を CSV または Excel 形式に変換してスプレッドシートとして表示すると便利な場合があります。任意の変換ツールを使用できますが、ここでは Flatfile の Json to CSV コンバーターを使用します。

https://csvjson.com/json2csv に移動します。
出力ファイルをアップロードします。
[変換] を選択します。
[ダウンロード] を選択します。

Note

外部のオンラインツールを使用してデータを変換するときは十分な注意を払い、どのようなデータを送ろうとしているかをよく考えてください。 Learn Catalog API の場合は、応答が一般公開されており、認証は必要ないため、形式の変換に役立てるためにオンラインツールを使用しても問題はありません。

その他のクエリを試す

上記の手順に従って、その他のクエリを試してください。例を以下に示します。それぞれの応答ファイルサイズの変化と、その中のオブジェクトの違いを観察してください。

説明	クエリ
Learn Catalog API のすべての項目	`https://learn.microsoft.com/api/catalog/`
すべてのスペイン語モジュール	`https://learn.microsoft.com/api/catalog/?locale=es-es&type=modules`
人気スコアが 0.9 以上のすべてのモジュール	`https://learn.microsoft.com/api/catalog/?type=modules&popularity>0.9`
すべての初心者向けセキュリティトレーニングオブジェクトと認定オブジェクト	`https://learn.microsoft.com/api/catalog/?level=beginner&subject=security`
人気スコアが 0.5 を超え、先月に更新されたすべての高度なアクセシビリティモジュール	`https://learn.microsoft.com/api/catalog/?level=advanced&subject=accessibility&popularity>0.5&last_modified=gte 2022-10-01`

次のステップ

今後の開発に役立てるために、以下のリソースを確認することをお勧めします。