9.7. Web services

Administration → Erweiterungen → Web Services

Bemerkung

Web Services stehen nur für Site-Administratoren zur Verfügung

WebServices ermöglichen Ihnen Mahara mit anderen Anwendungen zu verknüpfen, die ebenfalls über WebServices/APIs verfügen. Es kann sein, dass Sie zunächst einige Konfigurationen vornehmen müssen oder im Einzelfall auch neue WebServices entwickeln müssen, um die gewünschte Verbindung zu realisieren. Die Mahara WebServices sind ein Framework, dass die Entwicklung weiterer APIs erlaubt durch die Definiton einer Funktion für die erwünschte Aktion und der zugehörigen Interface-Definition.

Um Web-Services zu nutzen muss die Site verschlüsselt aufrufbar sein

9.7.1. Konfiguration

Administration → Erweiterungen → Web Services → Konfiguration

Auf dieser Seite können Sie verschiedene Web-Service-Regeln anlegen, aktivieren oder deaktivieren.

9.7.1.1. Web-Service Hauptschalter und De-/Aktivierung der Protokolle

Sie können Web Services global aktivieren und die Protokolle individuellen je nach Bedarf konfigurieren. Wenn das Protokoll aktiviert wurde kann es für alle Funktionen, Nutzer und Token verwandt werden.

Switch web services and individual protocols on and off

1. Use web services: If set to „Yes“, web services are available to be used on your site.

   Bemerkung

   If you set the master switch to „No“, any activated individual protocols under „Protocol“ are turned off and would need to be enabled manually again when you switch web services on again.

2. SOAP: Erlaubt dieses Protokoll: Simple Object Access Protocol.

3. XML-RPC: Set this to „Yes“ if you want to make remote procedure calls to XML content. This protocol is used by MNet.

   Bemerkung

   Solange MNet von Mahara unterstützt wird, können Sie dies für die Konfiguration Ihrer Verbindung zu Moodle nutzen.

4. REST: Allow the REpresentational State Transfer protocol by switching this setting to „Yes“. The REST interface also supports JSON authentication.

5. OAuth: If you want to use the OAuth (Open Authentication) protocol, switch this setting to „Yes“.

9.7.1.2. Netzwerkzertifikate

In diesem Abschnitt wird der Public Key für Ihr Mahara Zertifikat erzeugt: Administration → Site-Konfiguration → Netzwerk.

9.7.1.3. Verwalten Sie die Service-Gruppen

Service groups are the units of allocation of access to a user (simple authentication) or user tokens. 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.

Übersicht über die verfügbaren Servicegruppen und ihre Grundeinstellungen

1. Service: Servicegruppe mit mehreren zugeordneten Funktionen, die an- oder abgeschaltet werden kann.

2. Komponente: Der Bereich durch den eine Servicegruppe abgewickelt wird, meist „WebService“:

3. Aktiviert: Sie sehen das Aktiviert-Icon wenn eine Servicegruppe aktiv ist. Andernfalls wird das Deaktiviert-Icon gezeigt .

4. Nur für autorisierte Nutzer: Wenn eine Servicegruppe für Nutzer verwandt wird, die mit Nutzerkennwort und Passwort eingeloggt werden sehen sie das Aktiviert-Icon. Falls es für diese Nutzer nicht verfügbar ist wird das Deaktiviert-Icon angezeigt

5. Nutzer-Token- Zugriff*: Sie sehen das Aktiviert-Icon wenn der Zugriff auf die Funktion einen Nutzer-Token erfordert. Das Deaktiviert-Icon ist sichtbar wenn der Zugriff über einen Nutzer-Token nicht zugelassen ist.

6. Funktionen: Dies ist eine Liste von Funktionen, die mit dieser Servicegruppe verbunden sind.

   Bemerkung

   Sie können die Funktionen anklicken und damit die Dokumentation des entsprechenden WebServices aufrufen. Diese enthält weitere Beschreibungen der Funktions API, Eingabe- und Ausgabe-Parameter und Fehlercode.

7. Klicken Sie auf den Bearbeiten-Button um Änderungen an der Servicegruppe vorzunehmen.

8. Klicken Sie auf den Löschen-Button , um die Servicegruppe zu löschen.

   Bemerkung

   In einigen Situationen ist es nicht sinnvoll eine Servicegruppe ganz zu löschen. Wenn Sie sie evtl. später bearbeiten oder erweitern wollen, sollten Sie sie nur deaktivieren.

9. Klicken Sie auf den Hinzufügen-Button, um eine neue Servicegruppe anzulegen. Die neue Gruppe wird in der Liste aufgenommen. Über den Bearbeiten-Button können sie ihn konfigurieren.

Nachdem Sie eine Servicegruppe zum Bearbeiten ausgewählt haben sehen Sie diese Seite.

Einstellungen einer Servicegruppe bearbeiten

1. Name of the service group

2. Service: Set this switch to „Yes“ if you want to use this service group. You can tweak the individual functions below.

3. Authorised users only: Set this switch to „Yes“ if only people with a username and password should be affected by this service group.

4. User token access: Set this switch to „Yes“ if you want users to have individual tokens in order to access certain functionalities.

   Bemerkung

   Der Nutzer-Token-Zugriff gibt der gesamten Mahara-Nutzerbasis die Möglichkeit die API zu nutzen. Um dies zu kontrollieren sollte der Zugriff auf Servicegruppen beschränkt werden, den Zugriff wiederum bestimmten Nutzern vorbehalten wird. Ein Beispiel: mahara_user_get_my_user für die Details eines Nutzeraccounts.

5. Der Name der Funktion.

6. Aktiviert: Die Einstellung aktiviert bzw. deaktiviert den Gebrauch der Funktion.

7. Class-Name: Name der Class, die Teil der Funktion ist.

8. Methoden-Name: Name der aufgerufenen Methode. Der Link bringt Sie zur Dokumentation für die jeweilige Methode.

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

9.7.1.4. Verwalten Sie den Zugangsservice zu Token

Sie können Zugriffstoken für individuelle Nutzer und zugewiesene Servicegruppen erzeugen, damit die Nutzer Zugriff erhalten.

Übersicht über Zugriffstoken

1. Token: Der für einen bestimmten Nutzer erstellte Token.
2. Institution: Liste der Institutionen in denen ein Nutzer Mitglied ist.
3. Nutzer: Der Nutzername wird angezeigt und zur Seite der Einstellungen für den Nutzer verlinkt
4. Service: Servicegruppe für die der Token erstellt wurde.
5. Aktiviert: wenn die Servicegruppe aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.
6. Web services security: If web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .
7. Funktionen: Dies ist eine Übersicht über alle Funktionen auf die der Token für den gewählten Service Zugriff hat.
8. Klicken Sie auf den Bearbeiten-Button , um Einstellungsänderungen vorzunehmen.
9. Klicken Sie auf den Löschen-Button, um den Token zu entfernen.
10. Username: Type a username of a user for whom you wish to add a token. 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.
11. 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.

Wenn Sie einen Token für einen Nutzer erstellen sind einige weitere Informationen erforderlich.

Service-Zugriffstoken konfigurieren

1. Stellen Sie fest, ob Sie den richtigen Token bearbeiten

2. Institution: legen Sie die Institution des Nutzers fest.

3. Username: Verify that you have the correct username for which you want to set up a token. The username is linked to the user’s settings page in the administration.

4. Service: Wählen Sie aus der Drop-down-Liste die Service-Gruppe für die Sie den Token erstellen wollen. Es können nur solche Services ausgewählt werden, die einen Nutzertoken zulassen.

5. Aktiviert: Der Token wird automatisch aktiviert wenn die Service-Gruppe aktiviert wird.

   Bemerkung

   Wenn Sie eine Service-Gruppe deaktivieren tun Sie dies unter Service-Gruppen verwalten.

6. Nur authorisierte Nutzer: Diese Checkbox wird hier nicht angewandt, da Siee einen Token verwenden.

7. Funktionen: Eine Liste der Funktionen auf die der Token Zugriff hat.

   Bemerkung

   Wenn Sie den Service ändern wird die Liste der Services erst aktualisiert nachdem Sie die Seite abgespeichert haben.

8. Web-Services-Sicherheit aktivieren (nur für XML-RPC): Diese Funktion existiert nur für die XML-RPC basierte Authentifizierung.

9. Public Key: Geben Sie den Public Key für die Web Service Sicherheit ein (nur für XML-RPC basierte Authentifizierung).

10. Public Key Gültigkeit: Datum zu dem der eingegeben Public Key abläuft. Das Datum wird nur durch Speichern der Seite abgespeichert.

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

9.7.1.5. Service Nutzer verwalten

Wenn Sie nicht beabsichtigen einen Token für Ihre Nutzer zu verwenden, können Sie ihnen Zugriff auf Funktionen mittel Nutzernamen geben. Dazu können Sie diese Option nutzen. Nutzer müssen dann:

• nur einmalig konfiguiriert.

• haben die „Webservice“-Authentifizierungsmethode in einer Institution in der sie Mitglied sind.

  Bemerkung

  Nutzer mit der Authentifizierungsmethode „WebService“ können auf Mahara nur über den WebService zugreifen und sich nicht direkt mit dem Standard-Login-Formular einloggen.

Verwaltung der Service Nutzer-Übersicht

1. Nutzer: Der Nutzername dem Sie eine Servicegruppe zugewiesen haben wird angezeigt. Er wird verlinkt mit der Accounteinstellungsseite in der Administration.
2. Institution: Liste der Institutionen in denen ein Nutzer Mitglied ist.
3. Service: The service group that is associated with the user.
4. Aktiviert: wenn die Servicegruppe aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.
5. Web services security: If web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .
6. Funktionen: Liste aller Funktionen auf die der Nutzer im gewählten Service Zugriff hat.
7. Klicken Sie auf den Bearbeiten-Button , um Einstellungsänderungen vorzunehmen.
8. Klicken Sie auf den Löschen-Button , um einen Nutzer aus der Service-Gruppe zu entfernen.
9. Username: Type a username of a user for whom you wish to manage the services. 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. The user must have web services as authentication method.
10. 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.

Wenn Sie einen Nutzer hinzufügen sind weitere Informationen erforderlich.

Verknüpfen Sie einen Nutzer mit einer Service-Gruppe.

1. Service owner: The username is displayed. It must match the username below.

2. Institution: Stellen Sie sicher, dass die Institution des Nutzers korrekt ist. Wenn Sie nicht stimmt, passen Sie sie auf der Accounteinstellungsseite an.

3. Nutzername: Überprüfen Sie, ob Sie den richtigen Nutzernamen ausgewählt haben.

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

5. Aktiviert: Die Einstellungen werden automatisch aktiviert wenn die Servicegruppe aktiviert wird.

   Bemerkung

   Wenn Sie eine Service-Gruppe deaktivieren tun Sie dies unter Service-Gruppen verwalten.

6. Nur für authorisierte Nutzer: Die Checkbox wird automatisch ausgewählt wenn die Servicegruppe den Zugriff über den Nutzernamen zulässt.

7. Funktionen: Eine Liste der Funktionen auf die der Nutzer Zugriff hat.

   Bemerkung

   Wenn Sie den Service ändern wird die Liste der Services erst aktualisiert nachdem Sie die Seite abgespeichert haben.

8. Web-Services-Sicherheit aktivieren (nur für XML-RPC): Diese Funktion existiert nur für die XML-RPC basierte Authentifizierung.

9. Public Key: Geben Sie den Public Key für die Web Service Sicherheit ein (nur für XML-RPC basierte Authentifizierung).

10. Public Key Gültigkeit: Datum zu dem der eingegeben Public Key abläuft. Das Datum wird nur durch Speichern der Seite abgespeichert.

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

9.7.2. OAuth Service Registrierung

Administration → Erweiterungen → Web Services → OAuth

Der OAuth Servicezugriff wird separat konfiguriert. Diese Einstellung aktiviert die Auswahl der Institution und der Servicedefinition für die ein Consumer Key und Secret automatisch erzeugt wird.

Einen OAuth Service registrieren

1. Applikation: Liste der Applikationen, die über OAuth verbunden sind.
2. Eigentümer: Nutzer, der den OAuth-Service angelegt hat.
3. Consumer Key: Der Consumer Key für den OAuth Service.
4. Consumer Secret: Der Consumer Secret für den OAuth Service.
5. Aktiviert: Wenn die Applikation aktiviert wurde sehen Sie das Aktiviert-Icon. Andernfalls das Deaktiviert-Icon .
6. Callback URI: Die Callback URI für die Applikation.
7. Klicken Sie auf den Bearbeiten-Button , um Einstellungsänderungen vorzunehmen.
8. Klicken Sie auf den Löschen-Button um die Applikation zu entfernen, damit Sie sich nicht mehr über OAuth mit Mahara verbinden kann.
9. Application: Geben Sie der Applikation, die Sie verwenden wollen, einen Namen.
10. Legen Sie fest welche Institution Zugriff auf die gewählte Applikation über OAuth haben soll.
11. Wählen Sie die Service-Gruppe fest, die Sie mit der Applikation vernbinden wollen.
12. Klicken Sie auf den Hinzufügen-Button, um die OAuth Authentifizierung für den gewählten Service zu erstellen. Auf der nächsten Seite können Sie weitere Konfigurationen vornehmen.

Wenn Sie es zulassen wollen, dass sich eine andere Applikation über OAuth mit Mahara verbindet, müssen einige weitere Informationen hinterlegt werden.

Einen OAuth Service konfigurieren

1. Server Key: Der Consumer Key für den OAuth Service.

2. Consumer Secret: Der Consumer Secret für den OAuth Service.

3. Titel der Applikation: Geben Sie der Applikation, die Sie hinzufügen, einen Namen.

4. Service Eigentümer: Nutzer, der den OAuth Service angelegt hat.

5. Applikation URI: URI der Applikation.

6. Callback URI: Die Callback URI für die Applikation.

7. Institution: Wählen Sie die Institution für die Sie OAuth aktivieren wollen.

8. Service: Wählen Sie die Servicegruppe für den OAuth-Service.

9. Aktiviert: Die Applikation ist automatisch aktiv wenn OAuth aktiviert wird.

10. Funktionen: Eine Liste der Funktionen auf die die Applikation Zugriff erhält.

    Bemerkung

    Wenn Sie den Service verändern wird die Liste der Services nicht automatisch angepasst. Sie aktualisierten Services werden erst nach dem Abspeichern sichtbar.

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

9.7.3. Web Service-Protokolle

Administration → Erweiterungen → Web Services → Web Services Logs

Sie können die Logs des WebServices einsehen und die Suche einschränken um nur die relevanten Informationen zu sehen.

Suche in den WebService-Logs

1. User: Type the username of the person for whom you want to see the logs. 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. Protokoll: Wählen Sie das WebService-Protokoll, das mit dem Nutzer verbunden ist. Sie können nur aktivierte Protokolle sehen.
3. Authentifizierungstyp: Wählen Sie den für den Nutzer verfügbaren Typ aus. Optionen sind:
   • Alle: Die Logs für jeden Authentifizierungstyp anzeigen.
   • Token: Nur Logs für Nutzer anzeigen, die einen Nutzertoken haben.
   • Nutzer: Logs anzeigen für Nutzer, die den Nutzernamen für WebService verwenden.
   • OAuth: Wählen Sie diese Option wenn Sie nur Logs für Nutzer anzeigen lassen wollen, die OAuth verwenden.
4. Funktion: Suche nach Funktionen.
5. Nur Fehler: Nur Logs anzeigen, die über Fehler berichten.
6. Klicken Sie auf den Starten-Button, um die Suche zu beginnen.

If there are any results for your search, you will see them in the Results area.

Results for the search of the web services logs

1. User: Display the username of the user for which there is a log entry.
2. Institution: Die Institution in der der Nutzer Mitglied ist anzeigen.
3. Protokoll: Das Protokoll anzeigen, das mit dem Nutzer für den Kontext verbunden ist.
4. Authentifizierungstyp: Den Authentifizierungstyp für den Nutzer anzeigen.
5. Function: Display the function for which there is a log entry.
6. Time taken: The time it took to fetch the log entry.
7. When: Display the date that the log entry was produced.
8. You can change the sort order for any column by clicking its column title.
9. Info: Fehlermeldungen werden hier angezeigt.

9.7.4. WebService Testclient.

Administration → Erweiterungen → Web Services → Web Services Testclient

The test client gives you the opportunity to test your settings. Please beware that the functions are executed on the system and not a separate test instance.

WebService Testclient.

Bemerkung

Wenn Sie die Konfiguration vornehmen sehen Sie zunächst nur das Protokoll und den Authentifizierungystyp, den Sie ausgewählt haben. Die anderen Felder werden erst sichtbar wenn Sie die Entscheidung getroffen haben,was Sie testen wollen.

1. Protokoll: Sie sehen die Web Services Protokolle, die aktuell aktiviert sind. Wenn Sie mehr als eines sehen, wählen Sie dasjenige aus, das Sie testen wollen.

2. Authentication type: Select the authentication type that you would like to include in your test. Click the Next button to see the following option.

3. Service: Choose the service group that you want to test. Click the Next button to see the following option.

4. Functions: Select the function that you want to include in your test. Click the Next button to see the following option.

5. wstoken: Geben Sie den WebService-Token für den Nutzer, den Sie testen wollen ein.

   Bemerkung

   If you selected „User“ for the authentication type, you’ll also see a field wspassword that you can fill in.

6. Click the Execute button if you want to run the test, or click Cancel if you want to abort the test.

Nachdem der Test durchgelaufen ist werden die Ergebnisse angezeigt.

9.7.5. Anwendungsverbindungen

Administration → Erweiterungen → Web Services → Anwendungsverbindungen

Dies ist eine Übersicht über alle Verbindungen, die Sie über persönliche Nutzertoken oder OAuth Zugriffstoken erlaubt haben.

Übersicht über die Anwendungsverbindungen

1. Der Abschnitt Persönliche Nutzer-Token zeigt alle Token, die Sie für einzelne Nutzer erstellt haben und ob diese genutzt wurden.

2. Service-Zugriff: Die Spalte zeigt die Service-Gruppe für die ein Token erstellt wurde.

3. Aktiviert: Wenn die Servicegruppe aktiviert ist, sehen Sie das*Aktiviert*-Icon , andenfalls das Deaktiviert-Icon .

4. Token: Der Token wird hier angezeigt.

5. Funktionen: Die Funktionen einer Servicegruppe sind hier aufgelistet und verlinkt. Die Links führen zur Webservice-Dokumentation der jeweiligen Funktion.

6. Last access: List the date and time of the last use of the token.

7. Expires: Show the expiry date of the token.

8. Click the Generate button to generate a new random token.

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.

   Bemerkung

   The Delete button is only available when a token was generated.

10. Im OAuth Zugriffstoken-Abschnitt sehen Sie die Token, die mit OAuth verwandt werden.