この記事では、Microsoft Learn Platform API の使用を開始する際に役立つ情報を提供します。 API の詳細やユース ケースに慣れていない場合は、まず Microsoft Learn Platform API の概要 に関する記事を確認することをお勧めします。
プラットフォーム API 認証について
Learn Platform REST API は、認証に Microsoft Entra ID を 使用します。 API 呼び出しを行う前に、アクセス方法を選択する必要があり、クライアント アプリケーションは有効な資格情報で認証する必要があります。
アプリ専用アクセス
アプリが Learn に直接アクセスする場合、そのアクセスは 1 人のユーザーに関連付けられません。 アプリは、独自の ID を使用して API を直接呼び出します。このシナリオはアプリ専用アクセスです。 Microsoft ID プラットフォームの詳細を確認します。
開始するには、Microsoft ID プラットフォームで有効な ID が必要です。これは、 アプリの登録 またはマネージド ID です。 クォータとパートナーの管理を簡素化するために、各パートナーが 1 つの ID を持っている必要があるのが理想的です。 ユーザー割り当てマネージド ID を使用すると、異なるサービス間でマネージド ID を統合するのに役立ちます。
Entra ID ID が設定されたら、認証の証明としてスコープが に設定された Entra ID からhttps://learn.microsoft.com/.defaultを取得します。 Learn に対して REST API 要求を行うときに、HTTP Authorization ヘッダーにアクセス トークンを含めます。
委任されたアクセス
ユーザーがアプリにサインインし、それを使用して Learn にアクセスする場合、アプリはまず、ユーザーの代わりにこのリソースにアクセスするためのアクセス許可を要求する必要があります。 このシナリオは、委任されたアクセスと呼ばれます。 Microsoft ID プラットフォームの詳細を確認します。
開始するには、 アプリの登録を登録する必要があります。 アプリの登録が設定されたら、アプリはユーザーに特定のスコープを付与するか、ユーザーの代わりに Learn にアクセスするためのスコープのセットをユーザーに要求する必要があります。 Learn では、きめ細かなリソース アクセスのスコープの一覧を提供します。 スコープの一覧は次のとおりです。
-
https://learn.microsoft.com/PublicContent.Read.All: このスコープを使用すると、ユーザーはサインインしているユーザーとして偽装された Learn のパブリック コンテンツにアクセスできます。
Microsoft Learn Platform API のバージョン管理について
API に重大な変更が加えられた場合は、新しい日付のバージョンがリリースされます。 破壊的変更とは、統合を破損する可能性のある変更のことです。 非破壊 (追加の) 変更は、サポートされているすべての API バージョンで適用されます。
API バージョンは api-version クエリ パラメーターとして指定され、安定バージョンには yyyy-MM-dd、プレビュー バージョンでは yyyy-MM-dd-preview を使用します。 API バージョンのクエリ パラメーターは、すべての API 要求に必要です。
新しい安定した API バージョンがリリースされると、新しい API バージョンのリリース後、少なくとも 24 か月間、以前の安定した API バージョンがサポートされます。 プレビュー API のサポート サイクルは、新しいプレビュー API のリリースからさらに 3 か月短縮されます。
現在のバージョンは 2023-11-01-preview です。
すべての API の前の /v1/ URL セグメントは、API バージョンではなくベース URL の一部です。 これは、今後の大幅な API プロトコルとパターンの変更のために予約されています。
プラットフォーム API レート制限について学習する
Learn では、特定の時間内に行うことができる REST API 要求の数を制限します。 この制限は、不正使用やサービス拒否攻撃を防ぐのに役立ち、すべてのユーザーが API を使用できるようにします。
Learn では、アクセス トークンの oid 要求に基づいてレート制限を適用します。 アプリ専用アクセスの場合、制限はアプリ自体に適用されますが、委任されたアクセスの場合、制限はアプリにサインインしたユーザーに適用されます。
既定では、レート制限は 1 分あたり 100 回の API 呼び出しであり、5 分間で計算されます。 運用環境に対してより高い制限が必要な場合は、Learn Integrations サポートにお問い合わせのうえ、引き上げを依頼してください。
ナレッジ検索 API などの特定の API では、トークンベースのレート制限も実装されます。 これは、使用される Microsoft Azure OpenAI トークンの数に基づいており、既定の上限は 1 分あたり 10,000 トークンです。 運用環境でこの制限を引き上げるには、Learn Integrations サポートにお問い合わせください。
プラットフォーム API のページネーションの学習
すべての最上位 API リソースは、'list' API メソッドを使用した一括取得をサポートします。 たとえば、モジュールまたは試験の一覧を取得できます。 これらのメソッドは、標準化されたアプローチに従って、ページ分割された応答を返します。
リスト API メソッドは、応答本文の nextLink フィールドで示されるカーソルベースの改ページ位置を使用します。 このフィールドには、結果の次のページをフェッチするために必要な情報を含む不透明な URL が含まれています。 既定では、リスト API は要求ごとに 30 個の項目を返しますが、maxpagesize パラメーターを使用してページ サイズを調整できます。
クライアント SDK ライブラリには、リストの全ページを移動するための自動ページネーションヘルパーが用意されています。