Microsoft Learn Platform API の使用方法

Last updated at 2026-05-18Posted at 2026-05-18

はじめに

今回使用した Microsoft Learn Platform API について、使い方を整理します。

最初にざっくりの説明です。

Search API: キーワード検索して結果を返す
Catalog API: Learn の学習コンテンツを構造化データとして取得する

この2つだけ覚えておけば、まずは迷いにくくなります。

正直、最初に触ったときは「Search と Catalog の違いって何?」「認証ってどこまで必要?」で少し混乱しました。この記事は、同じところで詰まりやすい人向けに、できるだけかみ砕いて書いています。

このAPIで何ができるか

キーワード検索できる（Search API）
モジュールや学習パスの一覧を取得できる（Catalog API）
条件付きで絞り込みできる（Catalog API の filters）
1件の詳細情報を構造化データとして確認できる（Catalog API）
本文は返却 URL 先で読む

まず3分で全体像

Microsoft Learn API は、Microsoft Learn 上の学習コンテンツを「探す」「取得する」ための API 群です。

大きく2系統です。

Search API
- ほしい情報をその場で探すための API
- 例: 「Azure AI の日本語記事を10件ほしい」
Catalog API
- 学習コンテンツの構造化メタデータを一覧・詳細・フィルタ付きで取得する API
- 例: 「modules の一覧を取りたい」「特定条件の learning paths を絞り込みたい」
- 同期用途にも使えるが、まずは「構造化された学習データを取る API」と考えるとわかりやすい

イメージとしては、

Search = サイト内検索
Catalog = カタログ形式で構造化データを取る

です。

返り値のイメージを先に1行でいうと、

Search API は検索結果の一覧を返す
Catalog API は学習コンテンツの構造化データを返す
どちらも本文そのものを返すというより、コンテンツへの入口 URL やメタデータを返す

Catalog 系には、全体の入口となる URL と、各リソースを個別に取る URL があります。

入口: /api/catalog/
リソース単位: /api/v1/{resource}

どちらも Catalog 系で、別系統ではありません。実務では modules や learning-paths など、リソース単位の取得を使うことが多いです。

用語をやさしく整理

Catalog でよく出る言葉を、普段の言葉で言い換えると次の通りです。

Module
- 1つの学習単元（1章分、1レッスン分のイメージ）
Learning path
- 複数の Module をまとめた学習コース
Role
- 想定される職種（例: AIエンジニア、開発者）
Skill
- 身につけたい能力の分類
Subject
- 扱うテーマ・分野（例: identity、security など）

混乱しやすい3つを短く分けると次の通りです。

Role = どんな仕事向けか
Skill = どんな能力を伸ばすか
Subject = どんなテーマ・分野か

Learnのサイト内では以下のようにまとめられていますね！

☝Module

☝Learning Path

☝Role (AIエンジニア)

Search API: まずはここから

Search API は Learn 内のページ検索です。最初の1本として一番触りやすいです。

☝このようなドキュメント/トレーニングページのURLが返ってきます。

基本形

GET https://learn.microsoft.com/api/search?search={query}&$top={n}&$skip={offset}&locale={locale}

オプション

search
- 検索キーワード。必須
- 例: azure ai、ai-102
$top
- 何件返すか
- 例: 10なら上位10件
$skip
- 何件読み飛ばすか（ページ送りに使う）
- 例: 1ページ10件で2ページ目なら $skip=10
locale
- 言語/地域
- 例: ja-jp, en-us

具体例

https://learn.microsoft.com/api/search?search=azure+ai&locale=ja-jp&$top=10

「azure ai」で日本語コンテンツを10件検索

https://learn.microsoft.com/api/search?search=ai-102&locale=en-us&$top=10

「ai-102」で英語コンテンツを10件検索

レスポンスで最初に見るところ

results[].title: タイトル
results[].url: ページURL
results[].category: 種別（Documentation / Training など）
nextLink: 続きのページURL

Search のページングの考え方

1ページ件数は $top
何件目から読むかは $skip
次ページ URL が返ってきたら nextLink を優先してたどる

例: 1ページ10件で3ページ目を取りたい場合は、$top=10 と $skip=20

Catalog API: 構造化データを取得する

Catalog API は、学習データを「検索結果」ではなく「カタログ形式の構造化データ」として受け取るための API です。

2つの取り方

まとめ取得

GET https://learn.microsoft.com/api/catalog/

リソース単位取得

GET https://learn.microsoft.com/api/v1/{resource}?api-version=2023-11-01-preview&maxpagesize={n}&locale={locale}

`resource` の意味

modules: 学習モジュール
learning-paths: 学習パス
courses: コース
certifications: 認定資格
exams: 試験
applied-skills: 実践スキル

よく使うオプション

api-version
- APIバージョン指定（例: 2023-11-01-preview）
maxpagesize
- 1回で受け取る件数
locale
- 言語/地域
levels
- 難易度フィルタ（例: intermediate）
roles
- ロールフィルタ（例: ai-engineer）
products
- 製品フィルタ（例: azure）
subjects
- 主題フィルタ（例: identity）
updatedAt.gt
- この日時より新しい更新分だけ取りたい時に使う

例:

https://learn.microsoft.com/api/v1/modules?api-version=2023-11-01-preview&maxpagesize=20&locale=ja-jp

日本語（ja-jp）の学習モジュール（modules）を、1回の取得で最大20件（maxpagesize=20）まで取得

フィルタを使う例:

https://learn.microsoft.com/api/v1/modules?api-version=2023-11-01-preview&locale=en-us&maxpagesize=20&levels=intermediate&roles=ai-engineer&products=azure&subjects=identity

Catalog のページングの考え方

1回の取得件数を maxpagesize で指定する
レスポンスに続き取得用の URL（nextLink など）が含まれる場合は、それをたどって最後まで取得する
大量取得では 1回で取り切る前提にせず、継続取得のループを前提にする

認証の話

ここが一番つまずきやすい部分かと思います。

まず違いについて（どこまで必要か）

Search API
- 認証なしでも試せるケースがある
- まず挙動確認しやすく、PoC の入口に向いている
Catalog API
- 基本的に認証前提
- コンテンツの体系データ取得では、権限確認が必要になることが多い
実運用
- アプリ認証（client credentials）を使うケースが多い
- バッチや定期実行でユーザー操作なしにトークン更新できるため

なぜ Search は軽く、Catalog は重い?

Search は公開検索に近い用途が多く、最初の検証を進めやすい設計です。
Catalog は構造化データの取得や継続利用が前提になりやすく、権限管理が厳しめになりやすいです。

Search を試す最短手順

az login
必要に応じてトークン取得

$token = az account get-access-token --resource https://learn.microsoft.com --query accessToken -o tsv

Bearer 付きで呼び出し

$headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Method Get -Headers $headers -Uri "https://learn.microsoft.com/api/search?search=azure%20storage&locale=ja-jp&`$top=5"

Catalog の実務フロー（概要）

Azure AD でアプリ登録
API 権限を付与
管理者同意
client credentials でトークン取得
Bearer 付きで Catalog を呼び出す

実務フローで実際に返ってくるレスポンス（具体例）

※以下の JSON は理解しやすくするための例です。実際のフィールド名や構造は API バージョンやエンドポイントにより異なる場合があります。

1. トークン取得で返るレスポンス（client credentials）

Catalog 呼び出しの前段で、まず OAuth トークン取得 API から次のような JSON が返ります。

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ..."
}

最低限見る項目:

token_type: 通常 Bearer
expires_in: 有効期限（秒）
access_token: Catalog 呼び出し時に Authorization ヘッダーへ設定する値

2. Search API で返るレスポンス（比較用）

Search は「検索結果配列」が中心です。

{
  "results": [
    {
      "title": "Azure AI services documentation",
      "url": "https://learn.microsoft.com/azure/ai-services/",
      "description": "Learn about Azure AI services.",
      "category": "Documentation",
      "locale": "en-us"
    },
    {
      "title": "Design a solution for AI workloads",
      "url": "https://learn.microsoft.com/training/modules/design-ai-solutions/",
      "description": "Training module for AI-102.",
      "category": "Training",
      "locale": "en-us"
    }
  ],
  "nextLink": "https://learn.microsoft.com/api/search?..."
}

最低限見る項目:

results[].title
results[].url
results[].category
nextLink（ページング時）

3. Catalog API で返るレスポンス（認証成功時）

Catalog は「コンテンツ種別ごとの配列」が返るのが特徴です。

{
  "modules": [
    {
      "uid": "learn.wwl.some-module",
      "title": "Module title",
      "summary": "Module summary",
      "url": "https://learn.microsoft.com/training/modules/...",
      "roles": ["ai-engineer"],
      "levels": ["intermediate"],
      "products": ["azure"]
    }
  ],
  "learningPaths": [
    {
      "uid": "learn.wwl.some-learning-path",
      "title": "Learning path title",
      "modules": ["learn.wwl.some-module"]
    }
  ],
  "exams": [],
  "certifications": []
}

最低限見る項目:

modules[].uid
modules[].title
modules[].roles
modules[].levels
learningPaths[].uid
learningPaths[].modules

4. 失敗時に実際に返ってきたログ（この環境）

この環境では、catalog 呼び出し以前に Azure CLI の実行パス解決で次のエラーが出ていました。

'"C:\Program Files\Microsoft SDKs\Azure\CLI2\wbin\az.cmd"' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

つまりこのケースでは、Catalog の HTTP レスポンス本体（200/401/403 のJSON）まで到達していません。

トークン取得例:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client-id}
&client_secret={client-secret}
&scope=https%3A%2F%2Flearn.microsoft.com%2F.default

呼び出しヘッダー例:

Authorization: Bearer {access_token}
Accept: application/json

補足:

GET本体では Content-Type 不要なことが多い
トークン取得時は Content-Type: application/x-www-form-urlencoded を使う

実例: Azure Storage を探す

まずは Search API で「Azure Storage」に関連する Learn コンテンツを探す例です。

URL 直叩き:

https://learn.microsoft.com/api/search?search=azure%20storage&locale=ja-jp&$top=5

PowerShell:

$token = az account get-access-token --resource https://learn.microsoft.com --query accessToken -o tsv
$headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Method Get -Headers $headers -Uri "https://learn.microsoft.com/api/search?search=azure%20storage&locale=ja-jp&`$top=5"

実際の利用パターン

Search API でキーワード検索する
検索結果の url を拾って目的ページへ到達する
必要なら Catalog API で構造化メタデータを取得する
本文は URL 先を開いて読む

初心者向けのつまずきポイント

locale を付け忘れて、英語結果ばかり返る
$top と $skip の役割が混ざる
Search は通るのに Catalog が 401/403 になる
scope やテナントが合っておらずトークンが使えない
subject と skill を同じ意味で扱ってしまう

困ったら、次の順で切り分けると楽です。

まず Search API を認証なしで試す
次に Search API を認証ありで試す
最後に Catalog API を試す
Catalog で失敗したら権限・同意・テナントを確認

使い分けまとめ

やりたいこと	使うAPI
Learn 内をキーワード検索したい	Search API
モジュール一覧を取りたい	Catalog API
1件の詳細を取りたい	Catalog API
学習パスを見たい	Catalog API
本文を読みたい	返ってきた URL を開く

補足:

画面での検索機能を作るなら Search API
データを定期取得して分析や推薦に使うなら Catalog API

迷ったら最初は Search API から入るのがおすすめです。私もこの順番にしてから、理解がだいぶ楽になりました。

おわりに

Microsoft Learn Platform API は、一見すると似たURLが多くて混乱しやすいですが、

Search = 探す
Catalog = 取る（構造化データを取得する）

と整理すると、かなり見通しが良くなります。

最初は小さく Search で成功体験を作って、必要になったら Catalog の認証設計に進む。これがいちばんスムーズです。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Microsoft Learn Platform API の使用方法

はじめに

このAPIで何ができるか

まず3分で全体像

用語をやさしく整理

Search API: まずはここから

基本形

オプション

具体例

レスポンスで最初に見るところ

Search のページングの考え方

Catalog API: 構造化データを取得する

2つの取り方

resource の意味

よく使うオプション

Catalog のページングの考え方

認証の話

まず違いについて（どこまで必要か）

なぜ Search は軽く、Catalog は重い?

Search を試す最短手順

Catalog の実務フロー（概要）

実務フローで実際に返ってくるレスポンス（具体例）

1. トークン取得で返るレスポンス（client credentials）

2. Search API で返るレスポンス（比較用）

3. Catalog API で返るレスポンス（認証成功時）

4. 失敗時に実際に返ってきたログ（この環境）

実例: Azure Storage を探す

実際の利用パターン

初心者向けのつまずきポイント

使い分けまとめ

おわりに

`resource` の意味