10.10. ウェブサービス

管理 → ウェブサービス

注釈

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

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

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

10.10.1. 設定 (Configuration)

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

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

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

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

Switch web services and individual protocols on and off

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

  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」 に切り替えます。

注釈

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

10.10.1.2. ネットワーク証明書

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

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

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

Overview of the available service groups and their basic settings

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

  1. サービス: いくつかの関連する機能をグループ化して有効または無効にできるサービスグループ。

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

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

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

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

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

    注釈

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

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

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

    注釈

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

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

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

Edit the settings of a service group

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

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

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

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

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

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

    注釈

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

  6. 関数の名前。

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

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

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

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

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

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

Overview of the access tokens

アクセストークンの概要

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

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

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

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

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

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

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

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

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

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

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

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

Configure a service access token

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

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

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

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

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

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

    注釈

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

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

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

    注釈

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

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

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

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

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

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

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

  • 一度だけ設定される。

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

    注釈

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

Manage service users overview section

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

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

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

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

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

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

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

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

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

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

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

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

Associate a user with a specific service group

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

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

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

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

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

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

    注釈

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

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

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

    注釈

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

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

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

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

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

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

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

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

Overview of the application connections

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

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

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

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

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

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

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

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

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

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

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

    注釈

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

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

10.10.3. 接続マネージャ

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

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

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

Overview page for the connection manager

接続マネージャの概要

10.10.4. 外部アプリの登録

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

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

Register an external application

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

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

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

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

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

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

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

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

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

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

  10. アプリケーション:アプリケーションに名前を追加するよう指示します。

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

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

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

アプリケーションがOAuthを介してMaharaに接続されるようにするには、さらに情報を提供する必要があります。

Configure an OAuth service

OAuthサービスを設定する

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

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

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

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

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

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

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

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

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

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

    注釈

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

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

10.10.5. ウェブサービスログ

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

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

Search the web services logs

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

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

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

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

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

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

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

    • OAuth: ユーザがOAuth経由でログインしたときにだけログを表示する場合、このオプションを選択してください。

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

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

  6. 検索を開始するには Go ボタンをクリックします。

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

Results for the search of the web services logs

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

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

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

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

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

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

  6. 取得時間: ログエントリを取得するまでにかかった時間。

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

  8. 列のタイトルをクリックすると、列のソート順を変更できます。

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

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

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

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

Web services test client

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

注釈

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

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

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

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

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

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

    注釈

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

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

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