Riferimento API IBM MaaS360 per i servizi Web

IBM® MaaS360® fornisce una serie completa di servizi web RESTful che consentono ad amministratori e sviluppatori di interagire a livello di programmazione con la piattaforma per la gestione di dispositivi, applicazioni, utenti e altro ancora. Il contenuto che segue spiega, attraverso esempi pratici, come accedere alla documentazione dell'API, autenticare la propria applicazione ed eseguire chiamate API reali.

La documentazione di riferimento dell'API per i servizi web include informazioni quali note di implementazione, attributi obbligatori per l'esecuzione dell'API, dettagli sul controllo degli accessi, classi di risposta con esempi di modelli e dettagli sui parametri.

Accesso alla documentazione API nel portale IBM MaaS360

Gli amministratori devono avere il Web Services Ruolo che consente di visualizzare e interagire con la documentazione dei servizi Web e di gestire le chiavi di accesso direttamente all'interno del portale IBM MaaS360.

L'utilizzo dell'API segue gli stessi controlli di accesso basati sui ruoli previsti per l'accesso al portale standard. Assicurati che all'account di servizio API siano stati assegnati i ruoli appropriati per eseguire le attività richieste. Per ulteriori informazioni, consultare la sezione "Ruoli e diritti di accesso per gli amministratori del portale IBM MaaS360 ".

Come accedere alla documentazione

Segui i passaggi per accedere alla documentazione dell'API dei servizi Web nel portale IBM MaaS360.
  1. Dalla pagina iniziale del portale IBM MaaS360, fare clic su Configurazione > API dei servizi Web > Documentazione.
    Importante: quando si eseguono i test nella documentazione, è necessario utilizzare il proprio account o lo stesso account utilizzato per effettuare l'accesso.
  2. Esplora gli endpoint suddivisi per categoria (Autenticazione, Gestione dei dispositivi, Gestione delle app).
  3. Inserisci i valori dei parametri indicati nel corpo della richiesta per la chiamata API che desideri provare.

    L'interfaccia di documentazione integrata ti aiuta a testare le chiamate API in modo interattivo, semplificando la verifica delle richieste e l'analisi delle risposte prima di integrarle nei tuoi flussi di lavoro.

Autenticazione: richiesta iniziale e obbligatoria

Importante: prima di utilizzare qualsiasi servizio web di IBM MaaS360, la tua applicazione deve effettuare l'autenticazione e ottenere un token di autenticazione valido. Una volta generato, il token è valido per 60 minutes dopo di che è necessario richiederne uno nuovo. Tutte le successive chiamate al servizio web devono includere questo token.

Per poter richiedere un token di autenticazione, l'applicazione deve prima essere provisioned within IBM MaaS360 autorizzata a utilizzare i relativi servizi web. Per ulteriori informazioni, consultare la sezione "Servizi web con configurazione automatica".

Credenziali applicazione

Le seguenti credenziali vengono utilizzate per autenticare un'applicazione sulla piattaforma IBM MaaS360.

Valori del campo
  • App ID: 30102000_testAPI
  • Versione dell'app: 1
  • ID piattaforma: 3
  • Chiave di accesso all'app: jCTjQ762Tp
  • ID fattura: 30102000
  • Nome utente: Admin_API
  • Password: adminSafe01

Esempio di chiamata API: Authentication (authToken)

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

Versione API: auth1.0

Corpo della richiesta (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>
Risposta
Una risposta di autenticazione riuscita contiene un <authToken> elemento. Estrai e salva questo valore, poiché è necessario per tutte le successive chiamate all'API.
xml
<authToken>9bab5021-d275-4970-952b-0630775f5c3e-IGJAaGQ</authToken>
Durata del token
Il token di autenticazione scade dopo 60 minutes. Progetta la logica dell'applicazione in modo da effettuare l'autenticazione quando necessario.

Effettuare chiamate API autenticate

Una volta effettuata l'autenticazione, tutte le richieste successive devono includere il token di autorizzazione nell'intestazione della richiesta. MaaS token="<your-auth-token>"Il token deve essere formattato esattamente come mostrato nell'esempio seguente, comprese le MaaS token= prefix virgolette e quelle che lo racchiudono.

Intestazioni obbligatorie

Valore/Formato dell'intestazione

Autorizzazione: MaaS token="<your-auth-token>"

BillingId: 30102000

Esempio di intestazione di autorizzazione
Autorizzazione: MaaS token="1cdfaedb-3b37-7abf-b5da-9f755ba73e73-IGPjdBd"
Nota: l'omissione di MaaS token= prefix o delle virgolette che lo racchiudono comporta un errore di autorizzazione.

Esempio di chiamata API: nascondere un dispositivo

Questo esempio illustra come contrassegnare un dispositivo come Inactive utilizzando l'endpoint Hide Device .

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

Questa operazione contrassegna il dispositivo specificato come inattivo all'indirizzo IBM MaaS360.

Parametri

Valore parametro
  • Autorizzazione: MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd"
  • BillingId: 30102000
  • deviceId: Appl73841673

cURL Comando

Dopo aver inserito i valori dei parametri nel portale, l'interfaccia compila automaticamente il seguente comando cURL ed è pronta per l'esecuzione.

Richiesta
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'
Risposta prevista
Se la richiesta va a buon fine, viene restituita una risposta XML che conferma l'azione.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<actionResponse>
 <actionStatus>0</actionStatus>
 <description>Hide action executed successfully</description>
 <maas360DeviceID>Appl73841673</maas360DeviceID>
</actionResponse>

Un <actionStatus> di 0 indica che l'operazione è andata a buon fine. Il <description> campo fornisce una conferma leggibile e <maas360DeviceID> riporta il nome del dispositivo su cui è stata eseguita l'operazione.

Punti chiave

  • Effettua prima l'autenticazione
    Ogni sessione deve iniziare con una richiesta di autenticazione riuscita per ottenere un token.
  • La validità del token è di 60 minuti
    Incorporare la logica di aggiornamento dei token in qualsiasi integrazione di lunga durata.
  • Imposta correttamente l'intestazione "Authorization"
    Utilizza sempre il MaaS token="your token" formato indicato; la sintassi esatta è fondamentale.
  • Utilizza la documentazione integrata nel portale
    L'interfaccia interattiva ti permette di testare e generare cURL comandi senza scrivere alcun codice.
  • Configurare l'app prima di richiamare l'API
    Senza una configurazione adeguata in IBM MaaS360, le richieste di autenticazione falliscono.

Per ulteriori endpoint e casi d'uso avanzati, consultare la documentazione API completa nel portale IBM MaaS360 in Configurazione > API dei servizi Web > Documentazione.