10.9. 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.

In order to use web services, your site must use a SSL certificate. When your site is not in production mode, you can test web services without SSL.

10.9.1. Konfiguration

Administration → Erweiterungen → Web Services → Konfiguration

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

10.9.1.1. Enable web service functionality

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

Switch web services and individual protocols on and off

  1. Allow outgoing web service requests: If set to „Yes“, web services are available to be used on your site for outgoing calls.

  2. Accept incoming web service requests: If set to „Yes“, web services are available to be used on your site for incoming calls, for example via Mahara Mobile.

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

  4. 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.

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

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

Bemerkung

If you disable web services, any activated individual protocols under “Protocol” are turned off and would need to be enabled manually again when you switch web services on again.

10.9.1.2. Netzwerkzertifikate

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

10.9.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.

Overview of the available service groups and their basic settings

Ü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.

Edit the settings of a service group

Einstellungen einer Servicegruppe bearbeiten

  1. Name: Name of the service group

  2. Short name: This is a short name for the service that is required by applications that connect to Mahara in order to refer to this service.

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

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

  5. 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.

  6. Der Name der Funktion.

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

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

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

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

10.9.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.

Overview of the access tokens

Ü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.

Configure a service access token

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. Authorised users only: This switch is not used in this context because here you create a token. That’s why it is disabled.

  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.

10.9.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.

Manage service users overview section

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.

Associate a user with a specific service group

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. Authorised users only: This switch is set to „Yes“ automatically when the service group is configured to allow access via a username.

  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.

10.9.2. Anwendungsverbindungen

Administration → Erweiterungen → Web Services → Anwendungsverbindungen

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

Overview of the application connections

Ü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. Client app: Display how the access token was generated.

  5. Token: Der Token wird hier angezeigt.

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

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

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

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

  10. 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.

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

10.9.3. Connection manager

Administration → Extensions → Web services → Connection manager

The connection manager facilitates the use of web services by making the setup of connections easier.

For more information, see the wiki (original idea) and the feature request item.

Overview page for the connection manager

Overview for the connection manager

10.9.4. Registration of external apps

Administration → Extensions → Web services → External apps

new in Mahara 17.04 The „OAuth“ page was renamed to „External apps“ to make it clearer what you can do here.

You can use this page to register external applications that are connected via OAuth. An example is LTI (Learning Tools Interoperability). You can enable external tools for institutions and specific service definitions, for which a consumer key and secret will be generated automatically.

Register an external application

Register an external application

  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. new in Mahara 17.04 Institution: The institution for which the external app has been set up.
  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. new in Mahara 17.04 Click the Manage button to decide on more settings where available.
  10. Application: Geben Sie der Applikation, die Sie verwenden wollen, einen Namen.
  11. Legen Sie fest welche Institution Zugriff auf die gewählte Applikation über OAuth haben soll.
  12. Wählen Sie die Service-Gruppe fest, die Sie mit der Applikation vernbinden wollen.
  13. 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.

Configure an OAuth service

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.

10.9.5. 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.

Search the web services logs

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. Only errors: Switch to „Yes“ if you only want to see log information that contains an error.
  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

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.

10.9.6. 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.

Web services test client

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.