Microsoft Learn Catalog API の使用に関するベストプラクティス

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

この記事では、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 は "Unique ID" の略で、各コンテンツオブジェクトに対して一意となるものです。 UID が変更されると、たとえタイトルや他のメタデータが同じであっても、そのコンテンツは新しいオブジェクトとみなされます。
モジュールは、Learn トレーニングカタログ内のコアオブジェクトです。これらはすべて、シナリオまたは概念をその中で端から端まで教えるという意味で、単独で機能します。前提条件となるモジュールを受講する必要はありません。中には、これだけで、ラーニングパスの一部ではないものもあります。また、より高度なコンセプトを構築するために、1 つまたは複数のラーニングパスにまとめられている場合もあります。モジュールはラーニングパスの一部である必要はなく、1 つまたは複数のラーニングパスの一部であることもあり得ます。
ユニットは独立したコンテンツとして書かれているわけではありません。それらは、モジュールの特定の順序で実施されることが意図されています。このため、モジュール詳細ページと最初のユニットへのリンクが含まれており、ユーザーはそこから始めてコンテンツを進めることができます。

Learn でのローカライズのしくみと、ローカライズされたコンテンツが API の出力にどのように反映されるかを理解する

Microsoft Learn のサイトでは 65 を超えるロケールがサポートされており、コンテンツの多くはこれらのロケールに翻訳されています。 Microsoft はコンテンツで教えられている製品が利用可能なすべての言語においてコンテンツを利用できるようにすることを目指していますが、すべてのロケールエクスペリエンスでコンテンツが翻訳されているわけではありません。

ロケールのレコードに関連する翻訳がない場合、サイト上のコンテンツと 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 回はコンテンツを最新の情報に更新するようにしてください。

開発者向けドキュメントの推奨事項を確認する

Learn Catalog API の開発者向けドキュメントには、応答の一部として提供されるデータの完全なリストがあり、優れた学習エクスペリエンスをサポートするために各フィールドをどのように使用するかについての推奨事項も記載されています。

クエリロジックを理解する

応答を事前フィルター処理するために使用できるフィルターが多数用意されており、これで自分が探しているものだけを受け取って、より小さいサイズのファイルを処理することができます。すべてのクエリフィルターの一覧については、Learn Catalog API 開発者リファレンスの記事を参照してください。特に、クエリを正しく形成する必要があります。また、要求の中で複数のクエリパラメーターを使用する場合は、クエリは AND 演算子を使用して評価されます。

次のステップ

Learn Catalog API の使用に役立つその他の情報については、次の記事を参照してください。

Microsoft Learn Catalog API の使用に関するベスト プラクティス