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.

Web-Services oder individuelle Protokolle an- und abschalten

1. Web-Services an- oder abschalten: Wenn die Einstellung auf „An“ gesetzt ist, sind Web-Services aktivier und können für die Site genutzt werden.

   Bemerkung

   Wenn Sie den Hauptschalter auf „Aus“ setzen, werden alle aktivierten Protokolle unter „Protokolle an- und ausschalten“ auf ‚aus‘ gesetzt und müssen manuelle wieder aktiviert werden.

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

3. XML-RPC: Setzen Sie es auf „An“ wenn Sie den Remote-Service über XML-Content verwenden wollen. Dieses Protokoll wird von MNet genutzt.

   Bemerkung

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

4. REST: Aktivieren Sie hier das REpresentational State Transfer-Protokoll. Das REST interface unserstützt auch die JSON-Authentifizierung.

5. OAuth: Wenn Sie das OAuth (Open Authentication) Protokoll verwenden wollen, aktivieren Sie es hier.

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

Servicegruppen sind die Zusammenfassungen für den Zugriff eines Nutzers (einfache Authentifizierung) oder Nutzer-Token. Sie sind Sammlungen von Funktionen. Mahara verfügt bereits über einige Servicegruppen und -funktionen, die Sie konfigurieren können. Weitere können noch hinzugefügt werden.

Ü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. Service: Setzen Sie diese auf „An“, um sie zu verwenden. Die individuellen Funktionen stehen darunter.

2. Nur authorisierte Nutzer: Auf „An“ setzen wenn es nur für Nutzer, die sich mit Nutzername und Passwort einloggen, verwendet werden soll.

3. Nutzertokenzugriff: Auf „An“ setzen wenn Sie für Nutzer individuelle Token verwenden wollen , um auf bestimmte Funktionen zuzugreifen.

   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.

4. Der Name der Funktion.

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

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

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

8. Klicken Sie auf den Speichern-Button wenn Sie Ihre Änderungen vorgenommen haben, oder auf Zurück, um diese zu verwerfen.

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. Nutzername: Geben Sie den Nutzernamen ein und klicken Sie auf den Token erstellen-Button, um einen neuen Zugriffs-Token für den Nutzer zu erstellen. Auf dem folgenden Bildschirm können Sie eine Service-Gruppe für diesen Token festlegen. Sie können nur einen Nutzernamen eingeben.

   Bemerkung

   Sie können beginnen den Namen oder Nutzernamen einer bereits registrierten Person eingeben. Sie erhalten Vorschläge zur Auswahl zum eingegeben Namensbestandteil.

2. Token: Der für einen bestimmten Nutzer erstellte Token.

3. Institution: Liste der Institutionen in denen ein Nutzer Mitglied ist.

4. Nutzer: Der Nutzername wird angezeigt und zur Seite der Einstellungen für den Nutzer verlinkt

5. Service: Servicegruppe für die der Token erstellt wurde.

6. Aktiviert: wenn die Servicegruppe aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.

7. WebService-Sicherheit: Wenn Web Service-Sicherheit aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.

8. Funktionen: Dies ist eine Übersicht über alle Funktionen auf die der Token für den gewählten Service Zugriff hat.

9. Klicken Sie auf den Bearbeiten-Button , um Einstellungsänderungen vorzunehmen.

10. Klicken Sie auf den Löschen-Button, um den Token zu entfernen.

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. Nutzername: Überprüfen Sie, ob Sie den richtigen Nutzernamen ausgewählt haben.

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. Klicken Sie auf den Speichern-Button, um die Änderungen zu speichern. Mit dem Zurück-Button heben Sie Ihre Änderungen auf.

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. Nutzername: Geben Sie einen Nutzernamen ein und klicken Sie auf den Hinzufügen-Button. Nun können Sie diesem Nutzer eine Service-Gruppe zuordnen. Sie können nur einen Nutzernamen zuordnen.

   Bemerkung

   Sie können beginnen den Namen oder Nutzernamen einer bereits registrierten Person eingeben. Sie erhalten Vorschläge zur Auswahl zum eingegeben Namensbestandteil.

2. Nutzer: Der Nutzername dem Sie eine Servicegruppe zugewiesen haben wird angezeigt. Er wird verlinkt mit der Accounteinstellungsseite in der Administration.

3. Institution: Liste der Institutionen in denen ein Nutzer Mitglied ist.

4. Service: Die Servicegruppe, die mit dem Nutzer verknüpft ist.

5. Aktiviert: wenn die Servicegruppe aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.

6. WebService-Sicherheit: Wenn Web Service-Sicherheit aktiviert wurde wird das Aktiviert-Icon , andernfalls das Deaktiviert-Icon gezeigt.

7. Funktionen: Liste aller Funktionen auf die der Nutzer im 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 einen Nutzer aus der Service-Gruppe zu entfernen.

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

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

1. Der Nutzername wird angezeigt

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: Wählen Sie eine Service-Gruppe zu der Sie dem Nutzer Zugriff geben wollen aus der Dropdown-Liste. Nur Services, die den Zugriff über den Nutzername erlauben, können ausgewählt werden.

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. Klicken Sie auf den Speichern-Button, um die Änderungen zu speichern. Mit dem Zurück-Button heben Sie Ihre Änderungen auf.

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

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. Klicken Sie auf den Speichern-Button, um die Änderungen zu speichern. Mit dem Zurück-Button heben Sie Ihre Änderungen auf.

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. Nutzer: Tragen Sie den Nutzernamen ein, dessen Logs Sie einsehen wollen. Sie können nur einen Nutzernamen eingeben.

   Bemerkung

   Sie können beginnen den Namen oder Nutzernamen einer bereits registrierten Person eingeben. Sie erhalten Vorschläge zur Auswahl zum eingegeben Namensbestandteil.

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.

7. Nutzer: Den Nutzernamen der Nutzer, die Sie suchen, anzeigen.

8. Institution: Die Institution in der der Nutzer Mitglied ist anzeigen.

9. Protokoll: Das Protokoll anzeigen, das mit dem Nutzer für den Kontext verbunden ist.

10. Authentifizierungstyp: Den Authentifizierungstyp für den Nutzer anzeigen.

11. Funktion: Die gesuchte Funktion anzeigen.

12. Benötigte Zeit: Zeitdauer für das Abrufen des Logs anzeigen.

13. Wann: Datum anzeigen zu dem der Log erstellt wurde. Die Sortierfolge für die Spalte kann angepasst werden.

14. Info: Fehlermeldungen werden hier angezeigt.

9.7.4. WebService Testclient.

Administration → Erweiterungen → Web Services → Web Services Testclient

Der Testclient ermöglicht Ihnen die Einstellungen zu testen. Denken Sie daran, dass die Funktionen auf den Echtsystem ausgeführt werden.

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. Authentifizierungstyp: Wählen Sie den Authentifizierungstyp, den Sie in den Test berücksichtigen wollen.
3. Service: Wählen Sie die Servicegruppe für den Test aus.
4. Funktionen: Wählen Sie die Funktion aus, die Sie testen wollen.
5. wstoken: Geben Sie den WebService-Token für den Nutzer, den Sie testen wollen ein.
6. Klicken Sie auf den Ausführen-Button, um den Test zu starten oder auf Abbrechen, um den Test abzubrechen.

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. Letzter Zugriff: Liste mit Datum und Zeit der letzten verwendeten Token.
7. Ablauf: Zeigt das Ablaufdatum des Tokens.
8. Klicken Sie den Erstellen-Button um ein zufälliges neues Token zu erstellen.
9. Klicken Sie auf den Löschen-Button , um den Token zu löschen. Die Nutzergruppe und Funktionen sind weiter verfügbar. Sie können dann mit dem Erstellen-Button einen neuen Token erstellen.
10. Im OAuth Zugriffstoken-Abschnitt sehen Sie die Token, die mit OAuth verwandt werden.