IBM MaaS360 -API-Referenz für Web-Services

IBM® MaaS360® bietet eine Reihe leistungsfähiger RESTful-Webdienste, die es Administratoren und Entwicklern ermöglichen, programmgesteuert mit der Plattform zu interagieren und Geräte, Anwendungen, Benutzer und vieles mehr zu verwalten. Im folgenden Abschnitt wird anhand praktischer Beispiele erläutert, wie Sie auf die API-Dokumentation zugreifen, Ihre Anwendung authentifizieren und echte API-Aufrufe ausführen können.

Die API-Referenz für Webdienste enthält Informationen wie Implementierungshinweise, für die Ausführung der API erforderliche Attribute, Details zur Zugriffskontrolle, Antwortklassen mit Modellbeispielen sowie Angaben zu den Parametern.

Zugriff auf die API-Dokumentation im IBM MaaS360 -Portal

Die Administratoren müssen die Web Services Rolle, um die Dokumentation der Webdienste anzuzeigen und mit ihr zu interagieren sowie Zugriffsschlüssel direkt im IBM MaaS360 Portal zu verwalten.

Die Nutzung der API unterliegt denselben rollenbasierten Zugriffskontrollen wie der Zugriff auf das Standardportal. Stellen Sie sicher, dass dem API-Dienstkonto die entsprechenden Rollen zugewiesen sind, damit die erforderlichen Aufgaben ausgeführt werden können. Weitere Informationen finden Sie unter „Zugriffsrollen und -rechte für IBM MaaS360 Portaladministratoren “.

So greifen Sie auf die Dokumentation zu

Folgen Sie den Anweisungen, um auf die Dokumentation der Web Services API im IBM MaaS360 Portal zuzugreifen.
  1. Klicken Sie auf der Startseite IBM MaaS360 Portals auf Setup > Web Services API > Dokumentation.
    Wichtig: Wenn Sie die Dokumentation testen, müssen Sie Ihr Konto oder dasselbe Konto verwenden, mit dem Sie sich angemeldet haben.
  2. Entdecken Sie die nach Kategorien geordneten Endpunkte (Authentifizierung, Geräteverwaltung, App-Verwaltung).
  3. Geben Sie die Werte für die Parameter ein, die im Request-Body des API-Aufrufs aufgeführt sind, den Sie ausprobieren möchten.

    Die integrierte Dokumentationsschnittstelle hilft Ihnen dabei, API-Aufrufe interaktiv zu testen, sodass Sie Anfragen leichter überprüfen und Antworten genauer unter die Lupe nehmen können, bevor Sie diese in Ihre Arbeitsabläufe integrieren.

Authentifizierung: Erste und zwingend erforderliche Anfrage

Wichtig: Bevor Sie einen Webdienst von IBM MaaS360 nutzen, muss sich Ihre Anwendung authentifizieren und ein gültiges Authentifizierungstoken abrufen. Nachdem das Token generiert wurde, ist es für 60 minutes gültig; danach muss ein neues Token angefordert werden. Alle nachfolgenden Webservice-Aufrufe müssen dieses Token enthalten.

Um ein Authentifizierungstoken anfordern zu dürfen, muss die Anwendung zunächst die Berechtigung zur Nutzung der Webdienste erhalten provisioned within IBM MaaS360 haben. Weitere Informationen finden Sie unter „Webdienste automatisch bereitstellen “.

Anwendungsberechtigungsnachweise

Die folgenden Anmeldedaten werden zur Authentifizierung einer Anwendung auf der Plattform „ IBM “ ( MaaS360 ) verwendet.

Feldwerte
  • App ID 30102000_testAPI
  • App Version 1
  • Platform ID 3
  • App Access Key jCTjQ762Tp
  • Billing ID 30102000
  • Username Admin_API
  • Password adminSafe01

Beispiel für einen API-Aufruf: Authentication (authToken)

Endpunkt
POST /auth/1.0/authenticate/{billingId}

API-Version: auth1.0

Anfragetext (XML)
xml
<?xml version="1.0" encoding="UTF-8"?>
<authRequest>
 <maaS360AdminAuth>
  <platformID>3</platformID>
  <billingID>30102000</billingID>
  <password>adminSafe01</password>
  <userName>Admin_API</userName>
  <appID>30102000_testAPI</appID>
  <appVersion>1</appVersion>
  <appAccessKey>jCTjQ762Tp</appAccessKey>
 </maaS360AdminAuth>
</authRequest>
Antwort
Eine erfolgreiche Authentifizierungsantwort enthält ein <authToken> Element. Extrahieren Sie diesen Wert und speichern Sie ihn, da er für alle nachfolgenden API-Aufrufe benötigt wird.
xml
<authToken>9bab5021-d275-4970-952b-0630775f5c3e-IGJAaGQ</authToken>
Lebensdauer des Tokens
Das Authentifizierungstoken läuft nach 60 minutes. ab. Planen Sie Ihre Anwendungslogik so, dass die Authentifizierung bei Bedarf erfolgt.

Authentifizierte API-Aufrufe durchführen

Nach der Authentifizierung müssen alle nachfolgenden Anfragen das Autorisierungstoken im Anfrage-Header enthalten. MaaS token="<your-auth-token>"Das Token muss genau so formatiert sein, wie im folgenden Beispiel gezeigt, einschließlich des MaaS token= prefix und der umgebenden Anführungszeichen.

erforderliche Header

Kopfzeilenwert / Format

Authorization MaaS token="<your-auth-token>"

BillingId 30102000

Beispiel für Autorisierungsheader
Authorization: MaaS token="1cdfaedb-3b37-7abf-b5da-9f755ba73e73-IGPjdBd"
Hinweis: Das Weglassen des MaaS token= prefix oder der umgebenden Anführungszeichen führt zu einem Autorisierungsfehler.

Beispiel für einen API-Aufruf: Ein Gerät ausblenden

Dieses Beispiel zeigt, wie man ein Gerät mithilfe des Hide Device Endpunkts als Inactive markiert.

Endpunkt
POST /devices/1.0/hideDevice/{billingId}

Durch diese Aktion wird das angegebene Gerät unter IBM MaaS360 als inaktiv markiert.

Parameter

Parameterwert
  • Authorization MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd"
  • BillingId 30102000
  • deviceId Appl73841673

cURL-Befehl

Nachdem Sie die Parameterwerte im Portal eingegeben haben, füllt die Schnittstelle den folgenden Befehl „ cURL “ automatisch aus und ist bereit zur Ausführung.

Anforderung
curl -X 'POST' \
 'https://services.m3.maas360.com/device-apis/devices/1.0/hideDevice/30102000' \
 -H 'accept: application/xml' \
 -H 'Authorization: MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd"' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'xFblAco: Api_Docs' \
 -d 'deviceId=Appl73841673'
Erwartete Antwort
Ein erfolgreicher Aufruf gibt eine XML-Antwort zurück, die die Aktion bestätigt.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<actionResponse>
 <actionStatus>0</actionStatus>
 <description>Hide action executed successfully</description>
 <maas360DeviceID>Appl73841673</maas360DeviceID>
</actionResponse>

Ein <actionStatus> von 0 bedeutet Erfolg. Das <description> Feld liefert eine gut lesbare Bestätigung und <maas360DeviceID> gibt das Gerät zurück, auf das die Aktion angewendet wurde.

Kernaspekte

  • Zuerst authentifizieren
    Jede Sitzung muss mit einem erfolgreichen Authentifizierungsaufruf beginnen, um ein Token zu erhalten.
  • Die Gültigkeitsdauer des Tokens beträgt 60 Minuten
    Integrieren Sie eine Logik zur Aktualisierung von Tokens in jede lang andauernde Integration.
  • Den „Authorization“-Header korrekt formatieren
    Verwenden Sie stets das MaaS token="your token" Format, wobei die genaue Syntax entscheidend ist.
  • Nutzen Sie die im Portal integrierte Dokumentation
    Die interaktive Benutzeroberfläche hilft Ihnen dabei, Befehle zu testen und zu erstellen cURL , ohne Code schreiben zu müssen.
  • Stellen Sie Ihre App bereit, bevor Sie die API aufrufen
    Ohne entsprechende Konfiguration unter IBM MaaS360 schlagen Authentifizierungsanfragen fehl.

Weitere Endpunkte und fortgeschrittene Anwendungsfälle finden Sie in der vollständigen API-Dokumentation im IBM MaaS360 Portal unter Setup > Web Services API > Dokumentation.