FUJITSU Cloud Service K5 API リファレンスマニュアル Version 1.7 FUJITSU LIMITED

Size: px

Start display at page:

Download "FUJITSU Cloud Service K5 API リファレンスマニュアル Version 1.7 FUJITSU LIMITED"

てるえやぶき
5 years ago
Views:

1 FUJITSU Cloud Service K5 API リファレンスマニュアル Version.7 FUJITSU LIMITED

2 まえがき本書の目的本書は富士通が提供する FUJITSU Cloud Service K5( 以降 K5) の操作および管理を行う際に使用する API について説明しています本書は作成時点で提供される機能範囲で記述しておりますなお本書の内容は今後の仕様変更等により変更されうることをご承知おき願います以下の関連マニュアルもあわせて参照することを推奨します K5 API ユーザーズガイド K5 ポータルユーザーズガイド輸出管理規制本ドキュメントを輸出または第三者へ提供する場合はお客さまが居住する国および米国輸出管理関連法規等をご確認のうえ必要な手続きをおとりくださいお願い本書は予告なしに変更されることがあります本書を無断で他に転用しないようお願いします本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については当社はその責を負いません i

3 変更履歴版数日付変更箇所概要. 206 年 8 月 8 日 3.3. ユーザーの追加を行うリクエストパラメータ追加ユーザーの変更を行う年 9 月 6 日ドキュメント全体誤記修正年 0 月 7 日 2.2 エラー情報エラーメッセージ修正 3.2 エラー情報年 2 月 22 日.2 ロール別操作権限につ節追加いて. API 一覧機能追加対応 2.3. アクセストークン取得を行うユーザー認証方式の情報を更新する年 5 月 5 日 2.3. アクセストークン取得説明追加を行う年 9 月日 2.3. アクセストークン取得説明追加を行う年月 9 日 2.3. アクセストークン取得を行う説明修正 ii

4 目次第章 API 情報... API 一覧... 2 ロール別操作権限について... 3 用語集第 2 章認証 API... 5 リクエストヘッダ情報... 6 エラー情報... 6 API 詳細アクセストークン取得を行う第 3 章利用者管理 API... 0 リクエストヘッダ情報... エラー情報... API 詳細ユーザーの追加を行うユーザーの変更を行うユーザーのパスワード変更を行うユーザーの削除を行うユーザー認証方式の情報を更新する... 9 iii

5 第章 API 情報

6 API 一覧項 API API 名メソッド URL 説明番グループアクセストークン API 認証用のトークンの取認証 POST 取得 API/paas/auth/token 得を行う 2 ユーザー追加 POST 利用者の新規登録を行う /api/users 契約者および利用者の情 3 ユーザー変更 PUT /api/users 報の更新を行うユーザーパスワ契約者および利用者のパス 4 利用者管理 PUT ード変更 /api/userspassword ワード変更を行う 5 ユーザー削除 DELETE 利用者の削除を行う /api/users/?login_id= ユーザー名ユーザー認証方契約者および利用者の認 6 PUT 式情報更新 /api/usersauthenticationmethod 証方式を変更する各 API の文字コードは UTF-8 です 2

7 ロール別操作権限について K5 ポータルの各ユーザーにはロールと呼ばれる権限情報が設定され K5 ポータルでの操作が制御されます ( 詳しくは K5 ポータルユーザーズガイドをご参照ください ) API の利用においてもロールごとに下表に示すとおり権限が設定されています APIグループ認証利用者管理 API 名アクセストークン取得 K5 共通サービスのロール利用者契約者管理者開発者操作対象操作対象操作対象自分自身利用者自分自身契約者利用者自分自身契約者利用者ユーザー追加ユーザー変更ユーザーパスワード変更ユーザー削除ユーザー認証方式情報更新 : 可能 : 不可 : 制限付きで可能 ( 下記 [ ユーザー変更 ] の説明を参照 ) API 名ごとに実行が許可されているロールを以下に説明します [ ユーザー追加 ] 契約者管理者は契約者以外のロールを持つユーザーを追加可能 [ ユーザー変更 ] 管理者開発者は自分自身の情報( パスワード含む ) を変更することが可能管理者が契約者に対して変更できる情報はパスワードのみ契約者は自分自身の情報( ユーザー状態以外 ) を変更することが可能契約者管理者による利用者( 管理者 / 開発者 ) の情報更新は可能 [ ユーザーパスワード変更 ] ユーザーはロールに関係なく自分自身のパスワードのみ変更可能 [ ユーザー削除 ] 契約者管理者は契約者以外のロールを持つユーザーを削除可能 [ ユーザー認証方式情報更新 ] 自分自身の認証方式のみ更新可能 3

8 用語集用語説明ユーザー機能を利用する人管理する人 ( またはシステムサービス ) ユーザー名ロールユーザーを一意的に識別するための名称人やグループに権限を割り当てるための情報ロールを用いてユーザーが使用できる API を区別するロールコードロールを一意的に識別するための ID トークン認証した証として発行される期限付きの認証情報 4

9 2 第 2 章認証 API 5

10 リクエストヘッダ情報認証 API 用ヘッダー項番ヘッダー名必須ヘッダー値 Content-Type application/json 2 X-FCX-Client-Cert 注参照ユーザー情報に紐づくクライアント証明書証明書 + パスワード認証の場合のみ必須エラー情報 API 実行エラーの際エラー情報はレスポンスのボディーに返却されます項番種別項目名型多重度 3 systemerrorcode string.. システムエラーコード JSON 4 business object.. 業務オブジェクト [Body] 5 businesserrorinfo string.. エラーメッセージ説明 errorlevel string.. エラーレベル 2 framework object.. フレームワークオブジェクト 6 responseerrorcode string.. 応答エラーコード 7 embeddedstring string array.. 埋め込み情報サンプル : "errorlevel": "888", "framework": "systemerrorcode": "", "business": "businesserrorinfo": "Cannot create token from the specified user information.", "responseerrorcode": "RCM30802", "embeddedstring": [ ] 6

11 項番返却されるエラー情報 HTTP ステータスエラー内容エラーメッセージエラーの原因 400 入力パラメータ異常 Parameter is invalid. Specified parameter: XXX XXX はパラメータ名 2 40 アクセストークン生成不可 Cannot create token from the specified user information アクセストークン払出失敗 Failed to create token (Internal Error). 入力パラメータチェックエラー ( パラメータなし桁数不備形式不備など ) リクエストで指定した情報に不備がある場合サーバー内部エラー 7

12 API 詳細. リクエストパラメータ定義項番 2.3. アクセストークン取得を行う種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小桁数最大桁数設定値の auth 認証オブジェクト認証オブジェクト 2 identity アイデンティティオブジェクトアイデンティティオブジェク 3 password パスワードオブジェクトパスワードオブジェクト 4 user ユーザーオブジェクトユーザーオブジェクト 5 contract_number 契約番号半角文字列認証ユーザーの契約番号 6 name ユーザー名半角文字列認証ユーザーのユーザー JSON 名 7 [Body] password パスワード半角文字列認証ユーザーのパスワード 8 timezone タイムゾーン - - 半角文字列タイムゾーンを指定しまサンプル : "auth":, "identity": "password": "user": "timezone":"utc" "contract_number":"xxxxxxxx", "name":"user-name", "password":"user-password" 条件説明トす ( 大文字 / 小文字を区別しない ) 未指定または "UTC" 以外及び無効なタイムゾーンを指定した場合は "JST" が自動設定されます 8

13 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :20 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 token トークン.. トークンオブジェクト 2 JSON [Body] expires_at 有効期限.. アクセストークンの有効期限です初回払い出し時点での有効期限は 30 分後ですタイムゾーン : リクエスト項目の timezone に"UTC" を指定した場合は "UTC" それ以外の場合は"JST" フォーマット : YYYY-mm-ddTHH:MM:SS.SSSZ("UTC" の場合 ) YYYY-mm-ddTHH:MM:SS("JST" の場合 ) 3 scope スコープ.. スコープ 4 user ユーザー.. ユーザーオブジェクト 5 contract_number 契約番号.. 認証ユーザーの契約番号 6 name ユーザー名.. 認証ユーザーのユーザー名サンプル : "token": "expires_at":" t03:20:42", "scope":"paas", "user": "contract_number":"xxxxxxxx", "name":"user-name" 9

14 3 第 3 章利用者管理 API 0

15 リクエストヘッダ情報各 API の共通ヘッダー項番ヘッダー名必須ヘッダー値 Token アクセストークン取得 API で取得したトークン 2 Content-Type application/json エラー情報 API 実行エラーの際エラー情報はレスポンスのボディーに返却されます項番種別項目名型多重度 3 systemerrorcode string.. システムエラーコード JSON 4 business object.. 業務オブジェクト [Body] 5 businesserrorinfo string.. 業務エラー情報説明 errorlevel string.. エラーレベル 2 framework object.. フレームワークオブジェクト 6 responseerrorcode string.. 応答エラーコード 7 embeddedstring string array.. エラーメッセージサンプル : "errorlevel": "888", "framework": "systemerrorcode": "", "business": "businesserrorinfo": "BECSA0003", "responseerrorcode": "RCS0000", "embeddedstring": [ "Internal Server Error" ]

16 項番返却されるエラー情報 HTTP ステータス 400 入力パラメータエラーエラー内容エラーメッセージエラーの原因 XXX はエラーとなったパラメータ名 Parameter is insufficient. Required parameter: XXX Parameter is required. Character count of parameter is invalid. Specified parameter: XXX The format of parameter is invalid. Specified parameter: XXX 契約者削除不可 Could not delete user because the target user is a contractor パスワードチェックエラー Password is of invalid format or does not satisfy password policy. Please try again. Password can not be changed again within 24 hours since the last change. Please try again after 24 hours. Failed to change password. The old password was invalid ユーザー状態不正 Cannot change user information because user status of the target user is invalid 無効トークン The specified access token is not valid. 入力パラメータ不足入力パラメータチェックエラー ( 桁数不備 ) 入力パラメータ形式エラー ( 桁数以外のエラー ) 削除対象ユーザーが契約者の場合パスワードポリシー違反 24 時間以内にパスワード連続変更変更前のパスワードチェックエラー更新対象ユーザーのユーザー状態が無効のため更新不可指定されたアクセストークンが無効権限なし Authorization Error. 権限チェックエラー更新ユーザー不正 Unauthorized to change information of the specified user 対象なし The target information does not exist 排他エラー Operation conflicts with another one. 契約者のユーザー状態を変更しようとした場合操作しようとした情報がみつからない場合操作しようとした情報は別のプロセスによって処理された場合業務不整合 Internal Server Error. 整合性チェックエラーまたはその他のサーバー側のエラー 2

17 API 詳細. リクエストパラメータ定義項番ユーザーの追加を行う種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小桁数最大桁数設定値の条件説明 login_id ユーザー名半角文字列追加対象ユーザーのユーザー名 user_description ユーザー説明半角全角文追加対象ユーザーのユ字列ーザー説明 3 mailaddress メールアドレスメールアドレ追加対象ユーザーのメースの形式でルアドレスあること 4 user_status ユーザー状態.. 無効 (0)/ 有追加対象ユーザーのユ 5 効 () ーザー状態 JSON password パスワード半角文字列追加対象ユーザーのパ [Body] スワード 6 language_code 言語コード日本語 (ja) 追加対象ユーザーの言英語 (en) 語コード 7 role_code ロールコード管理者 (00) 追加対象ユーザーのロ開発者 (0) ールコード 8 user_last_name 氏名 ( 姓 ).. 64 半角全角文追加対象ユーザーの氏字列名 ( 姓 ) 9 user_first_name 氏名 ( 名 ).. 64 半角全角文追加対象ユーザーの氏字列名 ( 名 ) サンプル : "login_id": "fujitsu23", "user_description": " ユーザー説明です ", "mailaddress": "abc@xyz.com", "user_status": "", "password": "Abcdefgh ", "language_code": "ja", "role_code": "00", "user_last_name": " 富士通 ", "user_first_name": " 太郎 " 3

18 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :200 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 2 login_id ユーザー名.. 追加したユーザーのユーザー名 user_description ユーザー説明.. 追加したユーザーのユーザー説明 3 mailaddress メールアドレス.. 追加したユーザーのメールアドレス 4 user_status ユーザー状態.. 追加したユーザーのユーザー状態 JSON 無効 (0)/ 有効 () 5 [Body] language_code 言語コード.. 追加したユーザーの言語コード日本語 (ja) 英語(en) 6 authentication_method 認証方式.. 追加したユーザーの認証方式当 APIはパスワード認証 (0) 固定で返却します 7 user_last_name 氏名 ( 姓 ).. 追加したユーザーの氏名 ( 姓 ) 8 user_first_name 氏名 ( 名 ).. 追加したユーザーの氏名 ( 名 ) サンプル : "login_id": "fujitsu23", "user_description": " ユーザー説明です ", "mailaddress": "abc@xyz.com", "user_status": "", "language_code": "ja", "authentication_method ": "0", "user_last_name": " 富士通 ", "user_first_name": " 太郎 " 4

19 . リクエストパラメータ定義項番ユーザーの変更を行う種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小桁数最大桁数設定値の条件説明 login_id ユーザー名半角文字列変更対象ユーザーのユーザー名 mailaddress メールアドレスメールアドレスの変更対象ユーザーの新メー形式であることルアドレス 3 user_description ユーザー説明半角全角文字列変更対象ユーザーの新ユーザー説明 4 language_code 言語コード日本語 (ja) 英語変更対象ユーザーの新言 (en) 語コード 5 user_status ユーザー状態 0.. 無効 (0)/ 有効 () 変更対象ユーザーの新ユ JSON 変更対象ユーーザー状態 [Body] ザーが契約者の場合ユーザー状態の変更が不可 6 password パスワード半角文字列変更対象ユーザーの新パスワード 7 user_last_name 氏名 ( 姓 ) 半角全角文字列変更対象ユーザーの氏名 ( 姓 ) 8 user_first_name 氏名 ( 名 ) 半角全角文字列変更対象ユーザーの氏名 ( 名 ) : いずれかつ以上のパラメータを指定しない場合エラーとなりますサンプル : "login_id": "fujitsu23", "mailaddress": "abc@xyz.com", "user_description": " ユーザー説明です ", "language_code": "ja", "user_status": "", "password":"abcdefgh ", "user_last_name": " 富士通 ", "user_first_name": " 太郎 " 5

20 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :200 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 2 login_id ユーザー名.. 変更対象ユーザーのユーザー名 language_code 言語コード.. 変更対象ユーザーの新言語コード 3 user_status ユーザー状態.. 変更対象ユーザーの新ユーザー状態 4 mailaddress メールアドレス.. 変更対象ユーザーの新メールアドレス 5 user_description ユーザー説明.. 変更対象ユーザーの新ユー 6 JSON [Body] user_last_name 氏名 ( 姓 ).. ザー説明変更対象ユーザーの氏名 ( 姓 ) 7 user_first_name 氏名 ( 名 ).. 変更対象ユーザーの氏名 ( 名 ) 8 accesstoken_destruction_information_list アクセストークン破棄情報リスト 9 customer_group_id カスタマグループ ID. アクセストークン破棄対象のユーザーの情報リスト. トークンが破棄されたユーザーが属するグループの ID 0 login_id ユーザー名. トークンが破棄されたユーザーのログイン ID サンプル : "login_id": "fujitsu23", "language_code": "ja", "user_status": "", "mailaddress": "abc@xyz.com", "user_description": " ユーザー説明です ", "user_last_name": " 富士通 ", "user_first_name": " 太郎 " "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", "login_id":" fujitsu23" ] 6

21 . リクエストパラメータ定義項番ユーザーのパスワード変更を行う種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小 JSON 3 [Body] before_password 変更前パスワード桁数最大桁数設定値の login_id ユーザー名半角文字列パスワード変更対象ユーザーのユーザー名 after_password 変更後パスワード条件説明半角文字列新パスワード半角文字列旧パスワードサンプル : "login_id": "fujitsu23", "after_password":"newpassword ", "before_password":"abcdefgh " 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :200 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 accesstoken_destruction_information_list アクセストークン破棄情報リスト. アクセストークン破棄対象のユーザーの情報リスト 2 customer_group_id カスタマグループ ID. トークンが破棄されたユーザーが属するグループの ID 3 login_id ユーザー名. トークンが破棄されたユーザーのログイン ID サンプル "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", "login_id":"auth00a" ] 7

22 . リクエストパラメータ定義ユーザーの削除を行う項番種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小 URL クエリパラメータ桁数最大桁数設定値の login_id ユーザー名半角文字列削除対象ユーザーのユーザー名条件説明サンプル : /API/v/api/users/?login_id= fujitsu23 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :200 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 accesstoken_destruction_information_list アクセストークン破棄情報リスト. アクセストークン破棄対象のユーザーの情報リスト 2 customer_group_id カスタマグループ ID. トークンが破棄されたユーザーが属するグループの ID 3 login_id ユーザー名. トークンが破棄されたユーザーのログイン ID "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", "login_id":" fujitsu23" ] 8

23 3.3.5 ユーザー認証方式の情報を更新する. リクエストパラメータ定義項番種別項目名 ( 英 ) 項目名 ( 和 ) 必須多重度最小最大設定値の説明桁数桁数条件 login_id ユーザー名半角文字列対象のユーザー名 2 JSON [Body] authentication_method 認証方式.. 半角数値対象ユーザーの認証方式 0: パスワード認証 : 証明書 + パスワード認証サンプル : "login_id": "fujitsu23", "authentication_method ":"", 9

24 2. レスポンス API が正常に実行された時以下のレスポンスが返却されます HTTP ステータス :200 ボディー部 : 項番種別項目名 ( 英 ) 項目名 ( 和 ) 多重度説明 authentication_method 認証方式. 対象ユーザーの認証方式 0: パスワード認証 : 証明書 +パスワード認証 2 accesstoken_destruction_information_list アクセストークン. アクセストークン破棄対象のユ JSON 破棄情報リストーザーの情報リスト [BODY] 3 customer_group_id カスタマグループ. トークンが破棄されたユーザー ID が属するグループの ID 4 login_id ユーザー名. トークンが破棄されたユーザーのログイン ID サンプル : "authentication_method":"", "accesstoken_destruction_information_list":[ "customer_group_id":"hvlgxxym", "login_id":" fujitsu23" ] 20

変更履歴版数修正日修正箇所修正内容 /7/27 初版 /12/4 - プロパティを修正 2 / 10

変更履歴版数修正日修正箇所修正内容 /7/27 初版 /12/4 - プロパティを修正 2 / 10 対話型 Bot for FAQ チュートリアル第 1.1 版 2017 年 12 月 4 日富士通株式会社 1 / 10 変更履歴版数修正日修正箇所修正内容 1.0 2017/7/27 初版 1.1 2017/12/4 - プロパティを修正 2 / 10 はじめに本書の目的本書は Zinrai プラットフォームサービスが提供する API を利用するための具体的な手順を説明しています本書の対象読者本書は