動作確認環境
- Spotfire Server 14.0 LTS
本資料記載の内容はSpotfire Server 7.13以降に適用できます。
※Spotfire 7.13にはAPI利用時の認証方法にOAuth2認証が追加されており、10.3よりOAuth2以外の認証方法(例えばユーザー名・パスワードによる認証)が完全に廃止されました(参考資料)。
API一覧
各バージョンのSpotfireで利用できるREST APIは下表の通りです。
REST APIカテゴリ | 機能 | 対応バージョン |
---|---|---|
Automation Services REST API |
|
7.13~ |
Library REST API v1 |
|
10.2~ |
|
14.0~ |
|
License Management REST API |
|
14.2~ ※14.3にてAPIのエンドポイントURLに変更あり |
Information Model REST API |
|
14.2~ ※14.3にてAPIのエンドポイントURLに変更あり |
Web Player REST API v1 |
|
14.4~ |
APIドキュメント
REST API のドキュメントは以下のURLから確認できます(アクセスにはログインが必要)。
http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html
上記のページにて以下を行えます。
- 画面右上にあるドロップダウンリストから利用可能なAPIカテゴリを選べます。
- 「Authorize」ボタンを押して認証を行った後に、それぞれのAPIを呼ぶ出すことも可能です。
- 一部APIは利用不可、例えばファイルのデータをアップロードすることはできません。
「Authorize」ボタン押下後に認証画面が表示されます。Client IDやClient Secret、スコープを指定して認証を行います。
認証が成功した後に認証画面を閉じて、各APIの下にある「Try it out」ボタンを押して、画面指示に従って必要なパラメータを入力してAPIを呼び出すことができます。
認証
REST APIを利用するには認証や認可が必要ですが、認証(authentication)と認可(authorization)に OAuth 2.0プロトコルを使用し、Spotfire Server自体を認可サーバー(Authorization Server)として使用します。
・APIはHTTPセッションを使用しないため、セッションクッキーを維持する必要はありません。
・OAuth 2.0を使用する場合、すべての通信は常にHTTPS経由で行われる必要があります。
Spotfire ServerをOAuth 2.0 Authorization Serverとして使用する場合のメタデータは以下のURLから取得できます(v10.9以降、ログインが不要で取得可能)。
http[s]://<host>[:<port>]/spotfire/.well-known/oauth-authorization-server
OAuth2認証を行うにはまずはAPIクライアントユーザー(Client ID、Client Secret)を新規作成する必要があります。APIクライアントユーザーに許可される操作(利用可能なAPI)はアカウント作成時に指定されたスコープ(scope)によって制限されています。また、クライアントアプリケーションの種類に合わせて、アカウント作成時にAPIクライアントユーザーのクライアントプロファイル(client profile)を正しく指定する必要があります。
利用可能なスコープ(scope)は下表のとおりです。
APIクライアントユーザーを新規作成する際に、クライアントがアクセスする予定のすべてのサービスに必要なスコープを指定する必要があります。
REST APIカテゴリ | スコープ | 説明 | 対応バージョン |
---|---|---|---|
Automation Services REST API | api.rest.automation-services-job.execute | ジョブを実行 | 7.13~ |
Library REST API v1 | api.rest.library.upload | ファイルをアップロード | 10.2~ |
Library REST API v2 | api.library.read | 読み取り | 14.0~ |
api.library.write | 書き込み | ||
License Management REST API | api.licenses.read | 読み取り | 14.2~ |
api.licenses.write | 書き込み | ||
Information Model REST API | api.information-model.read | 読み取り | 14.2~ |
api.information-model.write | 書き込み | ||
Web Player REST API v1 | api.web-player.load | 分析をロード | 14.4~ |
利用可能なクライアントプロファイル(client profile)は下表のとおりです。
APIクライアントユーザーを新規作成する際に、クライアントアプリケーションの種類に合わせてクライアントプロファイルを正しく指定する必要があります。
クライアントプロファイル (client profile) |
説明 |
---|---|
other | クライアント自体に代わってリクエストを実行する通常のヘッドレスアプリケーションの場合に使用する |
web | エンドユーザーに代わってリクエストを実行するサーバー側Webアプリケーションの場合に使用する |
native | エンドユーザーに代わってリクエストを実行する、iOS アプリや Android アプリなどのネイティブクライアントの場合に使用する |
user_agent |
エンドユーザーに代わってリクエストを実行する、クライアント側Web アプリケーション(JavaScript)の場合に使用する ※v12.0以降で利用可能。 |
OAuth2認証を行う際にはAPIクライアントユーザーのClient IDやClient Secret、スコープのほかに、許可種別(grant type)を指定する必要もありますが、クライアントプロファイルによって利用できる許可種別が制限されています。
許可種別(grant type) | 説明 |
---|---|
authorization_code |
Authorization Codeによる認証(参考資料) ・クライアントプロファイルweb / native / user_agentの場合のみ利用可能 |
client_credentials |
Client Credentialsによる認証(参考資料) ・クライアントプロファイルotherの場合のみ利用可能 |
refresh_token |
Refresh Tokenによる認証(参考資料) ・クライアントプロファイルweb / native / user_agentの場合のみ利用可能 |
Python(Requestsを使用)やPostmanなどのREST APIクライアントツールを利用してAPIを呼び出す場合、クライアントプロファイル「other」や許可種別「client_credentials」を使用します。
利用手順
REST APIを利用する際には以下の手順に従って行います。
- APIクライアントユーザーを新規作成します。
- アクセス権限を付与します。
- アクセストークンを取得します。
- APIを呼び出します。
本資料ではPython(Requestsを使用)を利用して、Client Credentialsによる認証を行ってAPIを呼び出す場合を例に説明します。
APIクライアントユーザーの新規作成
以下の手順でAPIクライアントユーザーを新規作成します。
1.Spotfire Server端末内で、OS管理者権限でコマンドプロンプトを起動し、Spotfire Serverのインストール先フォルダへ遷移します。
C:\spotfire\spotfireserver\14.0.0\tomcat\spotfire-bin
2.コマンド(register-api-client)を実行してAPIクライアントユーザーを新規作成します。作成後には該当ユーザーがすぐに利用できます。
config.bat register-api-client --name=apiuser -Sapi.library.write -Sapi.library.read --client-profile=other -Gclient_credentials
コマンドを実行するにはConfiguration Toolのパスワードの入力が必要です。
引数:
・--name=xxx(必須):APIクライアントユーザーのアカウント名(任意文字列)
・-Sxxx(必須、複数指定可):スコープ(scope)、※小文字・大文字を区別する
・--client-profile=xxx(オプション):クライアントプロファイル(client profile)、web、user_agent、native、other(未指定時のデフォルト)のいずれかを指定
・-Gxxx(オプション、複数指定可):許可種別(grant type)、authorization_code、client_credentials(未指定時のデフォルト)、refresh_tokenのいずれかを指定
例:
APIクライアントユーザーのClient IDやClient Secretはメモして保管してください。
3.作成されたAPIクライアントユーザーの一覧を取得するには以下のコマンド(list-oauth2-clients)を実行します。
config.bat list-oauth2-clients
例:
4.Client IDやClient Secretを再確認するには以下のコマンド(show-oauth2-client)を実行します。
config.bat show-oauth2-client -s true -i <Client ID>
引数「-s true」はClient Secretを表示させることを指定します(デフォルトはfalse)。
例:
5.既存APIクライアントユーザーを削除するには以下のコマンド(delete-oauth2-client)を実行します。
config.bat delete-oauth2-client -i <Client ID>
例:
アクセス権限を付与
上記の手順で作成されたAPIクライアントユーザーは、通常のSpotfireユーザーと同じようにグループ管理、またはライブラリへのアクセス権限を管理できます。
各種REST API利用時に必要なアクセス権限は下表のとおりです。
REST APIカテゴリ | スコープ | 必要なアクセス権限 |
---|---|---|
Automation Services REST API | api.rest.automation-services-job.execute |
・ASジョブファイルの格納先ライブラリフォルダへの読み取り権限 |
Library REST API v1 | api.rest.library.upload | ・出力先のライブラリフォルダへの書き込み権限 |
Library REST API v2 | api.library.read | ・アクセス先のライブラリフォルダへの読み取り権限 |
api.library.write | ・出力先のライブラリフォルダへの書き込み権限 | |
License Management REST API | api.licenses.read | なし |
api.licenses.write | ・「Administrator」グループに所属 | |
Information Model REST API | api.information-model.read | ・アクセス先のライブラリフォルダへの読み取り権限 |
api.information-model.write |
・出力先のライブラリフォルダへの書き込み権限 ・「Spotfireインフォメーションモデラー:管理」ライセンス |
|
Web Player REST API v1 | api.web-player.load |
・Administratorグループに所属、もしくは「Spotfire Consumer」⇒「Spotfire Webクライアントでの分析ファイルの外部更新」ライセンスが付与されていること ・アクセス先のライブラリ内の分析への読み取り権限 |
アクセストークンの取得
Client Credentialsによる認証の場合にアクセストークンを取得するには、以下のエンドポイントに対してHTTPリクエストをPOSTメソッドで送信して、APIクライアントユーザーのClient IDやClient Secret、スコープ、許可種別などをSpotfire Serverに渡します。認証が成功した場合はアクセストークンがHTTPレスポンスとして返されます。
http[s]://<host>[:<port>]/spotfire/oauth2/token
・アクセストークンに有効期限が設けられています。デフォルト設定では7200秒(2時間)です。
・有効期限が過ぎた場合は改めてアクセストークンを取得する必要があります。
・アクセストークン取得時に指定されたスコープが対応しているAPIのみを利用できます。
アクセストークンを取得するPythonコードの例は以下です。複数スコープが必要な場合はスペースで区切って指定します。
import requests
import json
import urllib.parse
def get_access_token(server_url, client_id, client_secret, scope):
url = urllib.parse.urljoin(server_url, "/spotfire/oauth2/token")
data = {"grant_type": "client_credentials", "scope": scope}
resp = requests.post(url, data=data, auth=(client_id, client_secret))
assert resp.status_code == 200, "{} {}".format(resp.status_code, resp.text)
res = resp.json()
return res, res["access_token"]
server_url = "http://winx:1400"
client_id = "7e3ef079fc90a66c8a082af61715c18e.oauth-clients.spotfire.tibco.com"
client_secret = "03174659369c00e98647c2a66d518a787d30bbbef8643de114c6d9d8c612978b"
scope = "api.library.read api.library.write"
res, token = get_access_token(server_url, client_id, client_secret, scope)
print(json.dumps(res, indent=2))
print(token)
HTTPレスポンスのステータスコードが「200」となっている場合は処理が成功したことになりますが、レスポンス(JSON文字列)からアクセストークンの情報を取得できます。
取得したアクセストークンの情報の例は以下です。有効期限(7200秒、2時間)が示されています。
{
"access_token": "eyJraWQiOiJveGpKVDhnNmpoeFZ6THhvVjlwVDc5N...省略",
"scope": "api.library.read api.library.write",
"token_type": "Bearer",
"expires_in": "7200"
}
APIの呼び出し
上記で取得したアクセストークンを認証情報としてHTTPリクエストのヘッダーに設定し、必要なパラメータやデータなどを設定してAPIを呼び出します。
ライブラリの一般情報を取得するAPIを呼び出す例は以下です。
def get_library_info(server_url, token):
url = urllib.parse.urljoin(server_url, "/spotfire/api/rest/library/v2/info")
headers = {"Authorization": "Bearer " + token, "Content-type": "application/json"}
resp = requests.get(url, headers=headers)
assert resp.status_code == 200, "{} {}".format(resp.status_code, resp.text)
return resp.json()
info = get_library_info(server_url, token)
print(json.dumps(info, indent=2))
HTTPレスポンスにはライブラリの一般情報が含まれています。
・ルートフォルダのID
・ライブラリ項目の種類の一覧
・ライブラリへアップロードできるファイルの種類の一覧、同時実行数上限、ファイルサイズ上限など
・ライブラリからダウンロードできるファイルの種類の一覧
例:
{
"rootItem": "6b67ec30-712e-11dd-7434-00100a64217d",
"itemTypes": [
"spotfire.mod",
"spotfire.dxp",
"spotfire.datasource",
...省略
],
"uploadInfo": {
"allowedItemTypes": [
"spotfire.sbdf",
"spotfire.dxp",
"spotfire.mod"
],
"maxConcurrentJobsPerClient": 10,
"maxUploadSizeBytes": 2147483648
},
"downloadInfo": {
"allowedItemTypes": [
"spotfire.mod",
"spotfire.dxp",
"spotfire.datafunction",
...省略
]
}
}
HTTPステータスコード
アクセストークンを取得、またはAPIを呼び出す際に返されたHTTPレスポンスのステータスコードから処理が正常に実施されたかを判断できます。API利用時には必ず確認してください。
HTTPステータスコード | エラーコード | 原因 |
---|---|---|
200 | OK | 正常(処理が成功した) |
201 | Created | 正常(対象項目の作成が成功した) |
204 | Successful | 正常(分析をロードした) |
400 | invalid_request | リクエストの情報に不正がある |
400 | precondition_failed | 依存処理がまだ実施されていない |
400 | bad_digest | データのハッシュ値が正しくない |
401 | not_authenticated | 認証(ログイン)できていない |
403 | not_authorized | アクセス権限(読み取り、書き込みなど)が不足している |
404 | not_found | アクセス先が見つからない |
404 | job_unknown | 指定されたジョブが見つからない |
405 | method_not_allowed | HTTPメソッドが正しくない |
409 | already_exists | リソースがすでに存在する |
413 | limit_exceeded | データのサイズが上限を超えた |
415 | unsupported_mediatype | ファイルの種類がサポートされていない |
429 | rate_limit_exceeded | リクエストが多すぎる(対象APIの同時実行数の上限を超えた) |
500 | internal_error | Spotfire Server側処理に思わぬエラーが発生した |
503 | server_busy | Spotfire Serverが現在ビジー状態であるためリクエストを処理できない |