LMS365 API

  • 更新

概要

Cloud LMSは、ERP(Enterprise Resource Planning)、HRソフトウェア、レポートツールなどの他のエンタープライズアプリケーションと統合できるものです。
このようなシステム間の相互接続は、組織における業務の合理化や、仕事のパフォーマンスを向上させます。

LMS365APIでは「コースやトレーニング教材の管理」、「ユーザーやコースに関する統計情報の取得」、「ユーザーのコースへの登録」などを行うことができます。機能は随時追加されます。)

OData

OData(Open Data Protocol)は、RESTful APIを構築・使用するための一連のベストプラクティスを定義したOASIS規格です。ODataは、変更の追跡、再利用可能なプロシージャのための関数・アクションの定義、非同期・バッチリクエストの送信に関するガイダンスも提供しています。ODataのRESTful APIは、簡単に利用できます。

APIのデータモデルをコンピューターで読みとれるように記述した「ODataメタデータ」により、強力な汎用クライアントプロキシやツールの作成が可能になります。ODataプロトコルの詳細については http://www.odata.orgをご覧ください。

制限事項

1ページの表示は最大10,000件です。結果が複数のページにまたがる場合、次のページへのURLを含む@odata.nextLinkプロパティをレスポンスに返します。

マルチリージョン

LMS365 は、複数のデータセンターで運用されています。お客様がテナントとして選択した地域に応じて、選択した地域に対応する特定の LMS365 API エンドポイントにアクセスし、最適なパフォーマンスを得ることができます。

Region API End Point
Central US https://us-api.365.systems
North Europe https://ne-api.365.systems
Japan East https://je-api.365.systems
Australia East https://au-api.365.systems
Canada Central https://ca-api.365.systems
United Kingdom South https://uk-api.365.systems
Germany West Central https://de-api.365.systems
U.S. Government GCC https://va-api.usgcc365.systems

また、以前のエンドポイント https://api.365.systems との互換性を維持しているため、現在、エンドポイントはリバースプロキシで動作し、Authorizationヘッダーから顧客の地域を識別し、必要な地域ベースのAPIエンドポイントにAPIリクエストをルーティングしています。

テナント・リージョンの取得

地域ベースのAPIエンドポイントを直接使用することができます。テナントに関連するエンドポイントを取得するには、以下のエンドポイントに GET リクエストを送信します。

var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
var tenantUrl = encodeURIComponent('https://yourtenantname.sharepoint.com')
xhr.open("GET", "https://api.365.systems/discovery/tenants/byurl?url=" + tenantUrl);
xhr.send(null);

レスポンスは以下のような形式になります。

{
"apiUrl": "https://je-api.365.systems/",
"assetsUrl": "https://je-assets.365.systems/",
"appInfos": { /* LMS365 SharePoint Add-ins info */ }
}

これらの情報を得た後、実行するアプリケーションに応じて、キャッシュ/セーブを行うことができます。

APIキーで認証する

API キーを取得するには、LMS365 の管理者にお問い合わせください。API キーを取得すると、LMS365 API エンドポイントの基本認証に使用できます。この認証方法は、すべてのテナントのデータにアクセスしたい場合に便利です。

Authorization Bearer ヘッダによる認証

この方法は、アプリがインストールされているのと同じテナント上のSharePoint Onlineページから、JavaScriptを介して使用することを目的としています。この方法は、SharePoint Onlineに現在ログインしているユーザーでAPIをリクエストする機能を提供します。

注記:この例ではSharePoint Add-in認証を使用していますが、これは現在では廃止されています。最近のSharePointサイトやページでは、SPFx認証を使用することをお勧めします。使用方法のサンプルコードはこちら elearningforce / lms365.spfx-samples をご覧ください。

使用方法の例:

  1. LMS365 APIを利用したJavaScriptを設置するSharePointページに移動します。ページを編集し、埋め込みコードを挿入します。
  2. 次に、ユーザーの LMS365 API トークンを取得するコードと、そのトークンを使用するアプリケーションコードを記述します。

    ① 認証レイヤーをカプセル化し、LMS365 API への問い合わせを簡単に行うことができる便利なクエリ実行ヘルパーを提供する lms365 js ライブラリを含めます。

    <script src="https://assets.365.systems/assets/js/lms" type="text/javascript"></script>

    CourseCatalogアプリのインストールを使用して、現在ログインしているユーザーの下でLMS365APIをクエリするメソッドを提供するQueryExecutorインスタンスを作成します。

    <script type="text/javascript">
    (function () {
    var appTypes = {Scorm: 1, CourseCatalog: 2, Assignments: 3, LearningPath: 4, Quiz: 5}
    var lms = window['ef.lms365'];
    //we pass appTypes.CourseCatalog because we have CourseCatalog installed on the site where we paste the code.
    //if you have another app installed please pass it instead of appTypes.CourseCatalog
    lms.QueryExecuterProvider.instance.get(appTypes.CourseCatalog)
    .then(function (queryExecutor) {
    queryExecutor.execute({ url: '/odata/v2/Courses' })
    .then(x => {
    //process courses here
    });
    });
    })();
    </script>

例として、以下に、すべてのコースを取得し、LMS365 APIを使用して最初のコースの登録数を取得するコードを記述してみます。

<script src="https://assets.365.systems/assets/js/lms" type="text/javascript"></script>
<div id="lms365courses"><img src="/_layouts/15/images/loading.gif"/></div>
<script type="text/javascript">
(function () {
var appTypes = {Scorm: 1, CourseCatalog: 2, Assignments: 3, LearningPath: 4, Quiz: 5}
var lms = window['ef.lms365'];

lms.QueryExecuterProvider.instance.get(appTypes.CourseCatalog)
.then(function (queryExecutor) {
queryExecutor.execute({ url: '/odata/v2/Courses' })
.then(x => {
var element = document.getElementById("lms365courses");
element.innerHTML = "Courses count: " + x.value.length;

// get enrollments for the first course
queryExecutor.execute({ url: '/odata/v2/Courses?$expand=Enrollments&$filter=Id eq ' + x.value[0].Id })
.then(x => {
element.innerHTML += '<br/> First course enrollment count:' + x.value[0].Enrollments.length
});
});
});
})();
</script>

APIへのリクエストは、現在ログインしているユーザーアカウントで実行され、一部のAPIエンドポイントは、APIキー認証の場合のように、すべてではなく現在のユーザー固有のデータを返します。 これが、これら2つのアプローチの主な違いです。


現在のユーザーをコースに登録する
コードのサンプル

<script src="https://assets.365.systems/assets/js/lms" type="text/javascript"></script>

<script type="text/javascript">
(function () {
var appTypes = {Scorm: 1, CourseCatalog: 2, Assignments: 3, LearningPath: 4, Quiz: 5}
var httpMethods = {GET:0, POST:1}
var targetCourseId = 'D5CF2DB7-86E4-479C-8D96-29870D09F30D'

var lms = window['ef.lms365'];
lms.QueryExecuterProvider.instance.get(appTypes.CourseCatalog)
.then(function (queryExecutor) {
queryExecutor.execute({ url: '/odata/v2/Courses('+targetCourseId')/Enroll', method: httpMethods.POST })
.then(x => {
alert('Enrolled')
})
.catch(e => {
console.log(e)
});
});

})();
</script>


テナント・リージョンの変更処理エラー

一部の地域ですでにプロビジョニングされたテナントをお持ちのお客様は、データをエンドユーザーの近くに移動させるため地域の変更が必要となる場合があります。このような場合、クライアントコードがテナントリージョンをキャッシュしている場合は、ロジックを無効にすることを検討する必要があります。

例えば、お客様はNorthEuropeでテナントをプロビジョニングしました。開発者Aは、次のコードでLMS365APIを使用するJSアプリケーションを開発しました。

var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
//process LMS365 courses
}
});

xhr.open("GET", "https://ne-api.365.systems/odata/v2/Courses");
xhr.setRequestHeader("authorization", "Bearer <access token>");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(null);

その後、お客様がテナントをがUS地域に移動することになりました。開発者AはEFIのサポートチームに連絡し、EFIはテナントを「Central US」に移動させました。これ以降、上記のコードでは、以下のように新しいURIを含む409(Conflict)レスポンスエラーが発生します。これは、リクエストはNorthEuropeに送られているが、テナントはCentral USリージョンであることを意味しています。レスポンスはJSON形式で、新しい地域のAPIエンドポイントに関する情報を含んでいます。

{
"errorCode": "TenantRegionHasBeenChanged",
"environmentConfigData": {
"apiUrl": "https://us-api.365.systems:443/",
"assetsUrl": "https://us-assets.365.systems/",
"appInfos": { /* LMS365 SharePoint Add-ins info */}
}
}

"environmentConfigData"オブジェクトには、新しいリージョンAPIのエンドポイントに関する情報が含まれています。