11.10. ウェブサービス

管理メニュー → ウェブサービス

注釈

ウェブサービスはサイト管理者だけがアクセスできます。

ウェブサービスを使用すると、ウェブサービス/ APIを持つ他のアプリケーションとMaharaサイトを接続できます。探している統合を達成するためにはいくつかの設定や特定のウェブサービス機能の開発が必要な場合があります。Maharaのウェブサービスは、必要な機能と関連するインタフェース定義をパブリックする関数を定義する以上に多くのことをする必要なしに、追加のAPIを開発するこを可能にするフレームワークです。

ウェブサービスを使用するにはサイトでSSL証明書を使用する必要があります。サイトが運用モードでない場合は、SSLなしでウェブサービスをテストできます。

11.10.1. 設定 (Configuration)

管理メニュー → ウェブサービス → 設定

このページでは、様々なウェブサービスのルールを設定し、それらを有効または無効にします。

11.10.1.1. ウェブサービス機能を有効にする

ウェブサービスをグローバルに有効にしてから、必要に応じて個別にプロトコルを設定できます。プロトコルが有効になると、それはすべての機能、アカウント、およびトークンに使用できます。

ウェブサービスと個々のプロトコルのオンとオフを切り替える

ウェブサービスと個々のプロトコルのオンとオフを切り替える

  1. 外向きのウェブサービスリクエストを許可する: 『Yes』 に設定されている場合、外向きのサービス用にウェブサービスを使用できます。

  2. 内向きのウェブサービスリクエストを許可する: 『Yes』 に設定されている場合、ウェブサービスは、例えばMahara Mobileを介して、着信コール用にサイトで使用できるようになります。

  3. SOAP: シンプルオブジェクトアクセスプロトコルを使用できるようにする場合は、このプロトコルを許可します。

  4. XML-RPC: XMLコンテンツへのリモート手続き呼び出しをしたい場合、これを 『Yes』 に設定します。このプロトコルはMNetによって使用されます。

    注釈

    MNetがMaharaでサポートされる限り、それを使用して Moodleへの接続を構成する ことができます。

  5. REST: この設定を 『Yes』 に切り替えることにより、表現可能な状態転送プロトコル (REpresentational State Transfer protocol) を許可します。RESTインタフェースはJSON認証もサポートしています。

  6. OAuth: OAuth(オープン認証)プロトコルを使用する場合は、この設定を 『Yes』 に切り替えます。

注釈

ウェブサービスを無効にすると、 『プロトコル』 の下にあるアクティブ化された個々のプロトコルはオフになり、ウェブサービスを再びオンに切り替えると再び手動で有効にする必要があります。

11.10.1.2. ネットワーク証明書

このセクションでは、便宜上、管理メニュー → サイト設定 → ネットワーキング で作成されたMahara証明書の公開鍵が表示されます。

11.10.1.3. サービスグループを管理する

サービスグループは、アカウント(認証)またはユーザトークンへのアクセスの割り当ての単位です。それらは関数のコレクションです。Maharaには、構成可能な一連のサービスグループと機能がすでに付属しています。さらにサービスグループを追加できます。

利用可能なサービスグループの概要とその基本設定

利用可能なサービスグループの概要とその基本設定

  1. サービス: サービスグループの下にはユーザが有効または無効にできる多数の関連機能がグループ化されています。

  2. コンポーネント: サービスグループが使用可能なエリア。一般的に 『ウェブサービス』 です。

  3. 有効: サービスグループが有効にされている場合、 有効 アイコン が表示されます。有効にされていない場合、 無効 アイコン が表示されます。

  4. 認証済みユーザだけ: ユーザ名とパスワードでログインした人がサービスグループを使用できる場合は、有効 アイコン が表示されます。このようなユーザとして使用できない場合は、無効 アイコン が表示されます。

  5. ユーザトークンアクセス: このグループの機能へのアクセスにユーザトークンが必要な場合、有効 アイコン が表示されます。ユーザトークンによるアクセスが許可されていない場合、無効 アイコン が表示されます。

  6. 関数: これは、サービスグループに関連付けられている関数のリストです。

    注釈

    関数の一つをクリックすると、この関数のウェブサービスドキュメントが表示されます。関数APIの説明、入出力パラメータ、エラー処理など、ウェブサービス関数に関する詳細情報があります。

  7. 編集 ボタン をクリックして、以下で説明するようにサービスグループを変更します。

  8. 削除 ボタン をクリックすると、サービスグループが完全に削除されます。

    注釈

    多くの場合、ウェブサービスグループを再作成し、後で必要になった場合に関数を関連付ける必要があるため、ウェブサービスグループを完全に削除したくない場合があります。グループを無効にするだけで十分な場合があります。

  9. 新しいサービスグループを作成する場合、このフィールドに追加し、追加 ボタンをクリックしてください。次に、サービスグループのリストで新しいグループを確認し、グループの横にある 編集 ボタン をクリックして設定します。

編集するサービスグループを選択した場合、次の画面が表示されます。

サービスグループの設定を編集する

サービスグループの設定を編集する

  1. 名称: サービスグループの名称

  2. 省略名: これは、このサービスを参照するためにMaharaに接続するアプリケーションが必要とするサービスの省略名です。

  3. サービス: このサービスグループを使用する場合、このスイッチを 『Yes』 に設定します。以下の個々の機能を調整できます。

  4. 認証済みのユーザだけ: このサービスグループによってユーザ名とパスワードを持つ人だけが影響を受ける場合は、このスイッチを 『Yes』 に設定します。

  5. ユーザトークンアクセス: 特定の機能にアクセスするためにユーザに個別のトークンを持たせたい場合は、このスイッチを 『Yes』 に設定します。

    注釈

    ユーザトークンアクセスは全体のMaharaユーザベースにAPIを使用する可能性を与えます。一般的に、現在のユーザ自身の詳細についてはmahara_user_get_my_userなどのユーザ中心の機能にアクセスできるサービスグループに限定する必要があります。

  6. 関数の名前。

  7. 有効: この設定はこの関数の使用を有効または無効にします。

  8. クラス名: 関数の一部であるクラスの名前。

  9. メソッド名: 呼び出されているメソッドの名前。このリンクから、そのメソッドのウェブサービスドキュメントに移動します。

  10. 変更を完了したら 保存 ボタンをクリックしてください。変更を取り消す場合は 戻る をクリックしてください。

11.10.1.4. サービスアクセストークンを管理する

個々のアクセストークンを生成し、そのアカウントがアクセスできるサービスグループを関連付けることができます。

アクセストークンの概要

アクセストークンの概要

  1. トークン: 特定のアカウント用に生成されたトークン。

  2. インスティテューション: アカウントが所属するインスティテューションを一覧表示します。

  3. ユーザ: 管理者のユーザ名が表示され、ユーザの設定ページにリンクされます。

  4. サービス: トークンが生成されたサービスグループ。

  5. 有効: このサービスグループが有効な場合は、有効 アイコン が表示されます。有効になっていない場合は、無効 アイコン が表示されます。

  6. ウェブサービスセキュリティ: ウェブサービスセキュリティが有効になっている場合、有効 アイコン が表示されます。それ以外の場合、無効 アイコン が表示されます。

  7. 関数: これは選択したサービスに対してトークンがアクセスできるすべての関数のリストです。

  8. 編集 ボタン をクリックして設定を変更します。

  9. 削除 ボタン をクリックしてトークンを削除します。

  10. ユーザ名:トークンを追加するユーザ名を入力します。サイトに登録されている人の名前またはユーザ名を入力し始めることができます。入力すると、名前の候補が表示されます。

  11. そのアカウント用に作成される新しいアクセストークンについては、トークンを生成する ボタンをクリックします。このトークンにサービスグループを関連付けることができる画面が表示されます(以下参照)。一つのユーザ名しか入力できません。

トークンを作成するときは、追加情報を入力する必要があります。

サービスアクセストークンを設定する

サービスアクセストークンを設定する

  1. 正しいトークンを編集していることを確認します。

  2. インスティテューション: アカウントの所属するインスティテューションを選択します。

  3. ユーザ名: トークンを設定する正しいユーザ名を持っていることを確認します。ユーザ名は、管理の人の設定ページにリンクされています。

  4. サービス: トークンを有効にするサービスグループをドロップダウンリストから選択します。トークンアクセスを許可するサービスだけを選択できます。

  5. 有効: サービスグループが有効になると、トークンは自動的に有効になります。

    注釈

    サービスグループを無効にする場合は、サービスグループを管理する セクションでそれを行います。

  6. 認証済みユーザだけ: ここではトークンを作成するため、このコンテクストではこのスイッチは使用されません。だから、それは無効になっています。

  7. 関数: トークンがアクセスできる関数のリスト。

    注釈

    サービスを変更するとき、関数のリストは自動的に更新されません。ページを保存すると、更新されたリストだけが表示されます。

  8. ウェブサービスセキュリティを有効にする(XML-RPCのみ): この機能はXML-RPCベースの認証でだけ使用できます。

  9. 公開鍵: 追加されたウェブサービスセキュリティの公開鍵を入力します(XML-RPCベースの認証の場合だけ)。

  10. 公開鍵の有効期限: 入力した公開鍵の有効期限。日付はフォームを保存すると更新されます。

  11. 変更を完了したら 保存 ボタンをクリックしてください。変更を取り消す場合は 戻る をクリックしてください。

11.10.1.5. サービスユーザを管理する

ユーザにトークンを使用せず、ユーザ名を使用して機能にアクセスできるようにするにはこのオプションを選択する必要があります。ユーザは次のことが必要です:

  • 一度だけ設定される。

  • メンバーであるインスティテューションで 『ウェブサービス』 認証方法を持っている。

    注釈

    認証方法 『ウェブサービス』 を使用するアカウントは、ウェブサービス経由でだけMaharaにアクセスでき、標準ログインフォームを使用することはできません。

サービスユーザを管理する概要セクション

サービスユーザを管理する概要セクション

  1. ユーザ: サービスグループを設定したユーザのユーザ名が表示されます。これは管理のユーザの アカウント設定ページ にリンクされています。

  2. インスティテューション: アカウントが所属するインスティテューションを一覧表示します。

  3. サービス: アカウントに関連付けられているサービスグループ。

  4. 有効: このサービスグループが有効な場合は、有効 アイコン が表示されます。有効になっていない場合は、無効 アイコン が表示されます。

  5. ウェブサービスセキュリティ: ウェブサービスセキュリティが有効になっている場合、有効 アイコン が表示されます。それ以外の場合、無効 アイコン が表示されます。

  6. 関数: これはユーザが選択したサービスに対してアクセスできるすべての関数のリストです。

  7. 編集 ボタン をクリックして設定を変更します。

  8. 関連するサービスグループへのアクセスからアカウントを削除するには、削除 ボタン をクリックします。

  9. ユーザ名: サービスを管理するユーザ名を入力します。サイトに登録されている人の名前またはユーザ名の入力を開始できます。入力時に名前の候補が表示されます。アカウントは認証方法としてウェブサービスを持っている必要があります。

  10. そのアカウント用に作成される新しいアクセストークンについては、トークンを生成する ボタンをクリックします。このトークンにサービスグループを関連付けることができる画面が表示されます(以下参照)。一つのユーザ名しか入力できません。

アカウントを追加するときは、追加情報を入力する必要があります。

ユーザを特定のサービスグループに関連付ける

ユーザを特定のサービスグループに関連付ける

  1. サービスオーナ: ユーザ名が表示されます。以下のユーザ名と一致する必要があります。

  2. インスティテューション: アカウントに関連付けられているインスティテューションが正しいことを確認します。そうでない場合、アカウント設定ページ でインスティテューションを変更できます。

  3. ユーザ名: トークンを設定する正しいユーザ名を持っていることを確認します。

  4. サービス: 人にアクセスを許可するサービスグループをドロップダウンメニューから選択します。ユーザ名によるアクセスを許可するサービスだけが選択できます。

  5. 有効: サービスグループが有効になると、設定は自動的に有効になります。

    注釈

    サービスグループを無効にする場合は、サービスグループを管理する セクションでそれを行います。

  6. 認証済みユーザのみ: サービスグループがユーザ名によるアクセスを許可するように設定されている場合、このスイッチは自動的に 『Yes』 に設定されます。

  7. 関数: アカウントがアクセスできる関数のリスト。

    注釈

    サービスを変更するとき、関数のリストは自動的に更新されません。ページを保存すると、更新されたリストだけが表示されます。

  8. ウェブサービスセキュリティを有効にする(XML-RPCのみ): この機能はXML-RPCベースの認証でだけ使用できます。

  9. 公開鍵: 追加されたウェブサービスセキュリティの公開鍵を入力します(XML-RPCベースの認証の場合だけ)。

  10. 公開鍵の有効期限: 入力した公開鍵の有効期限。日付はフォームを保存すると更新されます。

  11. 変更を完了したら 保存 ボタンをクリックしてください。変更を取り消す場合は 戻る をクリックしてください。

11.10.2. アプリケーション接続

管理メニュー → ウェブサービス → アプリケーション接続

これは個人のユーザトークンまたはOAuthアクセストークンを使用して許可したすべての接続の概要ページです。

アプリケーション接続概要

アプリケーション接続概要

  1. パーソナルユーザトークン セクションには、個人に対して生成したトークンと、それらのトークンがアクセスされたかどうかが表示されます。

  2. サービスアクセス: このカラムではトークンを作成したサービスグループが表示されます。

  3. 有効: サービスグループが有効にされている場合、有効 アイコン が表示されます。有効にされていない場合、無効 アイコン が表示されます。

  4. クライアントアプリケーション: アクセストークンの生成方法を表示します。

  5. トークン: ここにトークンが表示されます。

  6. 関数: サービスグループの一部である関数がリストされ、リンクされています。リンクは選択した関数のウェブサービスのドキュメントに移動します。

  7. 最終アクセス: トークンの最後の使用日時を一覧表示します。

  8. 有効期限: トークンの有効期限を表示します。

  9. 新しいランダムトークンを生成するには 生成 ボタンをクリックしてください。

  10. 削除 ボタン をクリックしてトークンを削除します。ユーザグループと関数は引き続き使用できます。次に、生成 ボタンをクリックして新しいトークンを作成します。

    注釈

    トークンが生成されている場合だけ 削除 ボタンを使用できます。

  11. あなたはOAuthで使用するために生成されたトークンを OAuthアクセストークン セクションで確認できます。

11.10.3. 接続マネージャ

管理メニュー → ウェブサービス → 接続マネージャ

接続マネージャは接続の設定を容易にすることによってウェブサービスの使用を容易にします。

詳細については wiki (オリジナルアイデア)と 機能要求項目 を参照してください。

接続マネージャの概要ページ

接続マネージャの概要

11.10.4. 外部アプリの登録

管理メニュー → ウェブサービス → 外部アプリ

このページを使用してOAuth経由で接続されている外部アプリケーションを登録できます。一例はLTI(Learning Tools Interoperability)です。個人のキーと秘密鍵が自動的に生成されるインスティテューションと特定のサービス定義に対して外部ツールを有効にできます。

外部アプリケーションの登録

外部アプリケーションの登録

  1. アプリケーション: OAuth経由で接続されているアプリケーションを一覧表示します。

  2. オーナ:OAuthサービスを設定し人。

  3. コンシューマキー: OAuthサービスのコンシューマキーです。

  4. コンシューマ秘密鍵: OAuthサービスのコンシューマ秘密鍵です。

  5. 有効: アプリケーションが有効な場合、有効 アイコン が表示されます。有効にされていない場合、無効 アイコン が表示されます。

  6. インスティテューション: 外部アプリが設定されたインスティテューション。

  7. 編集 ボタン をクリックして設定を変更します。

  8. 削除 ボタン をクリックしてアプリケーションを削除して、OAuth経由でMaharaに接続できなくなるようにします。

  9. より多くの設定がどこで利用可能かを決めるために 管理 ボタン をクリックしてください。

  10. アプリケーション: あなたがアプリケーションに付けたい名称を追加してください。

  11. どのインスティテューションがOAuthを介して選択したアプリケーションにアクセスできるかを選択します。

  12. このアプリケーションに関連付けるサービスグループを選択してください。

  13. 追加 ボタンをクリックして選択したサービスのOAuth認証を作成します。アプリケーションを設定できる画面が表示されます(以下参照)。

編集 ボタン をクリックして、設定している接続の詳細を確認できます。

OAuthサービスを設定する

OAuthサービスを設定する

  1. コンシューマキー: 外部サービスのコンシューマキー。

  2. コンシューマ秘密鍵:外部サービスのコンシューマ秘密鍵。

  3. アプリケーションタイトル: アプリケーションのタイトルを変更できます。

  4. サービスオーナ:外部サービスを設定した人。あなた は、サービスのオーナを変更して、すべてがサイト管理者に関連付けられないようにできます。これは、すべてのウェブサービス呼び出しを処理する特定のアカウントを設定する場合に便利です。

  5. アプリケーションURI: アプリケーションのURIです。不要な場合は無視されます。

    注釈

    Mahara 20.10の新機能 アカウント所有者がMaharaに直接ログインするためのLTIを設定し、他の認証方法がない 場合 は、ここにLTIアクティビティのURLを入力して、通知を受け取ったときにログイン用に正しくリダイレクトされるようにすることができます。

  6. コールバックURI: アプリケーションのコールバックURIです。不要な場合は無視されます。

  7. インスティテューション: 外部サービスを設定するインスティテューションを選択します。

  8. サービス: 設定するサービスグループを選択します。

  9. 有効: OAuthが有効な場合、アプリケーションは自動的に有効になります。

  10. 関数: アプリケーションがアクセスできる関数のリストです。

    注釈

    サービスを変更するとき、関数のリストは自動的に更新されません。ページを保存した場合、更新されたリストだけが表示されます。

  11. 変更を完了したら 保存 ボタンをクリックしてください。変更を取り消す場合は 戻る をクリックしてください。

11.10.5. ウェブサービスログ

管理メニュー → ウェブサービス → ログ

ウェブサービスからログを表示し、検索範囲を絞り込むことで、関連する情報だけを表示できます。

ウェブサービスログを検索する

ウェブサービスログを検索する

  1. ユーザ: ログを表示する人のユーザ名を入力してください。一つのユーザ名しか入力できません。サイトに登録されている人の名前またはユーザ名の入力を開始できます。入力時に名前の候補が表示されます。

  2. プロトコル: アカウントに関連付けられているウェブサービスプロトコルを選択します。有効になっているプロトコルだけを表示できます。

  3. 認証タイプ: アカウントに選択した認証のタイプを選択します。オプションは次のとおりです:

    • すべて: 任意の認証タイプのログを表示します。

    • トークン: アカウントがユーザトークンを持っているときだけログを表示します。

    • ユーザ: アカウントがウェブサービスのユーザ名を使用するとログを表示します。

    • OAuth: 人がOAuth経由でログインしたときにだけログを表示する場合、このオプションを選択します。

  4. 関数: 興味のある関数を検索します。

  5. エラーのみ: エラーを含むログ情報だけを表示する場合は、 『Yes』 に切り替えます。

  6. 検索を開始するには Go ボタンをクリックしてください。

検索結果がある場合、結果 エリアに表示されます。

ウェブサービスログの検索結果

ウェブサービスログの検索結果

  1. ユーザ: ログエントリがあるアカウントのユーザ名を表示します。

  2. インスティテューション: アカウントが所属するインスティテューション名を表示します。

  3. プロトコル: 選択したコンテクストのアカウントに関連付けられているプロトコルを表示します。

  4. 認証タイプ: アカウントに関連付けられている認証タイプが表示されます。

  5. 関数: ログエントリのある関数を表示します。

  6. 取得時間: ログエントリの取得に要した時間です。

  7. When: ログエントリが作成された日付を表示します。

  8. あなたは列のタイトルをクリックして列のソート順を変更できます。

  9. Info: ここにエラーメッセージが表示されます。

11.10.6. ウェブサービステストクライアント

管理メニュー → ウェブサービス → テストクライアント

テストクライアントは設定をテストする機会を与えます。これらの機能は別々のテストインスタンスではなく、システム上で実行されることに注意してください。

ウェブサービステストクライアント

ウェブサービステストクライアント

注釈

あなたが設定を開始した時点で一つのプロトコルしか選択されていない場合、プロトコルと認証タイプが表示されます。他のフィールドは何をテストするか決定した後に明らかになります。

  1. プロトコル: 現在有効にされているウェブサービスプロトコルだけが表示されます。一つ以上のプロトコルが表示されている場合、テストしたい一つを選択してください。

  2. 認証タイプ: テストに含みたい認証タイプを選択してください。次のオプションを表示するには 次へ ボタンをクリックしてください。

  3. サービス: テストに含みたいサービスグループを選択してください。次のオプションを表示するには 次へ ボタンをクリックしてください。

  4. 関数: テストに含める関数を選択してください。次のオプションを表示するには 次へ ボタンをクリックしてください。

  5. wstoken: テストしたいアカウントのウェブサービストークンを入力します。

    注釈

    認証タイプの 『ユーザ』 を選択した場合、入力することのできる wspassword フィールドも表示されます。

  6. テストを実行したい場合、実行 ボタンをクリックしてください。テストを中止したい場合、キャンセル をクリックしてください。

テストが実行された場合、画面にテスト結果が表示されます。