アプリケーションデベロッパーマニュアル
概要
Adobe Learning Manager は、クラウドホスト環境で学習者中心のセルフサービス学習を実現できる管理ソリューションです。Learning Manager API を使用すると、プログラムで Learning Manager リソースにアクセスして、他のエンタープライズアプリケーションと統合させることができます。アドビパートナーは、API を使用して機能を拡張したり、他のアプリケーションやサービスと統合したりすることで、Learning Manager の価値提案を高めることもできます。
使用シナリオ
デベロッパーは Learning Manager API を使用して、Learning Manager の機能を拡張した自己完結型アプリケーションを構築したり、Learning Manager を他のエンタープライズアプリケーションワークフローと統合したりできます。お好みのテクノロジーを使用して、Web アプリケーション、デスクトップクライアント、モバイルアプリを開発することもできます。 開発者は、Learning Manager内からアプリケーションデータにアクセスできます。 開発するアプリケーションのデプロイメントはLearning Managerプラットフォームの外部で行われ、アプリケーションの進化に合わせてソフトウェア開発ライフサイクルを完全に制御できます。 通常、Learning Manager アカウントで使用するアプリケーションは、顧客組織により開発されます。それらのアプリケーションは非公開で、その特定の顧客組織にのみ対応します。Learning Manager API を使用すると、アドビパートナーが、大勢の Learning Manager のお客様にご利用いただける汎用アプリケーションを構築することも可能です。
Learning Manager API
Learning Manager API は、REST の原則に基づいており、Learning Manager オブジェクトモデルの主要な要素をアプリケーションデベロッパーに HTTP で公開します。デベロッパーは、API エンドポイントと HTTP メソッドの詳細を知らなくても、さまざまな Learning Manager オブジェクト、その属性および相互関係について理解できます。モデルを理解できたら、API リクエストと API 応答の構造に関する基本を学び、API 全体でよく使用される一般的なプログラミング用語を覚えることは有益です。
さまざまなAPIエンドポイントとメソッドの詳細については、Learning Manager APIドキュメントを参照してください。
学習者API
Adobe Learning Manager – 学習者APIを使用すると、ユーザーにカスタムの学習エクスペリエンスを提供できます。 これらのAPIを使用するには、有効なユーザートークンが必要です。このAPIは、完全にライセンスを取得し、登録された学習者が存在するワークフローの目的でのみ使用されます。
ログインしていないユースケースでは、特別な処理が必要です。
これらのAPIの適切な使用に関する質問がある場合に備えて、ソリューションアーキテクトに連絡してソリューションを確認してから、展開してください。
API 認証
Learning Manager に API 呼び出しを行うアプリケーションを作成する場合は、統合管理アプリを使用してアプリケーションを登録する必要があります。
Learning Manager API では、OAuth 2.0 フレームワークを使用して、クライアントアプリケーションを認証および承認します。
手順
1.アプリケーションのセットアップ
適切なエンドポイントを使用するように、クライアントIDとクライアントシークレットを使用してアプリケーションを設定できます。 アプリケーションを登録すると、clientIdとclientSecretを取得できます。 Get URL は、SSO やアドビ ID などの事前設定されたアカウントを使用して、ブラウザーで Learning Manager ユーザーを認証する際に使用されます。
GET https://learningmanager.adobe.com/oauth/o/authorize?client_id=<Enter your clientId>&redirect_uri=<Enter a url to redirect to>&state=<Any String data>&scope=<one or more comma separated scopes>&response_type=CODE.
認証が成功すると、ブラウザーは上記の URL に示された redirect_uri にリダイレクトします。 パラメーター コード がリダイレクト URI と共に表示されます。
2. コードから更新トークンを取得
POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded
POST リクエストの本文:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
code:
<code from step 1></code>
</enter>
</enter>
3. 更新トークンからアクセストークンを取得します
アクセストークンを取得するためのURL:
POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded
POST リクエストの本文:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
refresh_token:
<refresh token>
</refresh>
</enter>
</enter>
アクセストークンの詳細情報の確認用 URL
GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>
使用制限
アクセストークンの有効期間は7日間です。 その後は、更新トークンを使用して新しいアクセストークンを生成する必要があります。 既存のアクセストークンが有効な場合に、更新トークンから新しいアクセストークンを生成すると、既存のトークンは返却されます。
Learning Manager API でよく使用される用語の一部が、参考のために以下に説明されています。
Includes
デベロッパーは、単一の API オブジェクトモデルと、そのモデルに関連付けられた複数のモデルにアクセスできます。 後続の関連するモデルにアクセスするには、各モデルと他のモデルとの関係性を理解する必要があります。 含む パラメーターを使用すると、開発者は依存モデルにアクセスできます。 カンマ区切りを使用して複数のモデルにアクセスできます。 includes のサンプルの使用法と詳細については、このページのサンプルAPIモデルのセクションを参照してください。
API リクエスト
API リクエストは、HTTP リクエストで実行できます。 エンドポイントやメソッドに応じて、デベロッパーは、GET、PUT、POST、DELETE、PATCH など、さまざまな HTTP 動詞を選択する場合があります。 リクエストの中には、クエリパラメーターを渡すことができるものもあります。 ユーザーは、特定のデータモデルをリクエストする場合に、JSON API 仕様に従って、関連するモデルをリクエストすることもできます。 一般的な API リクエストの構造は、サンプルモデルの使用例で説明されています。
API 応答
クライアントにより API リクエストが実行されると、JSON API 仕様に従って SON ドキュメントの取得が行われます。 このレスポンスにはHTTPステータスコードも含まれています。開発者はこのコードを確認することで、アプリケーションロジックで適切な次のステップを実行することができます。 一般的なAPI応答の構造は、モデルの使用例で説明されています。
エラー
API リクエストに失敗すると、エラー応答を取得します。 応答で返される HTTP ステータスコードに、エラーの性質が示されています。 エラーコードは、API リファレンス内の各モデルの番号を使って表示されます。 200、204、400、および404は、HTTPアクセスの問題を示すAPIで表現される一般的なエラーの一部です。
フィールド
API オブジェクトの属性や関係は、総称としてフィールドと呼ばれます。 詳しくは、JSON API を参照してください。モデルから1つ以上の特定の属性を取得するAPI呼び出しを作成する際に、パラメーターとしてフィールドを使用できます。 フィールドパラメーターがない場合、API 呼び出しは、モデルから使用可能な属性をすべて取得します。 例えば、次のAPI呼び出しでは、 fields[skill]=nameはスキルモデルのname属性のみを取得します。
https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name
ページネーション
API リクエストにより、応答でオブジェクトの長いリストが返ってくる場合があります。 このような場合、デベロッパーはページネーション属性を使用して、結果を順番に取得できます。記録の範囲を各ページに示した複数のページが単位となります。 例えば、Learning Manager のページネーションの属性により、1 ページに表示する記録の最大数を設定できます。また、ページに表示される記録の範囲値を定義することもできます。
並べ替え
API モデルでは並べ替えが可能です。 モデルに基づいて、結果に適用するソートのタイプを選択します。 並べ替えは、昇順または降順で適用できます。 たとえば、code sort=name
を指定した場合、名前順で昇順に並べ替えられます。 code sort=-name
を指定した場合、名前の降順で並べ替えられます。 詳細については、JSON API仕様を参照してください。
API の使用例
開発者がスキル名、スキルレベルに割り当てられた最大ポイント数、学習者がそのスキルについて獲得したポイント数を取得する必要がある場合を考えてみましょう。
Learning Manager API の userSkill モデルは、デフォルトの属性として id、type、dateActived、dateCreated、pointsEarned で構成されています。したがって、デベロッパーが GET メソッドを使用して userSkill モデルの詳細を取得すると、デフォルト属性に付随する現在のデータが応答出力に表示されます。
ただし、このシナリオでは、デベロッパーはユーザーのスキル名と、スキルレベルに対するポイントを取得するものとします。 Learning Manager API により、関係フィールドを使用して関連情報にアクセスし、パラメーターを含めることが可能です。userSkill に関連付けられたモデルは、関連タグで取得できます。 これらのモデルを userSkill と一緒に呼び出して、関連付けられた各モデルの詳細を取得できます。 この情報を取得するには、関連付けられている各モデルの値をドット(ピリオド)で区切った code include
パラメーターを使用します。 カンマを区切り文字として使用して、ユーザーinclude=skillLevel.skill,courseなどの別のモデルを要求できます
API 呼び出し
https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned
例として、userId は 746783、userSkill ID は 746783_4426_1 とします。
API 呼び出しの応答
\{
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1?include=skillLevel.skill&fields[userSkill]=pointsEarned&fields[skillLevel]=maxCredits&fields[skill]=name"},
"data": {
"id": "746783_4426_1",
"type": "userSkill",
"attributes": {"pointsEarned": 5},
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1"}
},
"included": [
{
"id": "4426",
"type": "skill",
"attributes": {"name": "Java"},
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/skills/4426"}
},
{
"id": "4426_1",
"type": "skillLevel",
"attributes": {"maxCredits": 10}
}
]
}
Learning Manager モデル
Learning Manager API を使用すると、開発者は Learning Manager オブジェクトに RESTful リソースとしてアクセスできます。 各 API エンドポイントは、通常、バッジなどのオブジェクトインスタンスといったリソースを指しており、そのようなオブジェクトのコレクションを指すこともあります。 デベロッパーは、PUT、GET、POST、DELETE などの HTTP 動詞を使用して、それらのオブジェクト(コレクション)に対する CRUD 操作を実行します。
次の図は、V1 API の Learning Manager オブジェクトモデルのさまざまな要素を示しています。
次の表では、Learning Manager V1オブジェクトモデルの様々な要素について説明します。
以下は、V2 API の Learning Manager のさまざまな要素を示したクラス図です。
badge
catalog
user
an ``loResource
内にカプセル化されたすべてのリソースは、学習目標に関しては同等ですが、配信タイプまたはコンテンツのロケールに関しては互いに異なります。 with
を関連付けます。 いつ達成したかや assertionUrl
などの詳細が含まれています。 and
作業計画書)があります。 module
の概念と同じです。 コースは、 of
個のモジュールで構成されます。 Learning Manager では、モジュールをさまざまな同等の方法で配信できる。したがって、 loResource
は、これらの同等のリソースをすべて本質的にカプセル化します。 user
が費やした期間、ユーザーが行った進行状況の割合、合格/不合格のステータス、関連付けられたクイズでユーザーが取得したスコアなどの情報が含まれます。 upcoming classroom
個またはバーチャル教室コースのリストです。オブジェクトの属性と関係のリスト。
属性
dateCreated
gamificationEnabled
id
locale
loginUrl
logoUrl
name
サブドメイン
themeData
timeZoneCode(タイムゾーン)
リレーションシップ
contentLocales(localizationMetadata)
gamificationLevels(gamificationLevel)
timeZones(timeZone)
uiLocales(localizationMetadata)
id
imageUrl
name
state(状態)
dateCreated
dateUpdated
説明
id
isDefault
isInternalSearchable
isListable
name
state(状態)
id
名前
カラー
name
ポイント
属性
authorNames
dateCreated
datePublished
dateUpdated
effectivenessIndex
enrollmentType
id
imageUrl
isExternal
isSubLoOrderEnforced
loType
state(状態)
タグ
リレーションシップ
authors(user)
enrollment(learningObjectInstanceEnrollment)
instances(learningObjectInstance)
prerequisiteLOs(learningObject)
skills(learningObjectSkill)
subLOs(learningObject)
supplementaryLOs(learningObject)
supplementaryResources(resource)
属性
completionDeadline
dateCreated
enrollmentCount
id
isDefault
座席の上限
state(状態)
効力
リレーションシップ
バッジ(バッジ)
l1FeedbackInfo(feedbackInfo)
learningObject(learningObject)
loResources(learningObjectResource)
localizedMetadata(localizationMetadata)
subLoInstances(learningObjectInstance)
属性
dateComplete
dateEnrolled
dateBegin
hasPassed
id
progressPercent
スコア
state(状態)
リレーションシップ
learner(user)
learnerBadge(userBadge)
learningObject(learningObject)
loInstance(learningObjectInstance)
loResourceGrades(learningObjectResourceGrade)
属性
externalReporting
id
loResourceType
resourceType
version
リレーションシップ
learningObject(learningObject)
loInstance(learningObjectInstance)
localizedMetadata(localizationMetadata)
resources(resource)
属性
dateComplete
dateBegin
dateSuccess
duration
hasPassed
id
progressPercent
スコア
リレーションシップ
loResource(learningObjectResource)
クレジット
id
リレーションシップ
learningObject(learningObject)
skillLevel(skillLevel)
属性
id
理由
リレーションシップ
learningObject(learningObject)
authorDesiredDuration
completionDeadline
contentStructureInfoUrl
contentType
contentZipSize
contentZipUrl
dateCreated
dateStart
desiredDuration
downloadUrl
extraData
hasQuiz
hasToc
id
instructorNames
isDefault
locale
location
name
onlyQuiz
reportingInfo
reportingType
座席の上限
属性
description
id
name
state(状態)
リレーションシップ
levels(skillLevel)
id
レベル
maxCredit
name
リレーションシップ
バッジ(バッジ)
スキル
属性
avatarUrl
バイオ
contentLocale(コンテンツのロケール)
電子メール
フィールド
id
name
pointsEarned(獲得ポイント)
profile(プロファイル)
役割
state(状態)
timeZoneCode(タイムゾーン)
uiLocale(UI のロケール)
リレーションシップ
account(account)
manager(ユーザー)
属性
assertionUrl
dateAchieved
id
modelType
リレーションシップ
バッジ(バッジ)
learner(user)
model(learningObject)
属性
コース
courseType
dateStart
登録済み
id
月
四半期
リレーションシップ
containerLO(learningObject)
course(learningObject)
actionTaked
チャンネル
dateCreated
id
message
modelIds
modelNames
modelTypes
read
role
属性
dateAchieved
dateCreated
id
pointsEarned(獲得ポイント)
リレーションシップ
learnerBadge(userBadge)
learningObject(learningObject)
skillLevel(skillLevel)
user(user)
アプリケーション開発プロセス
前提条件
デベロッパーは、Learning Manager で体験版アカウントを作成して、そのアカウント内すべての役割にフルアクセス権を持つ必要があります。アプリケーションの作成にあたって、デベロッパーはユーザーやコースを作成して、アカウントを適切な状態にする必要があります。そのようにして、開発中のアプリケーションがサンプルデータにアクセスできるようにします。
クライアント ID とシークレットの作成
-
統合管理者 のログインで、左ペインの アプリケーション をクリックします。
統合管理者のアプリケーションの選択
-
ページの右上隅にある 登録 をクリックして、アプリケーションの詳細を登録します。 登録ページが表示されます。
アプリケーションの登録
このページにあるフィールドは、すべて入力必須です。
アプリケーション名:アプリケーション名を入力します。 同じアプリケーション名を使用する必要はありません。任意の有効な名前を使用できます。
URL:アプリケーションがホストされる正確な URL がわかっている場合は、その URL を指定できます。 わからない場合は、会社の URL を指定できます。 このフィールドには、有効なURL名が必須です。
リダイレクトドメイン:OAuth 認証後に Learning Manager アプリケーションをリダイレクトするアプリケーションのドメイン名を入力します。複数のURLを指定できますが、
http://google.com
、http://yahoo.com
などの有効なURLを使用する必要があります。説明: アプリケーションの簡単な説明を入力してください。
スコープ: アプリケーションのスコープを定義するために使用できる4つのオプションのいずれかを選択します。 ここに示された選択に基づき、アプリケーションから、Learning Manager API エンドポイントへのアクセスが可能になります。例えば、学習者の役割の読み取りアクセス を選択した場合、Learning Managerの学習者APIエンドポイントのすべてで、アプリケーションから読み取り専用のアクセスが可能になります。
このアカウントのみですか?
はい - [はい]を選択した場合、他のアカウント管理者がアプリケーションを見ることはできません。
いいえ - [いいえ]を選択した場合、他のアカウント管理者もこのアプリケーションにアクセスできますが、このアプリケーションにアクセスするには、アプリケーションIDを使用する必要があります。 アプリケーションIDが生成され、Learning Managerアプリケーションの編集モードに表示されます。アプリケーションの登録中にスコープとして 管理者役割の読み取りおよび書き込みアクセス を選択し、APIのオーサリング中に 管理者役割の読み取りアクセス を選択した場合でも、アプリケーション登録スコープが承認ワークフローに優先するため、アプリケーションに対する書き込みアクセス権を維持できます。
-
登録ページで詳細を入力したら、右上隅の 「登録」 をクリックします。
アプリケーション開発とテスト
Learning Manager API は、デベロッパーがさまざまなアプリケーションを構築する際に使用できます。デベロッパーは、アカウントが有効なユーザーとコースで構成されていることを確認する必要があります。 複数のダミーユーザーやコースを作成して、体験版アカウントでアクティビティをシミュレートして、アプリケーションの機能をテストできます。
アプリケーションデプロイメント
実用アカウントでは、Learning Manager の管理者や統合管理者が、組織内のユーザーにアプリケーションを使用する権限を与えるようにすることをお勧めします。アプリケーションのテストが完了して、実用の準備が整ったら、実用アカウントの管理者に通知します。 管理者が、実用アカウントでアプリケーションの新しいクライアント ID とクライアントシークレットを生成し、それらを安全に組み込めるよう、アプリケーション内で必要な手順を取るのが理想的です。 アプリケーションをデプロイする実際の手順は、企業によって異なります。デプロイを完了するには、組織の Learning Manager 管理者が、組織内の IT/IS 部門からサポートを受ける必要があります。
外部アプリケーションの承認
アプリケーション ページの右上隅にある 承認 をクリックすると、外部アプリケーションを追加できます。 外部アプリケーション ID を入力し、「保存」 をクリックします。
外部アプリケーションの追加と承認