InfiniCLOUD REST API V2(Muramasa)リファレンス

Top > 開発者資料 > InfiniCLOUD REST API V2(Muramasa)リファレンス

REST APIの概要

REST APIを利用することで、アプリケーションデベロッパーは、ユーザの収容サーバや、契約サイズ等の情報取得から、ファイルの情報取得、ファイル共有や公開機能の制御、アプリ専用領域としてのDATASETの作成、スナップショットの作成、削除など、様々な管理を行うことができる。

このAPIは認証方式に基づき、OAUTH2認証版とBASIC認証版がある、OAUTH2認証版は全ての機能を使うことができ、BASIC認証版はサブセットとなる。

OAUTH2認証版を利用する場合、REST APIでセッションをやり取りする必要があり、WebDAVアクセスも同じセッションを利用する必要がある。すでにWebDAVアプリケーションがBASIC認証を利用して作られていた場合、新規のコードを追加しないとならない可能性があるだろうし、CLIプログラムであった場合は、セッション管理が難しい側面もある。

そのため、アプリケーションをInfiniCLOUDに対応するためには、次の2つの方向性が考えられる。

  1. 既存のWebDAVアプリケーションのコードを余り変更せずに、InfiniCLOUDに対応させる方針
  2. InfiniCLOUDの機能をフルに使う方針

1の場合はBASIC認証を用いたサブセット版APIを利用することになるし、2の場合はOAUTH2を用いたフル機能版APIを用いることになる。

アプリのInfiniCLOUD対応ベストプラクティス

BASIC認証版、OAUTH2認証版の共通として、アプリのInfiniCLOUD対応のおおまかなベストプラクティスとしては、次の流れとなる。

  1. アプリケーションへのInfiniCLOUDのレジスター(初回登録時のみ)
    • REST APIのuser、あるいはba/userにてレジスターし、そのユーザが利用しているノードサーバのURLを得る。
  2. ノードサーバからユーザの容量などを取得する(任意)
    • REST APIのdataset、あるいはba/datasetにて、ユーザのデータセット情報を取得する。
  3. ノードサーバにWebDAV接続する

それ以外のREST APIは、InfiniCLOUD独自の機能を使いたい場合に必要とされるものとなっている。

なお、REST APIを受け付けるサーバは主に2つある。詳細は、サーバの種類を参照のこと。また、リファレンスマニュアルも参照。

また、アプリケーション開発者は、概ね次の手順でAPIをアクセスする。

ここでは、APIキーのテスト用として、「 FEF5078EA41D182EEF89A21E034BD680 」を利用する。

このテスト用のキーは、開発者がテストの為に自由に使っても良いが、自分のプロダクトを何らかの形で公開する場合は、専用のキーを、別途、申請して欲しい。

また、最初にこのAPI-KEY利用するとき、自動的に利用したユーザに、50GB/1年のボーナス容量が着くようになっている。増えた容量は自由に利用できるが、あくまで開発者のためのものなので、このAPI-KEYでもって、ユーザに容量を増やすようなサービスソフトウェアは控えて欲しい。

Basic認証だけで行う場合

初回登録時にアクセスすると良いAPI

  1. APIサーバのba/userリソースにアクセス(GET)。ユーザ毎に異なるノードサーバ(WebDAV URL)を取得する。
  2. 取得した返値から、接続すべきWebDAV URLを取得する。
  3. データセットへのアクセスが必要なら、ノードサーバへリクエストする。

ユーザのノードサーバは、ユーザが初めてInfiniCLOUDのアカウントを作成するときに自動的に収容先が決まり、その後は原則として変わることはない。そのため、アプリケーションが一度、取得したノードサーバをキャッシュして使い続けることができる。

またノード系サーバはBASIC認証のクレデンシャルも含めて独立して動作している。したがって、API系やウェブサーバがサーバダウンしていても、ノードサーバさえ稼働していれば、WebDAVのサービスは継続できるように設計されている。

Curlによるリクエスト例：

curl -X GET --user あなたのID -H "X-TeraCLOUD-API-KEY: FEF5078EA41D182EEF89A21E034BD680" https://api.teracloud.jp/v2/api/ba/user
Enter host password for user 'あなたのID': アプリパスワードを入力

返値例

{"result":0,"node":"ise.teracloud.jp","webdav_url":"https://ise.teracloud.jp/dav/","api_key":{"note":"jpc api test","vendor":"justplayer","activated_time":"2018-12-06 12:29:41.0","name":"jpc api test"},"introduce_code_bonus_for_inviter":2,"introduce_code_bonus_for_invitee":5,"user":"あなたのユーザ名","introduce_code":"あなたの紹介コード","capacity":あなたの契約容量,"revision":2020111801}

このようにJSONで、nodeやwebdav_urlを参照し、取得ができる。上記の例はiseというサーバが収容サーバとなっている。

node
ノードサーバ。このサーバに対してREST APIを送ること。/backup以下をアクセスする場合は、このホスト名からURLを作成すること。
webdav_url
一般にユーザが使っているWebDAVのURL。一般のアクセス領域を利用したい場合はこちらを利用する。ごく初期のユーザにはこのURLが「存在しない」場合がある。

詳しくは、リファレンスのgetUserを参照のこと。

OAUTH2認証で行う場合

初回登録時にアクセスすると良いAPI

  1. SSOのURLを出力して、ユーザに対し認証サーバにアクセスさせるように促す(初回のみ)。
  2. AuthCodeを取得、これをAPIのuserリソースにアクセス(GET)する(初回のみ)。ユーザ毎に異なるノードサーバのURLや、認可情報をアプリに保存しておく(初回のみ)。
  3. 認可情報やノードサーバのURLを利用し、ユーザ毎にデータセットAPIに接続。接続すべきWebDAV URLを取得する。
  4. データセットへのアクセスが必要なら、2と同じように、ノードサーバが持つREST APIのdatasetリソースにアクセスする。

ユーザのノードサーバは、ユーザが初めてInfiniCLOUDのアカウントを作成するときに自動的に収容先が決まり、その後は原則として変わることはない。そのため、アプリケーションが一度、取得したノードサーバのURLは保存し、使い続けることができる。

※現時点において、OAUTH2でのアクセスは非公開のため、実際のアクセス方法は割愛。

利用開始時(アプリケーション起動毎)にアクセスすると良いAPI

容量系など

アプリケーションの実装上、特に必要がないのであれば、何もする必要は無い。

※現時点において、OAUTH2でのアクセスは非公開のため、実際のアクセス方法は割愛。

WebDAVのアクセス毎にアクセスすると良いAPI

※現時点において、OAUTH2でのアクセスは非公開のため、実際のアクセス方法は割愛。

任意の時にアクセスできるAPI

ファイル関係のAPI

主なREST API

リソース名役割REST 対象サーバ
userユーザに関連する情報を操作する。アカウントAPIサーバ api.teracloud.jp
datasetデータセットに関連する操作を行う。
各ノードサーバ *.teracloud.jp
snapshotデータセットのスナップショットを作成、削除をする。各ノードサーバ *.teracloud.jp
filepropertiesファイルのプロパティを取得する。メディア情報を含む。各ノードサーバ *.teracloud.jp

画像ファイルのサムネイル取得に関して

画像ファイルのWebDAVアクセス時、GETパラメタにて、width、heightを指定することにより、サーバ側で縮小したサムネイルを取得することができる。ただし、この処理は大変に重く、初回が遅いため、下記のガイドラインに従う必要がある。

  1. API filepropertiesで、JPEG画像ピクセルを取得する。
    • 1つのディレクトリ内において、複数ファイルの処理が必要な場合、ディレクトリに対して一括で取得することもできる。
  2. ファイル毎に、画像ピクセルの1/2nのサイズでリクエストを行う。
    • 例：
      元ファイルが2048x1536で、必要なサイズが640x480だった場合、元ファイルの1/21の?width=1024&height=768、あるいは1/22の?width=512&height=384を指定する。これ以外のサイズのサムネイル取得も2020年5月現時点では可能だが、著しく遅い事が確認されているため、1/2nの範囲以外の仕様を変更する可能性がある。また、このサイズにおいては、二度目のリクエストではサーバ内でキャッシュされる。
  3. ブラウザ、ないしはクライアント側で、本当に必要な画像のサイズへ拡大縮小を行う。

※なお、このガイドラインは暫定的なものであるため、1/2n以外のリクエストの仕様は未定。

リファレンスマニュアル

リファレンスはこちらを参照のこと。

 
アカウント作成（無料 20GB）

1分で簡単登録！今すぐスタート！
Works online, Windows, Mac, iOS and Android