このガイドは、Udemy BusinessのAPIを使用した統合構築をサポートするためのベストプラクティスの参照資料です。学習者に最高の体験を提供するために、このガイドのヒントを活用することをおすすめします。
Udemyのセールスおよびソリューションエンジニアリングチームが構築プロセス中に発生する質問にお答えします。ご不明な点がございましたら、お気軽にUdemy Businessのビジネス担当者までご連絡ください。ミーティングを手配いたします。
このドキュメントの最終更新日は2023年5月31日です。
目次
- 仕組み
- Udemyとサードパーティシステムのコースへのアクセスの違い
- コース更新頻度
- おすすめのコースデータ
- 効率的なAPI 呼び出し
- ページサイズ
- 同期API呼び出し
- コース分類
- 言語コード
- 固有のコースカタログ
- 新規コースと削除されたコース
- コースリストAPIに含まれないもの
- 概要
- レポーティングxAPI
- レポーティングRESTful API
- 推奨エンドポイント
- レポーティングAPIの更新頻度
- レポーティングデータ
- 進捗と修了
- レポーティングAPIとxAPIに含まれないもの
1. APIの一般情報
認証とSSO
Udemy Business内の認証とユーザー管理は、学習管理システム(LMS)と学習体験プラットフォーム(LXP)システムとは独立して取り扱われることに注意してください。学習者がLMS/LXPシステムを介してUdemy Businessコースにアクセスする場合、ユーザーはUdemy Business内でコースを修了するためにUdemy Businessのライセンスも保有している必要があります。Udemy Businessは、標準のユーザー名/パスワード、メールドメインアクセス、シングルサインオンなど、いくつかのメカニズムによるユーザー管理をサポートしています。
エラーハンドリング + 回数制限
429エラー
- すべてのUdemy APIには回数制限があります。回数制限を超えると、429エラー応答がRetry-Afterヘッダーと共に返されます。さらなる要求を行う前に、Retry-Afterヘッダーの待機秒数に対して再試行ロジックを実装する必要があります。
- メモ: Udemyの回数制限は変更される場合があります。再試行ロジックは、ハードコーディングされた回数制限ではなく、429応答の値に基づいて実装する必要があります。
50Xエラー
- 502/503エラーに対しては、再試行ロジックも実装する必要があります。コースリストエンドポイントにアクセスするときに50Xエラーが発生した場合は、page_sizeパラメータ値を減らして、さらなるエラーを防止してください。
- また、コースカタログを再同期し、レポートデータを更新するために、顧客対応メカニズムを実装することをおすすめします。
2. コースリストAPI
仕組み
Udemy BusinessコースリストAPIを使用すると、Udemyコースに関連付けられているすべてのコースとコースメタデータをシステムに取り入れることができます。そこから、LMS、LXP、またはその他のシステムなどのサードパーティプラットフォーム内からUdemy Businessコースを検索、発見、利用できます。タイトル、説明、サムネイルなどの主要なコース情報に加えて、コースの統合には、学習者をLMS/LXPからUdemy Businessインスタンスに自動的にリダイレクトし、学習者がUdemy Business内でコースを修了できるディープリンクURLが含まれます。
この統合では、サードパーティシステム内でUdemy Businessコースを取り入れたり修了したりする機能はサポートされていません。これにより、他のシステムでコンテンツを再ホストする必要がなくなります。また、コースはUdemy内で使用できるように設計されており、学習者ツール、講師のQ&Aなどへのアクセスも含まれているため、可能な限り最高の学習者体験を実現できます。
Udemy Businessは、API構成のオプション設定として、コースの自動登録をサポートしています。これは統合で推奨されています。自動登録が有効になっている場合、学習者がLMS/LXPシステムにあるコースのリンクをクリックすると自動的に受講登録されます。
Udemyとサードパーティシステムのコースへのアクセスの違い
一部のLMS/LXPシステムには、LMS/LXP内のどのユーザーがどのコースにアクセスできるかを制限する機能があります。非公開のカスタムコースとラーニングパスを除き、Udemy Business内のすべてのユーザーは、Udemy Business内から公開コースカタログ全体にアクセスして登録することができます。これはUdemyをご利用のお客様にとって問題ではありませんが、LMS/LXPシステムとUdemy Businessではこの機能が若干異なる場合があることを知っておくことは重要です。
コース更新頻度
コースカタログは変更される可能性があるため、カタログを毎日更新することをおすすめします。これは自動的に行われるため、エンドユーザーが手動で行う必要はありません。更新はオフピーク時に行うことをお勧めします(UTCの午前3時が理想的な時刻です)。
おすすめのコースデータ
APIを介して返される大量のコースメタデータを提供していますが、最高のユーザー体験を得るために、少なくとも以下のデータポイントを使用することをおすすめします。
APIフィールド |
推奨 |
title description primary_category primary_subcategory |
これらのフィールドを使用して、ユーザーの検索用語を照合します |
images[] |
ユーザーにコースの画像を提供する画像URL |
url mobile_native_deeplink |
Udemy Businessウェブアプリとモバイルアプリの顧客の環境のコースへのディープリンク |
locale |
Udemy Businessのカタログには異なる言語のコースがあり、システムがこれを識別してフィルタリングする機能は重要です。 |
estimated_content_length |
これは分数を示すため、ユーザー向けに表示するのに最適です。また、レポート/ユーザーのゲーミフィケーションを通知するために使用できます。 |
level |
コースレベル(初級、中級、専門) |
効率的なAPI 呼び出し
Udemy Businessのコレクションには、お客様の言語コレクションに応じて6,000から23,000のコースが含まれています。最大ページサイズが100の場合、このすべてのコースを取得するには60~230回のAPIリターンが必要です。 このプロセスをうまく管理できるようにシステムを設定すると、長期的に大きなメリットが得られます。このプロセスに関する個別のコンサルティングをご希望の場合は、Udemyソリューションエンジニアの担当者にお問い合わせください。
ページサイズ
- page_size limitは100レコードです。
- この要求で遅延や502エラーが発生した場合は、このpage_sizeの値を半分に減らして再試行してください。
- 合計コース数は応答(count)で提供されます。
- count / page_sizeを使用してページ数を計算します。つまり、count = 1000でページサイズ = 100の場合、10回の要求を行う必要があります。
- 要求ごとにページパラメータを変更する
- https://{{ACCOUNT_NAME}}.udemy.com/api-2.0/organizations/{{ACCOUNT_ID}}/courses/list/?fields[course]=@all&page=1
- または、応答で返される次の値を使用して、結果の次のページを取得できます。
同期API呼び出し
- コースカタログを効率的に取得するには、同期要求を利用することをおすすめします。
- ソフトウェアがコースのページを処理する際、さまざまな理由で処理に失敗する可能性があります。どのページの処理に失敗したかを把握し、このプロセスに再試行メカニズムを含めることが重要です。
- 同期API呼び出しとキューデータ構造は、次のページを注文し、逃した呼び出しを再試行できるため、この種のプロセスに最適です。非同期API呼び出しの場合、一度の呼び出しが多すぎると、APIが過負荷になり、シーケンスのどのページが失敗したかを追跡するのが難しくなる可能性があります。次のコースに進む前に、各コースページを正常に完了することをおすすめします。
コース分類
現在のコース分類のリストを確認します。これには、APIを介してシステムにマップできるカテゴリーとサブカテゴリーのリストが含まれます。この分類法はすべての言語で標準化されているわけではなく、変更される可能性があることに注意してください。
言語コード
Udemy Businessの言語のリストと関連するコードは以下のとおりです。Udemy からコースリストをダウンロードすると、ロケールフィールドが表示されます。そこでは、最初の2文字の小文字はコース全体の言語に該当し、次の2文字はキャプションや字幕などに使用できる追加の地域に該当します。たとえば、英国英語を表すen_GBや、米国英語を表すen_USなどがあります。
アラビア語 - ar
インドネシア語 - id
英語 - en
フランス語 - fr
ドイツ語 - de
ヒンディー語 - hi
イタリア語 - it
日本語* - ja
韓国語* - ko
標準中国語 - zh
ポーランド語- pl
ポルトガル語 - pt
ロシア語 - ru
スペイン語 - es
トルコ語 - tr
固有のコースカタログ
Udemy Businessのコースカタログは、Udemy Businessの各お客様によって異なり非公開です。udemy.comからインポートされたさまざまな言語パッケージ、カスタムコース、その他のコースは、各お客様のコレクションに含まれ、コースAPI応答に含まれます。したがって、Udemy Businessのお客様の組織ごとに固有のコースカタログを維持する必要があります。
新規コースと削除されたコース
- コースカタログは常に変化する可能性があり、新規コースが追加されたり、コースが削除されたりします。
- コースカタログを使用してすべてのコースを取得して内部データベースにロードしている場合、削除されたコースがコースリストの出力に表示されなくなったら、削除するかフラグを立てることが大切です。
- コースが削除されると、コースリストAPIから返されなくなり、ユーザーはUdemyでコースに登録できなくなります。コースがUdemy Businessコレクションから削除されても、そのコースにすでに登録している学習者は引き続きコースにアクセスできます。学習者が削除されたコースの登録を解除すると、それ以降はコースにアクセスできなくなります。また、新規にそのコースにアクセスしたり登録したりすることもできなくなります。
コースリストAPIに含まれないもの
Udemy BusinessのコースカタログAPIには、コースに関するすべての情報へのアクセスが含まれていないことに注意してください。現在利用できないものには、次のものが含まれます。
- コースの埋め込みまたはホスティング
- Udemy Businessの外部でUdemy Businessのコンテンツを直接埋め込んだりホストしたりすることはできません。コンテンツを使用するには、ユーザーをLMS/LXPからUdemy Businessにリダイレクトする必要があります。
- コース評価
- これらはコースAPIエンドポイントには含まれていません。多くのLMS/LXPシステムには、コースを評価する独自のシステムが含まれており、学習者はそれを独自に使用できます。
- コースレビュー
- 登録情報
- 検索と発見機能
- Udemy Businessは、独自の方法で、検索結果を表示し、人気コース、高評価のコースなどを考慮したコースをおすすめします。この機能は、サードパーティのツールに「送信」されません。Udemy Businessは、サードパーティのツールが結果を表示する方法やコースを提案する方法を制御できません。
- ラーニングパスとUdemy Proパス
- これらはコースとは別のオブジェクトであり、コースカタログの同期には含まれません。Udemy BusinessラーニングパスとUdemy Proパスをインポートするには、個別のラーニングパスAPIエンドポイントを利用する必要があります。
- Lecture-level data
- Udemy BusinessのAPIは、APIを介して完全なコースと完全なラーニングパスを送信できます。個別のコースセクション、レクチャー、小テストなどのコースの一部を送信することはできません。
- コースの一部を使用してカスタムラーニングパスまたはラーニングプログラムを作成する機能を探している場合は、Udemy Business内でラーニングパスを構築し、ラーニングパスAPIエンドポイントを使用してラーニングパスをLMS/LXPにインポートすることをおすすめします。
- UB Proラボ、評価テスト、ワークスペース
- ラボ、評価テスト、ワークスペースはサードパーティのシステムに統合できず、Udemy Businessから直接起動する必要があります。
- API経由でコースをUdemyに一括アップロードすることはできません。UdemyのAPIは、Udemyからコース情報を取得することを目的としています。
3. ラーニングパスAPI
概要
UdemyのコースリストAPIエンドポイントと同様に、Udemy BusinessもラーニングパスAPIエンドポイントを提供しています。そのため、LMS、LXP、またはその他のシステムなどのサードパーティプラットフォーム内からUdemy Businessラーニングパスを検索、発見、利用できます。
ラーニングパスは、コース、個々のレクチャー、カスタムコンテンツ、リンクをグループにまとめたコレクションであり、学習者がその設計に関するテーマの知識を得る方法を案内します。
ラーニングパスからの情報は、コースリストAPIエンドポイントを介して得られる情報と多くの点で似ていますが、ラーニングパスはコースとは別のオブジェクトと見なされ、そのように取り扱う必要があることに注意してください。
ラーニングパスAPIを使用したコネクタの開発は、厳密にはUdemy Businessとの統合の主要なユースケースに必要というわけではありませんが、統合の長期的なメリットを最大化するため、開発を検討することをおすすめします。
4. レポーティングAPI
概要
Udemy BusinessレポーティングAPIを使用すると、学習者がコンテンツにどのように取り組んでいるかを追跡できます。たとえば、誰がどのコースをどのくらいの頻度で修了しているかを確認、追跡、把握して、優秀な学習者を追跡したり、苦労している学習者をサポートしたりすることなどができます。このようなインサイトは、より幅広い学習と開発の目標を達成するのに非常に役立ちます。Udemy Businessからエクスポートしたインサイトのレポートは、LMS/LXPで確認するのに役立ち、他の外部システムに存在するデータやレポート機能と組み合わせたり拡張したりすることが可能です。
Udemyからレポートデータを取得するメカニズムには、xAPIとRESTレポーティングAPIの2つがあります。その違いの詳細については、xAPIのメリットを参照してください。
レポーティングxAPI
- Udemyは、進捗状況と完了イベントを、指定されたエンドポイントにほぼリアルタイムで投稿します。これにより、UdemyのAPIを繰り返しポーリングする必要がなくなります。
- プラットフォームにxAPI機能がある場合、xAPIがおすすめのアプローチです。この標準を採用する学習システムが増えているからです。
- レポーティングxAPIには現在、RESTful APIほど多くのデータ要素が含まれていないことに注意してください。
- たとえば、学習者がコースに費やした時間は、xAPIステートメントの一部として送信されません。
レポーティングRESTful API
このAPIは定期的に呼び出す必要があり、データはレポーティングREST APIエンドポイントからLMS/LXPに取り込まれます。これはリアルタイムではなく、新しいレコードを取得するには定期的なプルが必要です。
推奨エンドポイント
修了および進捗状況データについてはuser-course-activityがおすすめです。 From_dateとto_dateを使用して、結果を特定の期間に限定します。
- https://{{ACCOUNT_NAME}}.udemy.com/api-2.0/organizations/{{ACCOUNT_ID}}/analytics/user-course-activity/?page=1&from_date=2022-05-21&to_date=2022-05-22&page_size=100
- 最新のデータをキャプチャしながら日没データもキャプチャできるように、当日と前日で構成される2日間の日付範囲をお勧めします(データは、毎日/更新で生成される可能性があります)。
レポーティングAPIの更新頻度
- 4時間ごと
- メモ: REST APIデータは1日3回更新されます。
- 4時間ごとに、統合の変更を必要とせずに、Udemyが今後、より頻繁に更新を行えるようになります。
レポーティングデータ
データ要素 |
詳細 |
course_id |
コースの一意の識別子 |
user_email |
ユーザーの一意の識別子 |
completion_ratio |
ユーザーが修了したコースの割合。 この割合は、コースにより変化する場合があります。 |
num_video_consumed_minutes |
ユーザーエンゲージメントの合計学習時間/クレジットを追跡するための内部LMS指標に最適 |
course_first_completion_date |
ユーザーが任意の時点でコースを修了したかどうかを追跡する目的で使用されます。 |
course_completion_date |
最近の修了状況を追跡する目的で使用されます。 |
user_external_id |
ユーザーに固有の外部IDとして使用されます(メールが有効な一意のIDでない場合のみ)。 |
lms_user_id |
LMSに固有の外部IDとして使用されます(メールが有効な一意のIDでない場合のみ) |
進捗と修了
- 統合には進捗状況イベントと修了イベントの両方を取り込む必要があります。
- これは、削除されたコースやプラットフォームから開始されなかったコースを含め、利用されたすべてのUdemy Businessコースで発生します。
レポーティングAPIとxAPIに含まれないもの
- Udemy Business Proレポーティング
- 現時点では、ユーザーラボアクティビティレポートとユーザー評価テストアクティビティレポートは、Udemyの管理者設定から直接ダウンロードすることでのみ利用できます。
- ラーニングパスレポート
- これはAPI経由では利用できません。現時点では、Udemy管理者設定から直接ダウンロードすることでのみ利用できます。
5. 今後の予定
Udemyは、APIとテクノロジースタックの継続的な改善に努めています。
- GraphQL - Udemyエンジニアリングは、コースカタログAPIを更新して、GraphQLアーキテクチャを利用する予定です。GraphQLの概要をご覧ください。GraphQLにより、特定の呼び出しに必要なデータのみを返すコースカタログAPIへのクエリが可能になるなど、さまざまなメリットがあります。UdemyのGraphQL APIの公開リリースは、2023年第3四半期に予定されています。
- 検索API - Udemyには、20万件以上のコースカタログを検索するユーザーから集めた、最適なコースをおすすめするための豊富な情報があります。Udemyの検索機能は、ユーザーの検索やおすすめのニーズをサポートします。検索は2023年第3四半期にリリースされる予定です。
6. フィードバックはありますか?
このドキュメントに関するフィードバックがある場合やその他の情報が必要な場合は、partnerships@udemy.comまでフィードバックをお送りください。お待ちしております。