注意:

Captivate Prime V1 API は非推奨となりました。 V1 API は、2021 年 2 月をもって終了します。 今後は V2 API をご使用ください。

概要

Adobe Captivate Prime は、クラウドホスト環境で学習者を主導として行う、セルフサービス形式の学習管理ソリューションです。Captivate Prime API を使用すると、プログラムで Captivate Prime リソースにアクセスして、他のエンタープライズアプリケーションと統合させることができます。 アドビパートナーは、API を使用して機能を拡張したり、他のアプリケーションやサービスと統合したりすることで、Captivate Prime の価値提案を高めることもできます。

使用シナリオ

デベロッパーは、Captivate Prime API を使用して、Captivate Prime の機能を拡張した自己完結型アプリケーションを構築したり、Captivate Prime を他のエンタープライズアプリケーションワークフローと統合したりできます。 お好みのテクノロジーを使用して、Web アプリケーション、デスクトップクライアント、モバイルアプリを開発することもできます。 デベロッパーは、Captivate Prime 内からアプリケーションデータにアクセスできます。 開発するアプリケーションのデプロイが、Captivate Prime プラットフォームの外部で行われるので、アプリケーションの進化に合わせたソフトウェア開発ライフサイクルをきめ細かく制御できます。 通常、Captivate Prime アカウントで使用するアプリケーションは顧客組織により開発されます。それらのアプリケーションは非公開で、その特定の顧客組織にのみ対応します。 Captivate Prime API を使用すると、アドビパートナーが、大勢の Captivate Prime のお客様にご利用いただける汎用アプリケーションを構築することも可能になります。

Captivate Prime API

Captivate Prime API は、REST の原則に基づいており、HTTP を介して Captivate Prime オブジェクトモデルの主要な要素をアプリケーションデベロッパーに公開します。 デベロッパーは、API エンドポイントと HTTP メソッドの詳細を知らなくても、さまざまな Captivate Prime オブジェクト、その属性および相互関係について理解することができます。 モデルを理解できたら、API リクエストと API 応答の構造に関する基本を学び、API 全体でよく使用される一般的なプログラミング用語を覚えることは有益です。

さまざまな API エンドポイントとメソッドについての詳細は、Captivate Prime API ドキュメントを参照してください。

API 認証

Prime に API 呼び出しを行うアプリケーションを作成する場合は、統合管理アプリを使用してアプリケーションを登録する必要があります。 

Captivate Prime API では、OAuth 2.0 フレームワークを使用して、クライアントアプリケーションの認証や承認を行います。 

手順

1. アプリケーションを設定

適切なエンドポイントを使用するように、クライアント ID とクライアントシークレットを使用してアプリケーションを設定できます。 アプリケーションが登録されると、clientId と clientSecret を取得できます。 Get URL は、SSO やアドビ ID などの事前設定されたアカウントを使用して、ブラウザーで Captivate Prime ユーザーを認証する際に使用されます。 

GET https://captivateprime.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://captivateprime.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>

3.更新トークンからアクセストークンを取得

アクセストークンを取得する URL: 

POST https://captivateprime.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>

アクセストークンの詳細情報の確認用 URL

GET https://captivateprime.adobe.com/oauth/token/check?access_token=<access_token>

使用制限

アクセストークンは 7 日間有効です。 その後は、更新トークンを使用して新しいアクセストークンを生成する必要があります。 既存のアクセストークンが有効な場合に、更新トークンから新しいアクセストークンを生成すると、既存のトークンは返却されます。 

Captivate Prime API でよく使用される用語の一部が参考のために以下に説明されています。 

Includes

デベロッパーは、単一の API オブジェクトモデルと、そのモデルに関連付けられた複数のモデルにアクセスできます。 後続の関連するモデルにアクセスするには、各モデルと他のモデルとの関係性を理解する必要があります。 デベロッパーは Includes パラメーターを使用して、依存モデルにアクセスできます。 カンマ区切りを使用すると、複数のモデルにアクセスできます。 使用例と Includes の詳細については、このページのサンプル API モデルのセクションを参照してください。 

API リクエスト

API リクエストは、HTTP リクエストで実行できます。 エンドポイントやメソッドに応じて、デベロッパーは、GET、PUT、POST、DELETE、PATCH など、さまざまな HTTP 動詞を選択する場合があります。 リクエストの中には、クエリパラメーターを渡すことができるものもあります。 ユーザーは、特定のデータモデルをリクエストする場合に、JSON API 仕様に従って、関連するモデルをリクエストすることもできます。 一般的な API リクエストの構造は、サンプルモデルの使用例で説明されています。

API 応答

クライアントにより API リクエストが実行されると、JSON API 仕様に従って SON ドキュメントの取得が行われます。 この応答には、デベロッパーがアプリケーションロジックで次の手順を適切に実行する際に照合できる、HTTP ステータスコードも含まれます。 一般的な API 応答の構造は、サンプルモデルの使用例 で説明されています。

エラー

API リクエストに失敗すると、エラー応答を取得します。 応答で返される HTTP ステータスコードに、エラーの性質が示されています。 エラーコードは、API リファレンス内の各モデルの番号を使って表示されます。 HTTP アクセスに問題がある場合に API で表される一般的なエラーには、200、204、400、404 などがあります。  

フィールド

API オブジェクトの属性や関係は、総称としてフィールドと呼ばれます。 詳しくは、JSON API を参照してください。API 呼び出しを行う際に、フィールドをパラメーターとして使用して、1 つ以上の特定の属性をモデルから取得できます。 フィールドパラメーターがない場合、API 呼び出しは、モデルから使用可能な属性をすべて取得します。 例えば、次の API 呼び出しの場合、fields[skill]=name により、スキルモデルの名前属性のみを取得します。 

https://captivateprime.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name 

ページネーション

API リクエストにより、応答でオブジェクトの長いリストが返ってくる場合があります。 このような場合、デベロッパーはページネーション属性を使用して、結果を順番に取得できます。記録の範囲を各ページに示した複数のページが単位となります。 例えば、Captivate Prime のページネーションの属性で、1 枚のページに表示する記録の最大数を設定することができます。 また、ページに表示される記録の範囲値を定義することもできます。 

並べ替え

API モデルでは並べ替えが可能です。 モデルに基づいて、結果に適用する並べ替えの種類を選択します。 並べ替えには、昇順または降順を適用できます。 例えば、sort=name と指定した場合、名前は昇順に並びます。 sort=-name と指定した場合には、名前が降順に並びます。 詳しくは、JSON API 仕様を参照してください。 

API の使用例

デベロッパーが、スキル名、スキルレベルに割り当てられた最大ポイント、そのスキルについて学習者が獲得したポイントなどを取得するというシナリオについて考えます。

Captivate Prime API の userSkill モデルは、id、type、dateActived、dateCreated、pointsEarned をデフォルトの属性として構成されています。 したがって、デベロッパーが GET メソッドを使用して userSkill モデルの詳細を取得すると、デフォルト属性に付随する現在のデータが応答出力に表示されます。 

ただし、このシナリオでは、デベロッパーはユーザーのスキル名と、スキルレベルに対するポイントを取得するものとします。 Captivate Prime API では、関係フィールドを使用して関連情報にアクセスし、パラメーターを含めることが可能です。 userSkill に関連付けられたモデルは、関連タグで取得できます。 これらのモデルを userSkill と一緒に呼び出して、関連付けられた各モデルの詳細を取得できます。 この情報を取得するには、関連するモデルごとにドット(ピリオド)で区切られた値を持つ、include パラメーターを使用します。 user include=skillLevel.skill,course などのように、カンマを区切り文字として使用して別のモデルをリクエストすることもできます。

API 呼び出し

https://captivateprime.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name&fields[skillLevel]=maxCredits&fields[userSkill]=pointsEarned

例として、userId は 746783、userSkill ID は 746783_4426_1 とします。 

API 呼び出しの応答

{
   "links": {"self": "https://captivateprime.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://captivateprime.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1"}
   },
   "included":    [
            {
         "id": "4426",
         "type": "skill",
         "attributes": {"name": "Java"},
         "links": {"self": "https://captivateprime.adobe.com/primeapi/v2/skills/4426"}
      },
            {
         "id": "4426_1",
         "type": "skillLevel",
         "attributes": {"maxCredits": 10}
      }
   ]
}

Captivate Prime モデル

デベロッパーは、Captivate Prime API を使用して、Captivate Prime オブジェクトに、RESTful リソースとしてアクセスすることができます。 各 API エンドポイントは、通常、バッジなどのオブジェクトインスタンスといったリソースを指しており、そのようなオブジェクトのコレクションを指すこともあります。 デベロッパーは、PUT、GET、POST、DELETE などの HTTP 動詞を使用して、それらのオブジェクト(コレクション)に対する CRUD 操作を実行します。

以下は、V2 API の Captivate Prime のさまざまな要素を示したクラス図です。

V2 API クラス図
V2 API クラス図
Captivate Prime オブジェクト 説明
account Prime のお客様に関する詳細をカプセル化したもの
badge 学習者がコースを進めるにつれて、指定のマイルストーンに到達したときに得られる功績のトークン
catalog 学習目標のコレクション
user Captivate Prime における主要なモデル。 通常、学習目標を使用する、組織の内部学習者や外部学習者を指す。 ただし、学習者という役割に加えて、作成者や管理者など、他の役割を果たす場合もある。 インライン属性には、ユーザー ID、タイプ、電子メールなどがある 
resource モジュールでカプセル化しようとする各コンテンツリソースをモデル化するために使用される。 loResource 内でカプセル化されたすべての リソースは学習目標という観点では同じだが、配信タイプやコンテンツのロケールが異なる
userNotification 学習者に関連した通知情報が含まれる
userSkill あるユーザーが 1 つのスキルレベルをどの程度達成したのか表示する
userBadge 単一のバッジを 1 人のユーザーと関連付ける。 いつ達成したかや、assertionUrl 等の詳細を含む
skill スキルモデルは、レベルとクレジットで構成される。 学習者は関係のあるコースを完了すると、スキルを取得できる
skillLevel 1 つまたは複数のコースで構成されており、レベルとそれに関連するクレジットを取得するために使用される
learningObject ユーザーが登録して学習できる、さまざまな種類のオブジェクトを抽象化したもの。 現在、Prime には 4 種類の学習目標(コース、資格認定、学習プログラムおよび作業計画書)がある
learningObjectInstance
学習目標の特定のインスタンス
learningObjectResource モジュールの概念と同等。コースは 1 つ以上のモジュールで構成されている。 Prime では、モジュールをさまざまな同等の方法で配信できる。 したがってloResource は基本的に、これらの同等のリソースをすべてカプセル化する。
loResourceGrade
ユーザーが登録した学習目標のコンテキストで特定のリソースを使用した結果をカプセル化する。 ユーザーがリソースにかけた時間、ユーザーの進捗状況、合格/不合格の状態、関連するクイズでユーザーが取得した得点などの情報を含む
calendar
ユーザーが登録できる今後行われるクラスルームやバーチャルクラスルームのコースのリスト
l1FeedbackInfo
学習目標に関連したフィードバックの質問に対して、学習者が提出した回答をカプセル化する。 学習者からフィードバックを収集する設定の場合、通常は、ユーザーが学習目標を完了した後に収集する
enrollment
この抽象化したものにより、特定の学習目標のインスタンスに対する、特定のユーザーの割り当てに関連したトランザクションの詳細をカプセル化する。

アプリケーション開発プロセス

前提条件

デベロッパーは、Prime で体験版アカウントを作成して、そのアカウント内すべての役割にフルアクセス権を持つ必要があります。 アプリケーションの作成にあたって、デベロッパーはユーザーやコースを作成して、アカウントを適切な状態にする必要があります。そのようにして、開発中のアプリケーションがサンプルデータにアクセスできるようにします。

クライアント ID とシークレットの作成

  1. 統合管理者ログインで、左ペインの「アプリケーション」をクリックします。 

    application-development-menu
  2. ページの右上隅にある「登録」をクリックして、アプリケーションの詳細を登録します。 登録ページが表示されます。 

    新しい応募者の登録
    新しい応募者の登録

    このページにあるフィールドは、すべて入力必須です。 

    アプリケーション名:アプリケーション名を入力します。 同じアプリケーション名を使用する必要はありません。別の有効な名前をどれでも使用できます。 

    URL:アプリケーションがホストされる正確な URL がわかっている場合は、その URL を指定できます。 わからない場合は、会社の URL を指定できます。 このフィールドには必ず有効な URL 名を入力してください。 

    リダイレクトドメイン:OAuth 認証後に Captivate Prime アプリケーションをリダイレクトするアプリケーションのドメイン名を入力します。 ここで複数の URL を指定できますが、http://google.com、http://yahoo.com など、有効な URL を使用する必要があります。 

    説明:アプリケーションの簡単な説明を入力します。 

    スコープ:4 つのオプションからいずれかを選択し、アプリケーションの範囲を定義します。 ここに示された選択に基づき、アプリケーションから、Captivate Prime API エンドポイントへのアクセスが可能になります。 例えば「学習者の役割の読み取りアクセス」を選択した場合、Captivate Prime の学習者 API エンドポイントのすべてで、アプリケーションから読み取り専用のアクセスが可能になります。 

    このアカウントのみですか? 
    はい - 「はい」を選択した場合、他のアカウント管理者がアプリケーションを見ることはできません。
    いいえ - 「いいえ」を選択した場合、他のアカウント管理者も、アプリケーション ID を使用して、このアプリケーションにアクセスできます。 アプリケーション ID が生成され、Captivate Prime アプリケーションの編集モードに表示されます。 

    注意:

    アプリの登録をするときのスコープが承認ワークフローより優先されるため、アプリケーション登録時に「管理者の役割の読み取りおよび書き込みアクセス」を範囲として選択し、API 認証時に「管理者の役割の読み取りアクセス」を選択した場合、書き込みアクセス権を保持できます。 

  3. 登録ページで詳細を入力したら、右上隅の「登録」をクリックします。

アプリケーション開発とテスト

Captivate Prime API は、デベロッパーがさまざまなアプリケーションを構築する際に使用できます。 デベロッパーは、アカウントが有効なユーザーとコースで構成されていることを確認する必要があります。 複数のダミーユーザーやコースを作成して、体験版アカウントでアクティビティをシミュレートして、アプリケーションの機能をテストできます。

アプリケーションデプロイメント

実用アカウントでは、Captivate Prime 管理者や統合管理者が、組織内のユーザーにアプリケーションを使用する権限を与えるようにすることをお勧めします。 アプリケーションのテストが完了して、実用の準備が整ったら、実用アカウントの管理者に通知します。 管理者が、実用アカウントでアプリケーションの新しいクライアント ID とクライアントシークレットを生成し、それらを安全に組み込めるよう、アプリケーション内で必要な手順を取るのが理想的です。 アプリケーションをデプロイする実際の手順は企業によって異なります。デプロイを完了するには、組織の Captivate Prime の管理者が、組織内の IT/IS 部門からサポートを受ける必要があります。

外部アプリケーションの承認

外部アプリケーションを追加するには、アプリケーションページの右上隅にある「承認」をクリックします。 外部アプリケーション ID を入力し、「保存」をクリックします。

外部アプリケーションを追加
外部アプリケーションを追加