10.10. ウェブサービス

管理 → ウェブサービス

Note

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

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

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

10.10.1. 設定 (Configuration)

管理→ ウェブサイト → 設定

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

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

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

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

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

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

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

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

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

    Note

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

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

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

Note

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

10.10.1.2. ネットワーク証明書

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

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

サービスグループはユーザへのアクセス（単純認証）またはユーザトークンの割り当て単位です。それらは関数の集まりです。Maharaにはすでに設定可能な一連のサービスグループと機能が用意されています。さらに多くのサービスグループを追加できます。

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

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

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

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

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

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

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

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

    Note

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

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

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

    Note

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

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

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

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

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

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

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

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

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

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

    Note

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

  6. 関数の名前。

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

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

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

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

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

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

アクセストークンの概要

アクセストークンの概要

  1. トークン: 特定のユーザ用に生成されたトークン。

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

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

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

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

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

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

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

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

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

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

ユーザのトークンを作成する場合、追加情報を入力する必要があります。

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

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

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

  2. インスティテューション: ユーザのインスティテューションを選択します。

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

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

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

    Note

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

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

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

    Note

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

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

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

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

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

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

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

  • 一度だけ設定される。

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

    Note

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

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

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

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

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

  3. サービス: ユーザに関連付けられているサービスグループ。

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

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

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

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

  8. 関連するサービスグループへのアクセスからユーザを削除するには 削除 ボタン をクリックしてください。

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

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

ユーザを追加する場合、追加情報を入力する必要があります。

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

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

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

  2. インスティテューション: ユーザのインスティテューションが正しいことを確認します。そうでない場合、ユーザの アカウント設定ページ でインスティテューションを変更できます。

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

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

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

    Note

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

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

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

    Note

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Note

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

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

10.10.3. 接続マネージャ

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

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

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

Overview page for the connection manager

接続マネージャの概要

10.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を介してMaharaに接続されるようにするにはさらに情報を提供する必要があります。

OAuthサービスを設定する

OAuthサービスを設定する

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

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

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

  4. サービスオーナ: OAuthサービスを設定したユーザです。

  5. アプリケーションURI: アプリケーションのURIです。

  6. コールバックURI: アプリケーションのコールバックURIです。

  7. インスティテューション: OAuthを設定するインスティテューションを選択してください。

  8. サービス: あなたがOAuth用に設定したいサービスグループを選択してください。

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

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

    Note

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

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

10.10.5. ウェブサービスログ

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

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

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

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

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

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

  3. 認証タイプ: ユーザに対して選択した認証のタイプを選択します。オプションは次のとおりです:

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

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

    • ユーザ: ユーザがウェブサービスのユーザ名を使用した場合、ログを表示します。

    • OAuth: ユーザのOAuth経由ログイン時のみログを表示したい場合、このオプションを選択してください。

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

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

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

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

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

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

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

  2. インスティテューション: ユーザがメンバであるインスティテューション名を表示します。

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

  4. 認証タイプ: ユーザに関連付けられている認証タイプが表示されます。

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

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

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

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

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

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

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

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

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

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

Note

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

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

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

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

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

  5. wstoken: あなたがテストしたいユーザのウェブサービストークンを入力してください。

    Note

    あなたが認証タイプの「ユーザ」を選択した場合、あなたが入力できる wspassword フィールドも表示されます。

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

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