1.7.21

Boxインストール

概要

barファイルを使って指定されたパスにBoxをインストールする。barファイルフォーマットについては 「barファイル」を参照。
本APIは非同期通信方式を採用しているため、本APIではBoxインストールを受け付けた後、即復帰する。
そのため、Boxインストール状況を確認するには、以下のAPIを使用する。

  • Box メタデータ取得 Boxインストールが異常終了した場合は、本APIにてBoxインストール状況を確認することで、エラーとなった原因を参照することができる。以下に、クライアントにおける受付から処理完了までの呼び出し方法を示す。
Boxインストールの呼び出し例（クライアントでのポーリングを30秒とした場合)
 1. Boxインストール受付
    -- MKCOL /cell1/box1
 2. Boxインストール状況確認
    -- GET /cell1/box1  -> "処理中" で返却。
    -- 30秒ポーリング
 3. GET /cell1/box1  -> "処理完了" で返却。
 ※上記 2. の処理をループして処理完了までポーリングする。

必要な権限

box-install

制限事項

Boxインストール対象Box制限

  • 既に同名のBoxが存在する場合は、Boxインストールできない。
  • 既に同じscheme URLが設定されたBoxが存在する場合は、Boxインストールできない。
  • メインBoxへのBoxインストールはできない。

barファイル制限

  • Boxインストール可能なbarファイルのファイルサイズは以下を上限とする。
    上限値を超えた場合はBoxインストールできない。
    • barファイルのファイルサイズ:100MB
    • barファイル内エントリの圧縮前ファイルサイズ：10MB

Boxインストールのログ詳細制限

  • Boxインストールのログ詳細は、Boxインストール対象Boxが所属するCellのEventBusへ出力される。 下記※1
    • そのため、ログ詳細を参照する場合は、ログファイル取得APIを使用して参照する。
    • ログファイル取得APIを使用するために、"log-read" の権限が必要である。
    • Boxインストール以外のイベントログも混在するため、"RequestKey" フィールド値でフィルタリングする必要がある。
    • "Type" フィールド値が "boxinstall" の "Requestkey" フィールド値を取得し、フィルタリングする。

その他制限

  • Boxインストール処理中にBoxインストール対象Boxを含む配下のリソースへのデータ操作はできない。
  • Boxインストール中にエラーが発生した場合のロールバックは行わない。
※1 Boxインストールのログ詳細フォーマット
状態"Type""Object""Info"
Boxインストール受付boxinstallBoxのURLステータスコード
Boxインストール処理中PL-BI-1000BoxのURLBar installation started.
PL-BI-1001Barファイル内のエントリパスInstallation started.
PL-BI-1002Barファイル内のエントリパスInstallation processing.
PL-BI-1003Barファイル内のエントリパスInstallation completed.
PL-BI-1004Barファイル内のエントリパスInstallation failed({原因}).
PL-BI-1005Unknown error({原因}).
Boxインストール完了PL-BI-0000BoxのURLBar installation completed.
PL-BI-0001BoxのURLBar installation failed({原因}).
処理コード
処理コードDescription
PL-BI-0000Boxインストール完了(正常終了)
PL-BI-0001Boxインストール完了(異常終了)
PL-BI-1000Boxインストール開始
PL-BI-1001barファイル内エントリインストール開始
PL-BI-1002barファイル内エントリインストール処理中
PL-BI-1003barファイル内エントリインストール完了(正常終了)
PL-BI-1004barファイル内エントリインストール完了(異常終了)
PL-BI-1005内部エラー

リクエスト

リクエストURL

{CellURL}{BoxName}

メソッド

MKCOL

リクエストクエリ

クエリ名概要有効値必須備考
p_cookie_peerクッキー認証値認証時にサーバから返却されたクッキー認証値×Authorizationヘッダの指定が無い場合のみ有効
クッキーの認証情報を利用する場合に指定する

リクエストヘッダ

ヘッダ名概要有効値必須備考
X-HTTP-Method-Overrideメソッドオーバーライド機能任意×POSTメソッドでリクエスト時にこの値を指定すると、指定した値がメソッドとして使用されます。
X-Overrideヘッダオーバライド機能${上書きするヘッダ名}:${値} override} $: $ {value}×通常のHTTPヘッダの値を上書きします。複数のヘッダを上書きする場合はX-Overrideヘッダを複数指定します。
X-Personium-RequestKeyイベントログに出力するRequestKeyフィールドの値半角英数、-(半角ハイフン)と_(半角アンダーバー)
最大128文字		×指定がない場合は、UUIDの独自短縮表現として${4桁}_${18桁}の形式のBase64url文字列を自動採番
AuthorizationOAuth2.0形式で、認証情報を指定するBearer {AccessToken}×※認証トークンは認証トークン取得APIで取得したトークン
Content-Typeリクエストボディの形式を指定するapplication/zip○
Content-Lengthリクエストボディのサイズを指定する半角数字×

リクエストボディ

概要有効値必須備考
インストールするbarファイルをバイナリでリクエストボディに指定するContent-Typeヘッダで指定した形式○barファイル：Zipファイル形式

barファイルのファイル構成については bar ファイルを参照。

レスポンス

ステータスコード

コードメッセージ概要備考
202Accepted処理受付成功時

レスポンスヘッダ

ヘッダ名概要備考
LocationBoxメタデータ取得API用URL
Access-Control-Allow-Originクロスドメイン通信許可ヘッダ返却値は"*"固定
X-Personium-VersionAPIの実行バージョンリクエストが処理されたAPIバージョン

Locationサンプル

Location: https://cell1.unit1.example/box1

Boxメタデータ取得API用URLの詳細は、Boxメタデータ取得を参照。

レスポンスボディ

なし

エラーメッセージ一覧

エラーメッセージ一覧を参照

cURLサンプル

curl "https://cell1.unit1.example/box1" -X MKCOL -i -H 'Content-type: application/zip' \
-H 'Authorization: Bearer AA~PBDc...(省略)...FrTjA' -H 'Accept: application/json' \
-T "/tmp/sample.bar"
← BoxエクスポートBoxメタデータ取得 →