IBM MaaS360 API リファレンス
IBM® MaaS360® 堅牢なRESTful Webサービス群を提供しており、管理者や開発者がプログラムを介してプラットフォームと連携し、デバイス、アプリケーション、ユーザーなどを管理できるようにします。 以下の内容では、実用的な例を用いて、APIドキュメントへのアクセス方法、アプリケーションの認証方法、および実際のAPI呼び出しの実行方法について解説します。
WebサービスのAPIリファレンスには、実装上の注意事項、APIを実行するために必須の属性、アクセス制御の詳細、モデル例を含むレスポンスクラス、およびパラメータの詳細などの情報が含まれています。
IBM MaaS360 ポータルでAPIドキュメントにアクセスする
管理者は、 IBM MaaS360 ポータル内で、Web サービスのドキュメントを閲覧・操作し、アクセスキーを直接管理するためのロール Web Services を持っている必要があります。
APIの利用については、標準のポータルへのアクセスと同様に、ロールベースのアクセス制御が適用されます。 API サービス アカウントに、必要なタスクを実行するために適切なロールが割り当てられていることを確認してください。 詳細については、 「 IBM MaaS360 ポータルの管理者のアクセス権とロール」 を参照してください。
ドキュメントの閲覧方法
- IBM MaaS360 ポータルのホームページから、 をクリックします。重要： ドキュメント内でテストを行う際は、ご自身のアカウント、またはログイン時に使用したのと同じアカウントを使用する必要があります。
- カテゴリ別に分類されたエンドポイント（認証、デバイス管理、アプリ管理）をご覧ください。
- 試してみたいAPI呼び出しのリクエスト本文に記載されているパラメータの値を入力してください。
組み込みのドキュメントインターフェースを使用すると、API呼び出しを対話形式でテストできるため、ワークフローに組み込む前にリクエストの検証やレスポンスの確認を簡単に行うことができます。
認証：最初に行うべき必須のリクエスト
60
minutes であり、その期間が経過すると、新しいトークンをリクエストする必要があります。 以降のすべてのWebサービス呼び出しには、このトークンを含める必要があります。認証トークンの要求を許可されるためには、アプリケーションはまず、そのWebサービスを利用する権限を持つ provisioned within IBM MaaS360 必要があります。 詳細については、 「Web サービスの自動プロビジョニング」 を参照してください。
アプリケーション資格情報
以下の認証情報は、 IBM MaaS360 プラットフォームに対するアプリケーションの認証に使用されます。
- フィールド値
- App ID:
30102000_testAPI - アプリのバージョン：
1 - プラットフォームID：
3 - アプリのアクセスキー：
jCTjQ762Tp - 請求ID：
30102000 - ユーザー名：
Admin_API - パスワード：
adminSafe01
- App ID:
API呼び出し例：Authentication (authToken)
- エンドポイント
POST /auth/1.0/authenticate/{billingId}
APIバージョン： auth1.0
- リクエスト本文（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>
- 応答
- 正常な認証応答には、要素
<authToken>が含まれます。 この値を抽出して保存してください。以降のすべてのAPI呼び出しで必要となります。xml <authToken>9bab5021-d275-4970-952b-0630775f5c3e-IGJAaGQ</authToken>
- トークンの有効期間
60 minutes認証トークンは、. 後に有効期限が切れます。 必要に応じて認証を行うよう、アプリケーションのロジックを設計してください。
認証済みAPI呼び出しの実行
認証が完了すると、それ以降のすべてのリクエストでは、リクエストヘッダーに認証トークンを含める必要があります。 MaaS
token="<your-auth-token>"トークンは、以下の例に示されているとおりに、 および前後の引用符 MaaS token= prefix も含めて、正確に記述する必要があります。
必要なヘッダー
- ヘッダー値／形式
承認：
MaaS token="<your-auth-token>"BillingId:
30102000
- 許可ヘッダーの例
- 承認：
MaaS token="1cdfaedb-3b37-7abf-b5da-9f755ba73e73-IGPjdBd"注： またはその前後の引用符をMaaS token= prefix省略すると、認証に失敗します。
API呼び出しの例：デバイスを非表示にする
この例では、エンドポイントを使用してデバイスを Hide Device として Inactive マークする方法を示しています。
- エンドポイント
POST /devices/1.0/hideDevice/{billingId}
この操作により、 IBM （ MaaS360 ）内で、指定されたデバイスが非アクティブとしてマークされます。
パラメーター
- パラメーター値
- 承認：
MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd" - BillingId:
30102000 - deviceId:
Appl73841673
- 承認：
cURL コマンド
ポータルにパラメータ値を入力すると、インターフェースが自動的に以下の cURL コマンドを入力し、実行可能な状態になります。
- 要求
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'
- 予期される応答
- 呼び出しが成功すると、そのアクションを確認するXMLレスポンスが返されます。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <actionResponse> <actionStatus>0</actionStatus> <description>Hide action executed successfully</description> <maas360DeviceID>Appl73841673</maas360DeviceID> </actionResponse>
主なポイント
- まず認証を行ってください
- すべてのセッションは、トークンを取得するために、認証呼び出しが正常に完了してから開始されなければなりません。
- トークンの有効期間は60分です
- 長時間実行される統合処理には、トークンの更新ロジックを組み込んでください。
- Authorizationヘッダーを正しく設定する
- 必ず 形式
MaaS token="your token"を使用してください。また、構文を正確に守ることが重要です。
- ポータルに組み込まれているドキュメントを利用してください
- この対話型インターフェースを使えば、コードを一切記述することなく、コマンドのテストや生成
cURLを行うことができます。
- APIを呼び出す前に、アプリの設定を行ってください
- IBM （ MaaS360 ）で適切なプロビジョニングが行われていないと、認証リクエストは失敗します。
エンドポイントや高度なユースケースの詳細については、 IBM MaaS360 ポータルの にある完全なAPIドキュメントを参照してください。