Return Data Specification_API_Object Storage-CDNetworks ドキュメント

このドキュメントは、オブジェクトストレージサービスにおけるデータレスポンスおよびコールバックメカニズムについて、以下の3つのコアサブシステムを中心に包括的にガイドします。

クライアントレスポンス制御（ReturnBody）
動的変数（$(bucket)、$(x:customVar)）を用いたクライアント側への返却値のカスタマイズ。通常アップロードではキーバリュー形式、マルチパートアップロードではJSON形式に対応。
サーバーコールバックプロトコル（CallbackBody）
HMAC-SHA1署名付きでコールバックを設定し、非同期システム連携に対応。
ファイル命名＆処理（SaveKey/PersistentOps）
タイムスタンプ/UUID変数によるストレージパス生成や、ビデオトランスコードなどの自動化ワークフロー設定が可能。

`returnBody` の返却メカニズム

シナリオ1:

returnBodyおよびreturnUrlを指定した場合のリクエストURL返却

例:

    bucket:     image
    key:        205.jpg
    returnBody: bucket=$(bucket)&key=$(key)
    returnUrl:  http://www.abc.com

アップローダーへ返却される内容:

    http://www.abc.com?bucket=image&key=205.jpg&hash=610d0284a0923298247d3a269ee28908cdcc7476

シナリオ2:

returnBodyを指定し、returnUrlを未指定の場合は、returnBodyで指定した内容をそのまま返します。

returnBodyを使うことで、クライアントへの返却情報を柔軟にカスタマイズできます。現時点で カスタム置換変数 と 指定置換変数 の2種類のパラメータ方式をサポートしており、両者を自由に組み合わせて利用できます。

注意:

通常アップロードの場合、returnBody既定の返却内容はファイルのハッシュ値です。マルチパートアップロードの場合、ハッシュ値とkeyが返ります。

設定後、returnBodyの返却内容は URLセーフBase64でエンコードされます。説明の便宜上、以下サンプルはデコード済みです。

カスタム置換変数

フォーマット: $(x:variable)
例:

    ReturnBody: position=$(x:position)&message=$(x:message)
    Request Parameter: position=abc&message=Success

通常アップロードによる返却内容:

    position=abc&message=Success&hash=610d0284a0923298247d3a269ee28908cdcc7476

マルチパートアップロードによる返却内容:

    {
        "position":"abc",
        "message":"Success",
        "key":"filename",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

注意: カスタム変数はUTF-8形式で「&」を含まないこと。含む場合は文字化けします。

指定置換変数

フォーマット: $(variable)
例:

    returnBody: url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

通常アップロードによる返却内容:

    url=http://abc.com/1.jpg&fsize=1231341&bucket=test&hash=610d0284a0923298247d3a269ee28908cdcc7476

マルチパートアップロードによる返却内容:

    {
        "url":"http://abc.com/1.jpg",
        "fsize":"1231341",
        "bucket":"test",
        "key":"1.jpg",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

注意: 指定パラメータの返却順は定義通りとなります。

変数一覧:

指定変数	説明	アップロードインターフェース
$(persistentID)	アップロード前処理や永続化処理のプロセスID	通常アップロード（マルチパートは限定的）
$(bucket)	アップロード対象バケット名	通常アップロード/マルチパート
$(key)	バケット内リソース名	通常アップロード/マルチパート
$(fname)	アップロード元のファイル名	通常/マルチパート
$(hash)	リソースのEtag値	通常/マルチパート
$(fsize)	リソース容量（バイト）	通常/マルチパート
$(url)	実リソースパス	通常/マルチパート
$(ip)	リクエスト元IPアドレス	通常/マルチパート
$(imageInfo)	アップロード画像の基本情報	通常/マルチパート
$(exif)	アップロード画像のEXIF情報	通常/マルチパート
$(avinfo)	動画のメタ情報（JSON、URLセーフBase64エンコード）	通常/マルチパート
$(mimeType)	リソース種別（例: JPG画像ならimage/jpg）	通常/マルチパート

`callbackBody` コールバックメカニズム

callbackBodyを使うことで、callbackUrlで返す通知/データフォーマットをカスタマイズできます。

注意: コールバック内容はURLEncodeされ、コールバックサーバー側でデコードして利用してください。

callbackBody は「定数」「カスタム置換変数」「指定置換変数」の3方式をサポート、混在利用可能です。

コールバックデータ説明

定数

フォーマット: key1=value1&key2=value2
説明: 指定された値をそのままcallbackUrlに通知
例:

username=john&age=21

カスタム置換変数

フォーマット: $(x:variable)
例:

    callbackBody: position=$(x:position)&message=$(x:message)

$(x:position)=abc、$(x:message)=Successの場合、コールバックサーバーには

    position%3dabc%26message%3dSuccess%0a%0a

が通知されます。

注意: カスタム変数はUTF-8形式で&は使えません。含むと文字化けします。

指定置換変数

フォーマット: $(variable)
例:

    callbackBody: url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

コールバックサーバー（urlencode済）の返却内容は:

    url%3daHR0cDovL2FiYy5jb20vMS5qcGc%3d%26fisize%3d1231341%26bucket%3dtest%0a

変数一覧:

指定変数	説明	アップロードインターフェース
$(persistentID)	アップロード前処理や永続化処理のプロセスID	通常アップロード（マルチパートは限定）
$(bucket)	アップロード対象バケット名	通常/マルチパート
$(key)	バケット内リソース名	通常/マルチパート
$(fname)	アップロード元ファイル名	通常/マルチパート
$(hash)	リソースのEtag値	通常/マルチパート
$(fsize)	バイト単位のリソースサイズ	通常/マルチパート
$(mimeType)	リソース種別 (例: image/jpg)	通常/マルチパート
$(url)	実リソースパス（URLセーフBase64エンコード）	通常/マルチパート
$(ip)	リクエスト元IPアドレス	通常/マルチパート
$(costTime)	サーバー受信～コールバック開始までの時間（ミリ秒）	通常/マルチパート
$(avinfo)	動画メタ情報（JSON・エンコード済）	通常/マルチパート
$(imageInfo)	画像基本情報（エンコード済）	通常/マルチパート
$(exif)	画像EXIF情報（エンコード済）	通常/マルチパート
$(mimeType)	リソース種別 (例: image/jpg)	通常/マルチパート

コールバックレスポンス説明

ストレージがコールバックサーバーのレスポンス（JSON形式、レスポンスコード）を取得後、それに基づいてクライアントに返答します。

コールバックサーバーのレスポンスが200かつ内容がJSONの場合、オブジェクトストレージのクライアントへの返答は200で、内容は以下の通りです。

{
  "hash": "<hash string>",
  "response": "<response string>"
}

コールバックサーバーのレスポンスが異常な場合、クライアントへの返答はステータスコード579となり、内容は以下です。

{
  "hash": "<hash string>",
  "error": {
    "callbackUrl": "<callbackUrl string>",
    "callback_bodyType": "<callback_bodyType string>",
    "callback_body": "<callback_body string>",
    "token": "<token string>",
    "err_code": "<err_code string>",
    "error": "<unexpected response>"
  }
}

コールバック安全メカニズム

CDNetworksオブジェクトストレージは、callbackリクエストヘッダに Authorization フィールドを追加します。

フォーマット:

<Accesskey>:<Urlsafe_Base64_Encode(hmac_sha1(callBackUrlWithQuery+"\n"+urlsafe_base64_encode(callbackBody),SecretKey))>

例:

d0e56f9f4a75267eba123348f839fbedcd9464c6:OTQzNzU5YWVjOTZlNTRlMWIwYmQzZTA2ZDhjMTFhOWEyNGM1ZjIzZg==

コールバックリトライメカニズム

アップロードコールバック失敗時は、3回連続自動リトライした後、以降は1分ごとに計5回（合計8回）リトライします。

リトライ後にコールバックが成功すれば、200の正常レスポンスを返却します。
リトライ後も正常レスポンスがなければ、579の異常レスポンスを返却します。

`saveKey` カスタム命名

saveKeyはリソース名のカスタマイズ用で、アップロードscopeにkeyが未指定の場合のみ有効です。このフィールドは単一ファイル通常アップロードのみ対応。
saveKeyは「定数」「カスタム置換変数」「指定置換変数」の3方式サポート、組み合わせて使用可能です。

リソース名指定方法

定数

フォーマット: value
説明: 指定値をそのまま命名に使用
例:

saveKey: constant

フォルダ

フォーマット: dirname/key
説明: オブジェクトストレージは多階層ディレクトリを持たないが、ファイル名により仮想パスを表現可能
例:

saveKey: dir/key

カスタム変数指定

フォーマット: $(x:variable)
例:

saveKey: $(x:position)

$(x:position)=test の場合、ファイルは「test」として保存されます。

注意: カスタム変数はUTF-8形式、&は含めないでください。

指定置換変数

フォーマット: $(variable)
例:

saveKey: $(year)/$(month)/$(hash)

現在時刻が2016年4月の場合は 2016/04/HASH値となります。

変数一覧:

指定変数	説明
$(fname)	アップロード元ファイル名
$(hash)	リソースのEtag値
$(mimeType)	リソース種別（例: JPGはimage/jpg）
$(suffix)	元ファイルから取得される拡張子。拡張子なければunknown
$(fprefix)	リソースの元ファイル名（拡張子除く）
$(uuid)	ランダム値
$(year)	アップロード年（例: 2015）
$(month)	アップロード月（例: 01）
$(day)	アップロード日（例: 01）
$(hour)	アップロード時（例: 01）
$(min)	アップロード分（例: 01）
$(sec)	アップロード秒（例: 01）

トランスコード命令について

動画トランスコード・サムネイル生成などのコマンドはOpsパラメータ形式を参照してください。

例:

ビデオトランスコード:

persistentOps=avthumb/mp4/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=;avthumb/flv/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=

ビデオサムネイル生成:

persistentOps=vframe/jpg/offset/10|saveas/YnVja2V0OmZpbGVrZXk=;vframe/jpg/offset/15|saveas/YnVja2V0OmZpbGVrZXk=

注意: コマンドは連結可能で、複数コマンドは「;」で区切って指定します。

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

Return Data Specification

`returnBody` の返却メカニズム

シナリオ1:

シナリオ2:

`callbackBody` コールバックメカニズム

コールバックデータ説明

コールバックレスポンス説明

コールバック安全メカニズム

コールバックリトライメカニズム

`saveKey` カスタム命名

リソース名指定方法

カスタム変数指定

トランスコード命令について

目次

Media Delivery

Cloud Security

Web Performance

Enterprise Application

Storage

Edge Computing

Console Guide

API Docs

Return Data Specification

returnBody の返却メカニズム

シナリオ1:

シナリオ2:

callbackBody コールバックメカニズム

コールバックデータ説明

コールバックレスポンス説明

コールバック安全メカニズム

コールバックリトライメカニズム

saveKey カスタム命名

リソース名指定方法

カスタム変数指定

トランスコード命令について

目次

`returnBody` の返却メカニズム

`callbackBody` コールバックメカニズム

`saveKey` カスタム命名