Microsoft Learn Catalog API を使用するためのベスト プラクティス
この記事では、Learn Catalog API を使用するためのベスト プラクティスについて説明します。
サービス利用規約を理解する
Learn Catalog API は一般公開されており、無料で使用できますが、ユーザーは Microsoft API 使用条件 の対象となります。 Learn Catalog API を使用する前、および運用環境に出力を含む前に、API 使用条件を読んで理解します。
Learn Catalog API の制限事項を理解する
Learn カタログ API 機能の概要 記事の制限事項を参照してください。
Learn コンテンツ モデルを理解する
Learn Catalog API の応答を効果的に使用するには、Microsoft Learn で利用できるコンテンツの種類と相互の関係を理解することが重要です。 詳細については、Learn コンテンツ モデルの に関する記事をご覧ください。
特に：
- UID は一意の ID を表し、コンテンツ オブジェクトごとに一意です。 UID が変更された場合、タイトルまたはその他のメタデータが変わらない場合でも、コンテンツは新しいオブジェクトと見なされます。
- モジュールは、Learn トレーニング カタログ内のコア オブジェクトです。 これらはすべて、シナリオや概念をエンド ツー エンドで教え、前提条件モジュールを取る必要がないという意味で、単独で立つ能力があります。 一部の人にとっては、これはそれであり、ラーニング パスの一部ではありません。 他のユーザーにとっては、より高度な概念を構築するために、1つ以上のラーニングパスにまとめられ、それを通じてユーザーが進んでいきます。 モジュールは、ラーニング パスの一部である必要はありません。また、1 つ以上のモジュールの一部である場合もあります。
- ユニットはスタンドアロン コンテンツとして書き込まれません。 これらは、モジュールの特定の順序で取得することを目的としています。 このため、モジュールの詳細ページと最初のユニットへのリンクを含めて、ユーザーがそこから開始してコンテンツを続行できるようにします。
Learn でのローカライズのしくみと、ローカライズされたコンテンツが API 出力にどのように反映されるかを理解する
Microsoft Learn では、サイト上で 65 を超えるロケールがサポートされており、コンテンツの多くはこれらのロケールに変換されます。 コンテンツで教えられている製品が利用可能なすべての言語でコンテンツを利用できるようにすることを目指していますが、すべてのロケール エクスペリエンスでローカライズされたコンテンツを利用できるわけではありません。
ロケール レコードに翻訳が関連付けられていない場合は、サイト上のコンテンツと API 応答が既定として英語に "フォールバック" されます。 API 出力では、フォールバックが発生したときに、他のロケール応答に英語のメタデータが表示されます。 メインコンテンツがフォールバックされる可能性があるとしても、URL は依然としてそのロケールを指します。これは、ユーザーがそのロケール内でサイトを移動できるようにするためです（翻訳されたヘッダー/フッターや、翻訳が利用可能なその他のリンクが表示されます）。
更新プログラムが英語コンテンツに公開されると、ローカライズ パイプラインは、ローカライズされたバージョンをできるだけ早く (通常は元の変更から数日以内に) 更新するように機能します。
サポートされているロケールの完全な一覧は、Microsoft Learn サイト フッターで確認できます (表示している言語を選択してください)。 これらのロケールはそれぞれ、locale フィルターを使用して Learn Catalog API を使用して照会できます。
トレーニング コンテンツの完了レコードはロケールに依存しません。つまり、ローカライズされたバージョンのコンテンツは、ユーザー トレーニング完了レコード内の個別のオブジェクトとして区別されません。 ユーザーがトレーニングを完了した言語に関係なく、ユーザーはオブジェクト全体のクレジットを受け取り、完了した言語への参照は保存されません。 このロケールに依存しない完了は、学習エクスペリエンスで Learn Catalog API を実装する場合は、それを考慮する必要があることを意味します。また、コンテンツ オブジェクトを個別のオブジェクトとして読み込む場合は、ユーザーがトレーニングを完了する言語に関係なく、他の言語でクレジットを取得し、再取得する必要がないように、それらのオブジェクト間に等価性を実装します。
Learn でのコンテンツのバージョン管理のしくみと、それが API 出力にどのように反映されるかを理解する
特に、コンテンツは常に更新されています。 利用可能な更新プログラムは 1 日に 2 回公開されます。 変更は、小さなテキスト変更のような軽微なものから、メジャーな改訂、追加、または削除のような大きなものまで、さまざまです。 一般に、コンテンツ ポートフォリオは、何千人もの共同作成者を持つ大規模で高度に管理されたオープンソース プロジェクトとして管理されており、変更は常に行われています。 実稼働システムで Learn Catalog API を使用する場合は、これを認識し、システムで処理できるようにする必要があります。
新しいコンテンツ オブジェクトが追加されると、応答に新しいオブジェクト (UID によって識別されます) として表示されます。 コンテンツが変更されると、そのlast_modified値に基づいて通知できます。 コンテンツが削除されると、コンテンツ オブジェクトは応答から削除されます。 API 応答でコンテンツが更新されるまでに若干の遅延が生じることがありますが、ユーザーがコンテンツの URL に従うと、常に最新の情報が表示されます。 削除の場合、古い URL は新しいコンテンツまたはエクスペリエンス、または次の最適なオプションにリダイレクトされます。
現時点では、last_modified 日付を超えるコンテンツ バージョンへの参照はありません。
データを定期的に更新する
Learn Catalog API のカタログ情報を使用してビジネス プロセスをサポートしている場合、またはサイト エクスペリエンスの一部として顧客向けに表示する場合は、少なくとも 1 日に 1 回はコンテンツを更新してください。
特に、コンテンツは常に更新されています。 利用可能な更新プログラムは 1 日に 2 回公開されます。 それらは、軽微なテキスト変更のように軽微である場合もあれば、主要な改訂、追加、削除のように重大である場合もあります。 一般に、コンテンツ ポートフォリオは、何千人もの共同作成者を持つ大規模で高度に管理されたオープンソース プロジェクトとして管理されており、変更は常に行われています。 実稼働システムで Learn Catalog API を使用する場合は、これを認識し、システムで処理できるようにする必要があります。
開発者向けドキュメントの推奨事項を確認する
Learn Catalog API 開発者向けドキュメント には、応答の一部として提供されるデータの完全な一覧と、優れた学習エクスペリエンスをサポートするために各フィールドを使用する方法に関する推奨事項が記載されています。
クエリ ロジックを理解する
検索対象のみを取得し、より小さなファイル サイズを処理できるように、応答を事前にフィルター処理するために使用できるフィルターは多数あります。 クエリ フィルターの完全な一覧については、Learn Catalog API 開発者向けリファレンス記事を参照してください。 特に、クエリを正しく形成する必要があり、要求で複数のクエリ パラメーターを使用している場合、クエリは AND 演算子を使用して評価されます。
次の手順
Learn Catalog API でサポートする詳細については、次の記事を参照してください。