Microsoft Learn Catalog API の使用に関するベスト プラクティス
この記事では、Learn Catalog API の使用に関するベスト プラクティスについて説明します。
サービス使用条件を理解する
Learn Catalog API は一般公開されており、無料で使用できますが、ユーザーには Microsoft API 使用条件が適用されます。 Learn Catalog API を使用する前、および運用環境に出力を含む前に、API の使用条件を読んで理解します。
Learn Catalog API の制限事項を理解する
「Learn Catalog API の機能の概要」の記事の「制限事項」を参照してください。
Learn のコンテンツ モデルを理解する
Learn Catalog API の応答を効果的に使用するには、Microsoft Learn で利用できるコンテンツの種類と、それぞれの相互関係を理解することが重要です。 詳細については、Learn のコンテンツ モデルに関する記事を参照してください。
注目すべき点:
- UID は一意の ID を表し、コンテンツ オブジェクトごとに一意です。 UID が変更されると、たとえタイトルや他のメタデータが同じであっても、そのコンテンツは新しいオブジェクトとみなされます。
- モジュールは、Learn トレーニング カタログ内のコア オブジェクトです。 これらはすべて、シナリオまたは概念をその中で端から端まで教えるという意味で、単独で機能します。前提条件となるモジュールを受講する必要はありません。 中には、これだけで、ラーニング パスの一部ではないものもあります。 また、より高度なコンセプトを構築するために、1 つまたは複数のラーニング パスにまとめられている場合もあります。 モジュールはラーニング パスの一部である必要はなく、1 つまたは複数のラーニング パスの一部であることもあり得ます。
- ユニットは独立したコンテンツとして書かれているわけではありません。 それらは、モジュールの特定の順序で実施されることが意図されています。 このため、モジュール詳細ページと最初のユニットへのリンクが含まれており、ユーザーはそこから始めてコンテンツを進めることができます。
Learn でのローカライズのしくみと、ローカライズされたコンテンツが API の出力にどのように反映されるかを理解する
Microsoft Learn では、サイト上で 65 を超えるロケールがサポートされており、コンテンツの多くはこれらのロケールに変換されます。 コンテンツで教えられる製品が利用可能なすべての言語でコンテンツを利用できるようにすることを目指していますが、すべてのロケール エクスペリエンスでローカライズされたコンテンツを利用できるわけではありません。
ロケールのレコードに関連する翻訳がない場合、サイト上のコンテンツと API の応答は、既定で英語に "フォールバック" されます。 API 出力では、フォールバックが発生したときに、他のロケール応答に英語のメタデータが表示されます。 ただし、メイン コンテンツがフォールバックする可能性がある場合でも、コンテンツへの URL は引き続きロケールを指します。その理由は、ユーザーが引き続きそのロケールのサイトに移動できるようにするためです (翻訳が利用可能な翻訳済みのヘッダー/フッターや、その他のリンクが表示されます)。
英語のコンテンツの更新が公開されると、Microsoft のローカライズ パイプラインは、できるだけ早く、通常は元の変更から数日以内にローカライズ版を更新できるように作業します。
サポートされているロケールすべての一覧は、Microsoft Learn サイトのフッターで確認できます (現在表示中の言語を選択してください)。 これらのロケールそれぞれに対するクエリを、Learn Catalog API で locale フィルターを使用して実行できます。
Microsoft のトレーニング コンテンツの修了レコードは、ロケールに依存しません。つまり、ローカライズ版のコンテンツは、Microsoft のユーザー トレーニングの修了レコードでは、個別のオブジェクトとして区別されません。 ユーザーがトレーニングを完了した言語に関わらず、ユーザーはオブジェクト全体の履修単位を受け取り、完了した言語への参照は保存されません。 このロケールに依存しない完了は、学習エクスペリエンスに 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 の使用に役立つその他の情報については、次の記事を参照してください。