オブジェクトストレージサービス
　コマンドラインインタフェース

    Copyright Fujitsu
=============================================================================================


1. はじめに
　このコマンドラインインタフェースを使うことにより、オブジェクトストレージサービス
が提供するインターネット経由でのストレージサービスを利用することができます。
　オブジェクトストレージサービスについては、下記URLをご覧ください。
     https://pfs.nifcloud.com/service/obj_storage_service.htm


2. 推奨環境
　このコマンドラインインタフェースを利用するためには、JRE(Java Runtime Environment)
をインストールする必要があります。
　Java SE 8以降を推奨します。
　また、このパッケージに含まれるコマンドスクリプト(ncs_cli.sh)は、Linux向けのもの
です。
　OpenJDK version 1.8.0_312 で動作確認


3. 概要
　1) バケット
　　　バケットは、トップディレクトリのようなもので、以下のような特徴があります。
　　　・ユーザーは、1人につき最大20個のバケットを作成することができます。
　　　・バケット名は、すべてのユーザーを通してユニークである必要があります。
　　　・バケットは階層にはできません。
　　　・バケット名の制限については、APIリファレンスをご覧ください。

　2) オブジェクト
　　　オブジェクトは、ファイルまたはディレクトリのことです。オブジェクトは、
　　　バケットの下に置かれます。
　　　オブジェクト名の制限については、APIリファレンスをご覧ください。

4. 準備
　1) このzipファイルを解凍します。
　　$ unzip NIFCLOUDStorage-SDK-CLI.zip

　2) 認証キーの設定
　　解凍後にできた credentials.propertiesにオブジェクトストレージサービスより取得した
　　Access Key IDとSecret Access Keyを記述し、保存します。

　　　# Fill in your NIFCLOUD Storage Service Access Key ID and Secret Access Key
　　　# https://pfs.nifcloud.com/api/obj_storage/
　　　accessKey =
　　　secretKey =

　3) プロキシ経由の設定
　　プロキシ経由でインターネットに接続している場合には、ncs_cli.shに次の設定を行って
　　保存します。必要な個所のコメント(#)を削除します。

　　　a) ホスト／ポートのみの場合
　　　　ex. ホスト名:proxy　ポート番号:8080
　　　　# proxy settings
　　　　PROXY_HOST="-Dhttp.proxyHost=proxy"
　　　　PROXY_PORT="-Dhttp.proxyPort=8080"
　　　　#PROXY_USER="-Dhttp.proxyUser=user"
　　　　#PROXY_PASS="-Dhttp.proxyPass=pass"

　　　b) ユーザー認証が必要な場合
　　　　ex. ホスト名:proxy　ポート番号:8080　ユーザー名:proxyuser　パスワード:password
　　　　# proxy settings
　　　　PROXY_HOST="-Dhttp.proxyHost=proxy"
　　　　PROXY_PORT="-Dhttp.proxyPort=8080"
　　　　PROXY_USER="-Dhttp.proxyUser=proxyuser"
　　　　PROXY_PASS="-Dhttp.proxyPass=password"

　4) リトライの設定
　　通信失敗時等の最大リトライ回数の設定を行う場合は、ncs_cli.shに次の設定を行って
　　保存します。必要な場合はコメント(#)を削除します。
　　未設定時は、最大リトライ回数が5で動作します。

　　　ex. 通信失敗時に最大3回のリトライを行いたい場合
　　　# retry settings
　　　MAX_RETRY="-Dhttp.maxRetry=3"

　5) マルチパートアップロードの設定
　　マルチパートアップロードの設定を行う場合は、ncs_cli.shに次の設定を行って保存します。
　　最大スレッド数、分割サイズ、マルチパートアップロード開始サイズの閾値、最大アップロード
　　サイズを設定できます。必要な箇所のコメント(#)を削除します。
　　未設定時は、最大スレッド数が10、分割サイズが5MB、マルチパートアップロードの閾値が16MB、
　　アップロードの最大サイズが5GBでそれぞれ動作します。

　　　ex. 20MBを超えるファイルに対して、1パート5MB、最大5スレッド、アップロードの最大サイズ
　　　　　を32GBでマルチパートアップロードを行う場合
　　　# multipart settings
　　　MAX_THREADS="-Dmultipart.maxThreads=5"
　　　MULTIPART_THRESHOLD="-Dmultipart.threshold=20971520"
　　　MULTIPART_PART_SIZE="-Dmultipart.partSize=5242880"
　　　MULTIPART_MAX_SIZE="-Dmultipart.maxSize=34359738368"

　6) 暗号化キーの設定
　　データの暗号化を利用する場合は、credentials.propertiesに秘密鍵のキーフレーズを記述し、
　　保存します。このキーフレーズは任意の値です。

　　　# The private keyphrase for using encryption
　　　privateKeyphrase =

　7) エンドポイントの設定
　　エンドポイントの設定を行う場合は、ncs_cli.shに次の設定を行って保存します。
　　必要な場合はコメント(#)を削除します。
　　未設定時は東リージョンへのHTTPS接続を行います。(https://jp-east-1.storage.api.nifcloud.com/)

　　　ex. 西リージョンに対してHTTPS接続を行う場合
　　　# endpoint settings
　　　ENDPOINT="-Dendpoint=https://jp-west-2.storage.api.nifcloud.com/"


5. 使用方法
　5.1 コマンドヘルプ
　　コマンドヘルプを表示するには、次のコマンドを実行します。

　　~$ sh ncs_cli.sh -h

　5.2 ファイルのアップロード
　　1) バケットの作成
　　　あらかじめ、バケットを作成しておく必要があります。
　　　作成していない場合は、次のコマンドを実行します。
　　　前述のバケット名の制限をご覧ください。
　　　
　　　例）バケット名を sample-bucket1 とした場合

　　　~$ sh ncs_cli.sh mb ncss://sample-bucket1

　　2) バケット一覧取得
　　　バケットが作成できたことを確認します。

　　　~$ sh ncs_cli.sh ls
　　　2011-03-01 10:47  ncss://sample-bucket1

　　3) バケット内の一覧取得
　　　バケット内のオブジェクト一覧を取得します。実際には空です。

　　　~$ sh ncs_cli.sh ls ncss://sample-bucket1
　　　~$

　　4) ファイルのアップロード
　　　前述のバケットにsome-file.xmlというファイルをアップロードするには、
　　　次のコマンドを実行します。

　　　~$ sh ncs_cli.sh put some-file.xml ncss://sample-bucket1/some-file.xml
　　　some-file.xml -> ncss://sample-bucket1/some-file.xml

　　5) バケット内の一覧を再度取得
　　　バケット内のオブジェクト一覧を取得します。

　　　~$ sh ncs_cli.sh ls ncss://sample-bucket1
　　　2011-03-01 11:03    123456  ncss://sample-bucket1/some-file.xml

　5.3 ファイルのダウンロード
　　1) ファイルのダウンロード
　　　前述の sample-bucket1にあるsome-file.xmlをsome-file-2.xmlとして
　　　ダウンロードするには、次のコマンドを実行します。

　　　~$ sh ncs_cli.sh get ncss://sample-bucket1/some-file.xml some-file-2.xml
　　　ncss://sample-bucket1/some-file.xml -> some-file-2.xml

　　2) チェックサムの比較
　　　md5sumのようなコマンドを利用して、ダウンロードしたファイルのチェックサムを
　　　比較します。

　　　~$ md5sum some-file.xml some-file-2.xml
　　　181e85e535e3da0c641de2b28da77d0e  some-file.xml
　　　181e85e535e3da0c641de2b28da77d0e  some-file-2.xml

　5.4 バケット操作
　　1) バケット作成
　　　バケットを作成する場合は、次のコマンドを実行します。

　　　例）バケット名を sample-bucket2 とした場合

　　　~$ sh ncs_cli.sh mb ncss://sample-bucket2

　　2) バケット一覧取得
　　　バケットの一覧を取得するには、次のコマンドを実行します。

　　　~$ sh ncs_cli.sh ls
　　　2011-03-01 10:47  ncss://sample-bucket1
　　　2011-03-02 21:32  ncss://sample-bucket2
　　　2011-03-02 21:38  ncss://sample-bucket3

　　3) バケット削除
　　　バケットを削除するには、次のコマンドを実行します。ただし、バケット内に
　　　オブジェクトが存在する場合、バケットの削除ができないのでご注意ください。

　　　例）バケット名を sample-bucket2 とした場合

　　　~$ sh ncs_cli.sh rb ncss://sample-bucket2

　5.5 オブジェクト操作
　　1) ディレクトリ作成
　　　ディレクトリを作成するには、次のコマンドを実行します。

　　　例）バケット名を sample-bucket2 、ディレクトリ名を doc とした場合

　　　~$ sh ncs_cli.sh put doc/ ncss://sample-bucket2/doc/

　　　※注意：ディレクトリの作成が成功した場合は、5.4 2)のバケット一覧取得の際に
　　　　オブジェクト名の最後が「/」で終わっています。

　　2) ファイルアップロード
　　　ディレクトリ配下にファイルをアップロードするには、次のコマンドを実行します。

　　　例）1)で作成したディレクトリの下に、 file-name.jpg をアップロードする場合

　　　~$ sh ncs_cli.sh put file-name.jpg ncss://sample-bucket2/doc/file-name.jpg


　　3) ファイルダウンロード
　　　ファイルのダウンロードを行うには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2/doc/file-name.jpg を file-name2.jpg として
　　　　　ダウンロードする場合

　　　~$ sh ncs_cli.sh get ncss://sample-bucket2/doc/file-name.jpg file-name2.jpg

　　4) ファイルの削除
　　　ファイルの削除を行うには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2/doc/file-name.jpg を削除する場合

　　　~$ sh ncs_cli.sh del ncss://sample-bucket2/doc/file-name.jpg

　　5) ディレクトリの削除
　　　ディレクトリの削除を行うには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2/doc/ を削除する場合

　　　~$ sh ncs_cli.sh del ncss://sample-bucket2/doc/

　　　※注意：ディレクトリ削除をした場合は、該当ディレクトリ配下に
　　　　あったオブジェクトは削除されませんので、ご注意ください。

　　6) バケット内のオブジェクト一覧取得
　　　バケット内のオブジェクト一覧を取得するには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2 内のオブジェクト一覧を取得する場合

　　　~$ sh ncs_cli.sh ls ncss://sample-bucket2

　　　key-marker、prefix、max-keysパラメータを利用する場合、以下のように引数を渡して下さい。

　　　~$ sh ncs_cli.sh ls ncss://<bucket-name> prefix=xxxx

　　7) 全オブジェクト一覧の取得
　　　全バケット内のオブジェクト一覧を取得するには、次のコマンドを実行します。

　　　~$ sh ncs_cli.sh la

　　8) オブジェクトのコピー
　　　オブジェクトのコピーを行うには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2/file-name.txt を ncss://sample-bucket2/copy-file.txt
　　　　　としてコピーする場合

　　　~$ sh ncs_cli.sh cp ncss://sample-bucket2/file-name.txt ncss://sample-bucket2/copy-file.txt

　　9) ファイルのヘッダー情報取得
　　　ファイルのヘッダー情報を取得するには、次のコマンドを実行します。

　　　例）ncss://sample-bucket2/file-name.txt のヘッダー情報を取得する場合

　　　~$ sh ncs_cli.sh head ncss://sample-bucket2/file-name.txt

　5.6 メタデータ設定
　　　ファイルアップロード時に、追加ヘッダを指定しメタデータを設定することができます。
　　　追加ヘッダは複数回指定することができます。ただし、同じキーのヘッダは指定することはできません。
　　　キーの制限については、APIリファレンスをご覧ください。
　　　
　　　例）sample-bucket3 に、 file-name.jpg を x-aws-meta-sample: value を追加してアップロード
　　　　する場合

　　　~$ sh ncs_cli.sh --add-header=x-amz-meta-sample:value put file-name.jpg ncss://sample-bucket3/file-name.jpg

　5.7 認証キーファイルの指定
　　　デフォルトと異なる認証キーファイルを指定する場合は、次のように指定します。

　　　例）認証キーファイルが、/foo/bar/sample.properties の場合

　　　~$ sh ncs_cli.sh -c /foo/bar/sample.properties ls

　5.8 データ暗号化の利用
　　1) ファイルの暗号化アップロード
　　　ファイルを暗号化してアップロードするには、アップロード時のコマンドにオプションを指定して
　　　実行します。
　　　※マルチパートアップロードの場合、暗号化は利用できません。

　　　例）file-name.txt を暗号化して ncss://sample-bucket2/file-name.txt へアップロードする場合

　　　~$ sh ncs_cli.sh --encrypt put file-name.txt ncss://sample-bucket2/file-name.txt

　　2) ファイルの復号化ダウンロード
　　　暗号化されたファイルをダウンロードして復号化するには、ダウンロード時のコマンドに
　　　オプションを指定して実行します。

　　　例）ncss://sample-bucket2/file-name.txt を復号化して file-name.txt としてダウンロードする場合

　　　~$ sh ncs_cli.sh --encrypt get ncss://sample-bucket2/file-name.txt file-name.txt

　5.9 大容量ファイルのアップロード異常終了時のデータ破棄
　　　大容量ファイルのアップロードが異常終了した場合、サーバ上にアップロードデータが残るため、
　　　これを破棄する必要があります。
　　　アップロードが正常終了した場合は、対処は不要です。
　　　注意：一度でも異常終了になったアップロードデータは、同一オブジェクト名でアップロードが
　　　　　　正常終了になった場合も破棄されることはありません。
　　　　　　バケットの削除が行われた場合に、バケット配下で破棄されていないアップロードデータ
　　　　　　については破棄されます。

　　1) 準備
　　　マルチパートアップロードに利用するアップロードIDを取得するため、cli/log4j.properties の
　　　log4j.rootLogger を INFO に設定します。
　　　例）log4j.rootLogger=INFO, stdout

　　2) ファイルのマルチパートアップロード
　　　大容量ファイルをアップロードします。

　　　例）大容量ファイルの場合、以下のようにマルチパートでのアップロードログが出力されます。

　　　~$ sh ncs_cli.sh put file-name.txt ncss://sample-bucket2/file-name.txt
　　　[INFO ] NiftyCloudClient execute - Sending Request: POST jp-east-1.storage.api.nifcloud.com //sample-bucket2 \
     Parameters: (uploads: null, ) Headers: (Authorization: AWS4-HMAC-SHA256 \
     Credential=XXXXXX/20220401/jp-east-3/s3/aws4_request, SignedHeaders=content-length;host;x-amz-content-sha256; \
     x-amz-date, Signature=XXXXXX, x-amz-Date: 20220401T002224Z, x-amz-Content-SHA256: \
     e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, )
　　　[INFO ] request parseResponse - Success: 200, Request ID: 1648772545140507
　　　[INFO ] NiftyCloudClient execute - Sending Request: PUT jp-east-1.storage.api.nifcloud.com //sample-bucket2 \
     Parameters: (uploadId: Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ, partNumber: 1, ) Headers: \
     (Authorization: AWS4-HMAC-SHA256 Credential=XXXXXX/20220401/jp-east-3/s3/aws4_request, \
     SignedHeaders=content-length;host;x-amz-content-sha256;x-amz-date, Signature=XXXXXX, \
     x-amz-Date: 20220401T002225Z, \
     x-amz-Content-SHA256: c036cbb7553a909f8b8877d4461924307f27ecb66cff928eeeafd569c3887e29, )
     [INFO ] NiftyCloudClient execute - Sending Request: PUT jp-east-1.storage.api.nifcloud.com //sample-bucket2 \
     Parameters: (uploadId: Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ, partNumber: 2, ) Headers: \
     (Authorization: AWS4-HMAC-SHA256 Credential=XXXXXX/20220401/jp-east-3/s3/aws4_request, \
     SignedHeaders=content-length;host;x-amz-content-sha256;x-amz-date, Signature=XXXXXX, \
     x-amz-Date: 20220401T002225Z, \
     x-amz-Content-SHA256: c036cbb7553a909f8b8877d4461924307f27ecb66cff928eeeafd569c3887e29, )
     :
     :
     :

　　　上記例の3メッセージ目にある「(uploadId: Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ, partNumber: 1, )」の
　　　「Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ」がアップロードIDになります。
　　　アップロードIDはそのマルチパートアップロードリクエストとして全てのパートで同一となります。

　　3) アップロードデータの破棄
　　　アップロードIDを指定して、アップロードデータの破棄を行います。

　　　例）アップロードIDが「Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ」で「ncss://sample-bucket2/file-name.txt」
　　　　　のアップロードデータを破棄する場合。

　　　~$ sh ncs_cli.sh --upload-id=Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ abort ncss://sample-bucket2/file-name.txt
　　　[INFO ] NiftyCloudClient execute - Sending Request: DELETE jp-east-1.storage.api.nifcloud.com //sample-bucket2 \
     Parameters: (uploadId: Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ, ) Headers: \
     (Authorization: AWS4-HMAC-SHA256 Credential=XXXXXX/20220401/jp-east-3/s3/aws4_request, \
     SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=XXXXXX, x-amz-Date: 20220401T003130Z, \
     x-amz-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, )
     [INFO ] request parseResponse - Success: 204, Request ID: 1648773091015002
     ncss://sample-bucket2/file-name.txt(Nv4x4suSfF5VZg9zRAuuvEIj5kRdBHUyu_bQqVcI-B29Dsp2Kgic7T0TEQ) deleted
　　　~$
