9.7. Web services

管理 → 拡張機能 → ウェブサービス （【訳注】 「拡張機能」 は不要）

注釈

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

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

In order to use web services, your site must use a SSL certificate.

9.7.1. 設定 (Configuration)

管理 → 拡張機能 → ウェブサービス → 設定 （【訳注】 「拡張機能」 は不要）

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

9.7.1.1. Web services master switch and switching protocols on and off

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

Switch web services or individual protocols on and off

1. Switch web services on or off: If set to 「On」, web services are available to be used on your site.

   注釈

   If you set the master switch to 「Off」, any activated individual protocols under 「Switch protocols on and off」 are turned off and would need to be enabled manually again.

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

3. XML-RPC: Set this to 「On」 if you want to make remote procedure calls to XML content. This protocol is used by MNet.

   注釈

   MNetがMaharaでサポートされる限り、Moodleへの接続を設定する ためにそれを使用することができます。

4. REST: Allow the REpresentational State Transfer protocol by turning this setting on. The REST interface also supports JSON authentication.

5. OAuth: If you want to use the OAuth (Open Authentication) protocol, turn this setting on.

9.7.1.2. ネットワーク証明書

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

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

Service groups are the unit of allocation of access to a user (simple authentication) or user token. They are a collection of functions. Mahara already comes with a series of service groups and functions that you can configure. More service groups can be added.

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

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

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

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

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

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

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

   注釈

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

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

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

   注釈

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

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

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

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

1. Service: Set this to 「On」 if you want to use this service group. You can tweak the individual functions below.

2. Authorised users only: Set this to 「On」 if only people with a username and password should be affected by this service group.

3. User token access: Set this to 「On」 if you want users to have individual tokens in order to access certain functionalities.

   注釈

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

4. 関数の名前。

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

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

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

8. Click the Save button when you are finished making your changes, or click the Back button if you want to cancel the changes.

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

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

アクセストークンの概要

1. Username: Type a username and click the Generate token button for a new access token to be created for that user. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username.

   注釈

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

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

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

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

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

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

7. Web services security: If the web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .

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

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

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

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

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

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

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

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

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

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

   注釈

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

6. Authorised users only: This checkbox is not used in this context because here you create a token.

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

   注釈

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

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

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

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

11. あなたの変更を保存するには*保存*ボタンをキャンセルするには*戻る*ボタンをクリックしてください。

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

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

• 一度だけ設定される。

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

  注釈

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

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

1. Username: Type a username and click the Add button. You are taken to a screen where you can associate a service group to that user (see below). You can only enter one username.

   注釈

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

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

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

4. Service: The service group that is associated with the user.

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

6. Web services security: If the web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .

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

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

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

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

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

1. ユーザ名が表示されます。

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

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

4. Service: Choose the service group from the drop-down list to which you want to give the user access. Only services that allow access via a username can be chosen.

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

   注釈

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

6. Authorised users only: This checkbox is selected automatically when the service group is configured to allow access via a username.

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

   注釈

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

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

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

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

11. あなたの変更を保存するには*保存*ボタンをキャンセルするには*戻る*ボタンをクリックしてください。

9.7.2. OAuthサービス登録

管理 → 拡張機能 → Webサービス → OAuth （【訳注】 「拡張機能」 は不要）

OAuthサービスへのアクセスは個別に設定されます。これにより、コンシューマーキーと秘密鍵が自動的に生成されるインスティテューションとサービス定義の選択が可能になります。

OAuthサービスを登録する

1. アプリケーション：アプリケーションに名前を追加するよう指示します。
2. どのインスティテューションがOAuthを介して選択したアプリケーションにアクセスできるかを選択します。
3. このアプリケーションに関連付けるサービスグループを選択します。
4. 追加 ボタンをクリックして、選択したサービスのOAuth認証を作成します。アプリケーションを設定できる画面が表示されます（下記参照）。
5. アプリケーション：OAuth経由で接続されているアプリケーションを一覧表示します。
6. オーナ：OAuthサービスを設定したユーザ。
7. コンシューマキー：OAuthサービスのコンシューマキー。
8. コンシューマ秘密鍵：OAuthサービスのコンシューマ秘密鍵。
9. 有効：アプリケーションが有効な場合は、有効 アイコン が表示されます。有効になっていない場合は、無効 アイコン が表示されます。
10. コールバックURI: アプリケーションのコールバックURI。
11. 編集 ボタン をクリックして設定を変更します。
12. 削除 ボタン をクリックして、アプリケーションを削除して、OAuth経由でMaharaに接続できなくなるようにします。

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

OAuthサービスを設定する

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

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

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

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

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

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

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

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

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

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

    注釈

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

11. あなたの変更を保存するには*保存*ボタンをキャンセルするには*戻る*ボタンをクリックしてください。

9.7.3. ウェブサービスログ

管理 → 拡張機能 → ウェブサービス → ログ （【訳注】 「拡張機能」 は不要）

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

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

1. ユーザ: あなたが閲覧したい人のログのユーザ名を入力してください。

   注釈

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

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

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

   • すべて: 任意の認証タイプのログを表示します。
   • トークン: ユーザがユーザトークンを持っているときだけログを表示します。
   • ユーザ: ユーザがウェブサービスのユーザ名を使用するとログを表示します。
   • OAuth: ユーザがOAuth経由でログインしたときにだけログを表示する場合は、このオプションを選択します。

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

5. Only errors: Tick this checkbox if you only want to see log information that contains an error.

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

7. User: Display the username of the user that you searched on.

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

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

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

11. 関数: あなたが検索した関数が表示されます。

12. 所要時間: ログの取得に要した時間です。

13. When: Display the date that the log entry was produced. You can change the sort order for this column.

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

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

管理 → 拡張機能 → ウェブサービス → テストクライアント （【訳注】 「拡張機能」 は不要）

テストクライアントはあなたに設定をテストする機会を与えます。実行される関数はシステム上で実際に実行される点に留意してください。

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

注釈

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

1. プロトコル: あなたには現在有効にされているウェブサービスプロトコルだけが表示されます。一つ以上のプロトコルが表示されている場合、あなたがテストしたい一つを選択してください。
2. 認証タイプ: あなたのテストに含みたい認証タイプを選択してください。
3. サービス: あなたがテストしたいサービスグループを選択してください。
4. 関数: あなたのテストに含みたい関数を選択してください。
5. wstoken: あなたがテストしたいユーザのウェブサービストークンを入力します。
6. あなたがテストを実行したい場合、*実行*ボタンをクリックしてください。テストを中止したい場合、*キャンセル*ボタンをクリックしてください。

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

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

管理 → 拡張機能 → ウェブサービス → アプリケーション接続 （【訳注】 「拡張機能」 は不要）

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

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

1. パーソナルユーザトークン セクションには、個々のユーザに対して生成したトークンと、それらのトークンがアクセスされたかどうかが表示されます。
2. サービスアクセス: このカラムではあなたがトークンを作成したサービスグループが表示されます。
3. 有効: サービスグループが有効にされている場合、有効 アイコン が表示されます。有効にされていない場合、無効 アイコン が表示されます。
4. トークン: ここにトークンが表示されます。
5. 関数: サービスグループの一部である関数がリストされ、リンクされています。リンクは、選択した関数のウェブサービスのドキュメントに移動します。
6. 最終アクセス: トークン使用の最終日時が一覧表示されます。
7. 有効期限: トークンの有効期限を表示します。
8. 新しいランダムトークンを作成するには*生成*ボタン|manage|をクリックしてください。
9. Click the Delete button to delete the token. The user group and functions are still available. You can then click the Generate button to create a new token.
10. あなたはOAuthで使用するために生成されたトークンを*OAuthアクセストークン*セクションで確認することができます。