アップロードコールバックの概要

ファイルがアップロードされると、OSS はコールバックサーバーにコールバックを提供します。 アップロードコールバックを実装するため、アップロード要求に関連するコールバックパラメーターを使用することができます。 アップロードコールバックをサポートしている API は、PutObjectPostObject、および CompleteMultipartUpload です。 詳しくは、「開発者ガイド」および「API Reference」をご参照ください。

コールバックサーバーはサービスサーバーとも呼ばれます。

適用シナリオ

  • 通知

    一般的な適用シナリオは、承認されたサードパーティ (ファイルのアップロード中にコールバックパラメーターを指定) によるアップロードとコールバックです。 アップロードが完了した後、OSS はコールバック要求をコールバックサーバーに送信します。 コールバックサーバーは、コールバック要求を受信した際、アップロード情報を記録します。

  • 処理、レビュー、および統計

    コールバックサーバーは、コールバック要求を受信した際、アップロードされたファイルの処理、レビュー、および統計を行います。

データストリーム

パラメーターについて、次のテーブルで説明します。

データストリーム 意味 説明
1 クライアントはファイルをアップロードし、コールバックパラメーターを伝送します [1]。 アップロード は SDK (PutObjectCompleteMultipartUpload) によって実装され、コールバックは PostObject API によって実装されます。
2 OSS インスタンスはファイルを保存し、コールバックを開始します。 OSS インスタンスは、アップロード要求で指定された CallbackUrlPOST [2] 要求を送信します。 コールバックタイムアウト時間は 5 秒です [3]。
3 コールバックサーバーは処理結果を返します。
  • コールバックサーバーから返されるメッセージ本文は、JSON 形式である必要があります。
  • OSSは、返された結果が 200 ではない場合、コールバックが失敗したと判断します。[4]
4 OSS はアップロードとコールバックの結果を返します。
  • アップロードとコールバックのどちらもが成功した場合、200 が返されます。
  • アップロードは成功したもののコールバックが失敗した場合、203 が返されます。 ErrorCode の値は CallbackFailed です。ErrorMessage はエラーの原因を示します。
  • [1] 形式の詳細については、「SDK / PostObject」をご参照ください。
  • [2] コールバック要求 POST の形式の詳細については、「Callback」をご参照ください。
  • [3 ]タイムアウト時間は固定されており、設定できません。
  • [4] パラメーターの無効化、または認証失敗の場合は、40x が返されます。タイムアウト、または接続失敗の場合は、50x が返されます。

SDK / PostObject

ファイルのアップロード中に、コールバックパラメーターを設定して、コールバックサーバーの URL、コールバックサーバーに送信されるデータ、およびデータ形式を指定できます。 コールバックサーバーがコールバックを処理するときに、bucketobject などのコンテキスト情報がシステム変数を使用して指定されます。 他のコンテキスト情報はカスタム変数を使用して指定されます。

アップロードコールバックパラメーター

アップロードコールバックには、以下のパラメーターが使用できます。

フィールド 意味 説明
callbackUrl コールバックサーバーのアドレス 必須項目
callbackHost コールバック要求メッセージヘッダーの Host の値 任意項目。 既定値は callbackUrl です。
callbackBody コールバック要求のメッセージ本文 必須項目 システム変数とカスタム変数を保持できます。
callbackBodyType コールバック要求メッセージのヘッダーの Content-Type 値。つまり、callbackBody のデータ形式。 任意項目。 既定値では、application/x-www-form-urlencoded。または application/json です。

アップロードコールバックパラメーターは、次の 2 つの方法のいずれかのアップロード要求によって伝送されます。

  • コールバックパラメーターはメッセージヘッダーの x-oss-callback によって伝送されます。 これは一般的かつ推奨されている方法です。
  • コールバックパラメーターは、QueryString 内のcallbackによって運ばれます。

x-oss-callback または callback 値を生成するための規則は次のとおりです。

Callback := Base64(CallbackJson)
CallbackJson := '{' CallbackUrlItem, CallbackBodyItem [, CallbackHostItem, CallbackBodyTypeItem] '}' 
CallbackUrlItem := '"'callbackUrl'"' ':' '"'CallbackUrlValue'"'
CallbackBodyItem := '"'callbackBody'"' ':' '"'CallbackBodyValue'"'
CallbackHostItem := '"'callbackHost'"' ':' '"'CallbackHostValue'"'
CallbackBodyTypeItem := '"'callbackBodyType'"' : '"'CallbackBodyType'"'
CallbackBodyType := application/x-www-form-urlencoded | application/json

CallbackJson の値の例は次のとおりです。


    "callbackUrl" : "http://abc.com/test.php",
    "callbackHost" : "oss-cn-hangzhou.aliyuncs.com",
    "callbackBody" : "{\"bucket\":${mimeType}, \"object\":${object},\"size\":${size},\"mimeType\":${mimeType},\"my_var\":${x:my_var}}",
    "callbackBodyType" : "application/json"
				
または、以下のようになります。

    "callbackUrl" : "http://abc.com/test.php",
    "callbackBody" : "bucket=${bucket}&object=${object}&etag=${etag}&size=${size}&mimeType=${mimeType}&my_var=${x:my_var}"
				

システム変数とカスタム変数

CallbackJson の例にある ${bucket}${object}${size} などの CallbackJson 変数は、OSS 定義のシステム変数です。 コールバック中に、OSS はシステム変数を実際値に置き換えます。次のテーブルは、OSS 定義のシステム変数の一覧です。

変数 意味
${bucket} ストレージスペース名
${object} ファイル名
${etag} ファイルのタグ
${size} ファイルサイズ
${mimeType} image / jpeg などのファイルタイプ
$ {imageInfo.height} 画像の高さ
$ {imageInfo.width} 画像幅
$ {imageInfo.format} .jpgや.pngなどのイメージフォーマット
  • システム変数は大文字と小文字を区別します。
  • システム変数の形式は ${bucket} である必要があります。
  • imageInfo はイメージ形式を対象に設定されます。 非イメージ形式の場合、imageInfo の値は空白です。

CallbackJson の例にある ${x:my_var} などの CallbackJson の変数は、カスタム変数です。 コールバック中に、OSS はカスタム変数をカスタム値に置き換えます。 カスタム変数値は、次の 2 つの方法のいずれかにより、アップロード要求によって定義され、伝送されます。

  • カスタム変数はメッセージヘッダーの x-oss-callback-var によって伝送されます。 これは一般的かつ推奨されている方法です。
  • カスタム変数は、QueryString の callback-var によって伝送されます。

x-oss-callback-var または callback-var 値を生成するための規則は次のとおりです。

CallbackVar := Base64(CallbackVarJson)
CallbackVarJson := '{' CallbackVarItem [, CallbackVarItem]* '}'
CallbackVarItem := '"''x:'VarName'"' : '"'VarValue'"'

CallbackVarJsonの値の例は次のとおりです。





    "x:my_var1" : "value1",
    "x:my_var2" : "value2"
			
  • カスタム変数は x: で始まる必要があります。大文字と小文字は区別され、${x:my_var} の形式で記述されます。
  • カスタム可変長は、メッセージヘッダーと URL の長さによって制限されます。 カスタム変数の数は 10 個を超えないようにし、合計長は 512 バイトを超えないようにすることを推奨します。

SDK の使用例

JAVA や JS などの一部の SDK では、上記の手順がカプセル化されています。 Python、PHP、C などの一部の SDK では、アップロードコールバックパラメーターとカスタム変数を生成するため、前述の規則を使用する必要があります。 次のテーブルにて、SDK の使用例を一覧表示します。

SDK アップロードコールバックの例 説明
JAVA CallbackSample.java CallbackBody のエスケープ文字に注意してください。
Python object_callback.py -
PHP Callback.php $options にある OSS_CALLBACKOSS_CALLBACK_VAR は、SDK で実装されている Base64 を使ってエンコードする必要はありません。これらは SDK により実装されます。
C # UploadCallbackSample.cs using を使用して to read、 および PutObjectResult.ResponseStream を読み取りますが、using が無効になっていることを確認します。
JS object.test.js -
C oss_callback_sample.c -
Ruby callback.rb -
iOS

アップロード後のコールバック通知

<var1> (var1の形式) は x:var1です。
Andriod

Callback notification after upload

CallbackBody 内のエスケープ文字に注意してください。
Go SDK は現在アップロードコールバックをサポートしていません。

PostObject の使用例

PostObject はアップロードコールバックをサポートします。そのコールバックパラメーターはフォームフィールド callback により伝送され、カスタム変数は独立したフォームフィールドによって伝送されます。 詳しくは、「PostObject」をご参照ください。

PostObject の使用例を次のテーブルに示します。

SDK アップロードコールバックの例
Java PostObjectSample.java
Python object_post.py
C# PostPolicySample.cs

コールバックサーバー

コールバックサーバーは、OSS から送信されたコールバック要求と POST メッセージを処理する HTTP サーバーです。 コールバックサーバーの URL は、アップロードコールバックパラメーター callbackUrl の値です。 アップロードしたデータの記録、レビュー、処理、および統計のために、コールバックサーバーに独自の処理ロジックを実装できます。

コールバック署名

コールバックサーバーは、POST 要求が OSS アップロードコールバックからのものであることを確認するため、POST 要求の署名を検証する必要があります。 コールバックサーバーは、署名を検証せずにメッセージを直接処理することもできます。 コールバックサーバーのセキュリティを強化するため、コールバックサーバーにメッセージの署名を検証させることを推奨します。 コールバック署名規則の詳細については、「Callback」をご参照ください。

OSS コールバックサーバーの例では、署名検証を実装する方法について説明します。 コードを直接使用することを推奨します。
メッセージ処理

コールバックサーバーの主なロジックは、OSS コールバック要求を処理することです。 次の点に注意してください。

  • コールバックサーバーは OSS の POST 要求を処理する必要があります。
  • OSS コールバックのタイムアウト時間は 5 秒です。 したがって、コールバックサーバーは 5 秒以内に処理を完了し、結果を返さなければなりません。
  • コールバックサーバーから OSS に送信されるメッセージ本文は JSON 形式である必要があります。
  • コールバックサーバーは独自のロジックを使用しています。OSS は特定のサービスロジックの代わりに実例を提供します。
実装例

次のテーブルは、コールバックサーバーの実装例を示しています。

言語 実行方法
JAVA AppCallbackServer.zip パッケージを解凍し、java -jar oss-callback-server-demo.jar 9000 を実行します。
PHP callback-php-demo.zip プログラムを Apache 環境に展開し、実行します。
Python callback_app_server.py.zip Python callback_app_server.py.zip パッケージを解凍し、python callback_app_server.py を実行します。
Ruby oss-callback-server ruby​​ aliyun_oss_callback_server.rb を実行します。

デバッグ手順

アップロードコールバックのデバッグには、ファイルをアップロードするクライアントのデバッグ、およびコールバックを処理するコールバックサーバーのデバッグが含まれます。 最初にクライアントをデバッグしてからコールバックサーバーをデバッグすることを推奨します。 2 つのパーツを個別にデバッグした後、全体のアップロードコールバックを実行します。

  • クライアントのデバッグ

    クライアントをデバッグするには、OSS によって提供されるコールバックサーバー http://oss-demo.aliyuncs.com:23450 を使用します。これは、クライアントをデバッグするためのコールバックパラメーター callbackUrl です。コールバックサーバーはコールバック要求の署名だけを検証し、コールバック要求は処理しません。署名の検証に成功したコールバック要求の場合、コールバックサーバーは {"Status":"OK"} を返します。 署名の検証に失敗したコールバック要求の場合、コールバックサーバーは 400 Bad Request を返します。 非 POST 要求の場合、コールバックサーバーは 501 Unsupported method を返します。コールバックサーバーのコードの詳細については、「callback_app_server.py.zip」をご参照ください。

  • コールバックサーバーのデバッグ

    コールバックサーバーは POST 要求を処理できる HTTP サーバーです。 OSS によって提供される例に基づいてコールバックサーバーを修正するか、または自分で実装することができます。 次のテーブルで、OSS によって提供されるコールバックサーバーの例を示します。

    言語 実行方法
    JAVA AppCallbackServer.zip パッケージを解凍し、java -jar oss-callback-server-demo.jar 9000 を実行します。
    PHP callback-php-demo.zip Apache 環境にプログラムを展開して実行します。
    Python callback_app_server.py.zip パッケージを解凍し、python callback_app_server.py を実行します。
    C# callback-server-dotnet.zip プログラムをコンパイルし、aliyun-oss-net-callback-server.exe 127.0.0.1 80 を実行します。
    Go callback-server-go.zip プログラムをコンパイルし、 aliyun_oss_callback_server を実行します。
    Ruby oss-callback-server ruby aliyun_oss_callback_server.rb を実行します。

    コールバックサーバーは、cURL コマンドを実行することでデバッグできます。 以下は実際に使用される可能性のある cURL コマンド文です。

    # Run the following command to send a `POST` request whose message body is `object=test_obj` to the callback server:  
    curl -d "object=test_obj" http://oss-demo.aliyuncs.com:23450 -v
    # Run the following command to send a `POST` request whose message body is `post.txt` to the callback server:  
    curl -d @post.txt http://oss-demo.aliyuncs.com:23450 -v
    # Run the following command to send a `POST` request whose message body is `post.txt` and which carries the specified message header `Content-Type` to the callback server: 
    curl -d @post.txt -H "Content-Type: application/json" http://oss-demo.aliyuncs.com:23450 -v
    • コールバックサーバーをデバッグするときは、cURL は署名関数をシミュレートするのが難しいため、署名の検証を無視します。
    • OSS の例では、署名検証関数を提供しています。 直接使用することを推奨します。
    • デバッグと追跡を容易にするため、コールバックサーバーにすべてのメッセージを記録するログ機能を実装することを推奨します。
    • コールバック要求を正しく処理した後、コールバックサーバーは 20x ではなく 200 を返す必要があります。
    • コールバックサーバーから OSS に送信されるメッセージ本文はJSON 形式である必要があり、 Content-Typeapplication/json に設定されています。

一般的なエラーと原因

  • 無効な引数
    <Error>
      <Code>InvalidParameter</Code>
      <Message>The callback configuration is not json format.</Message>
      <RequestId>587C79A3DD373E2676F73ECE</RequestId>
      <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      <ArgumentName>callback</ArgumentName>
      <ArgumentValue>{"callbackUrl":"8.8.8.8:9090","callbackBody":"{"bucket":${bucket},"object":${object}}","callbackBodyType":"application/json"}</ArgumentValue>
    </Error> 
    コールバックパラメーターの設定が正しくないか、パラメーターの形式が正しくありません。一般的なエラーは、ArgumentValue のコールバックパラメーターが有効な JSON 形式ではないことが原因です。JSON では、\" はエスケープ文字です。 例えば、 "callbackBody":"{"bucket":${bucket},"object":${object}}" は、"callbackBody":"{\"bucket\":${bucket},\"object\":${object}}" とする必要があります。SDK の詳細については、「SDK 使用例」のアップロードコールバックの例をご参照ください。
    エスケープ後の文字 エスケープ前の文字
    \\ \\\\
    \\\”
    \b \\b
    \f \\f
    \n \\n
    \r \\r
    \t \\t
  • CallbackFailed
    • 例 1
      <Error> 
        <Code>CallbackFailed</Code>
        <Message>Response body is not valid json format.</Message>
        <RequestId>587C81A125F797621829923D</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      コールバックサーバーから OSS に送信されたメッセージ本文は JSON 形式ではありません。内容を確認するには、curl -d "<Content>" <CallbackServerURL> -v を実行するか、またはパケットのキャプチャを実行します。Windows でパケットをキャプチャするには、Wireshark を使用することを推奨します。Linux でパケットをキャプチャするには、tcpdump を使用することを推奨します。無効な応答メッセージには、OK および \357\273\277{"Status":"OK"} (ef bb bfバイトを含む BOM ヘッダー) が含まれます。
    • 例 2
      <Error> 
        <Code>CallbackFailed</Code>
        <Message>Error status : -1. OSS can not connect to your callbackUrl, please check it.</Message> 
        <RequestId>587C8735355BE8694A8E9100</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error> 
      コールバックサーバーの処理時間が 5 秒を超過しています。 したがって、OSS はタイムアウトが発生したと判断します。5 秒以内に処理を完了し、結果を OSS に返すことができるように、コールバックサーバーの処理ロジックを非同期処理に変更することを推奨します。
    • 例 3
      <Error>
        <Code>CallbackFailed</Code>
        <Message> error status:-1 8.8.8.8: 9090 reply timeout, cost: 5000 MS, timeout: 5000 MS (Ernest-4, errno170) </message>
        <RequestId>587C8D382AE0B92FA3EEF62C</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error> 
      コールバックサーバーの処理時間が 5 秒を超過しています。 したがって、OSS はタイムアウトが発生したと判断します。
    • 例 4
      <Error> 
        <Code>CallbackFailed</Code>
        <Message>Error status : 400.</Message>
        <RequestId>587C89A02AE0B92FA3C7981D</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error> 
      コールバックサーバーから OSS に送信されるメッセージの状態コードは "400" です。 コールバックサーバーの処理ロジックを確認します。
    • 例 5
      <Error>
        <Code>CallbackFailed</Code>
        <Message>Error status : 502.</Message>
        <RequestId>587C8D382AE0B92FA3EEF62C</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error> 
      コールバックサーバーが起動していないか、CallbackUrl がコールバックパラメーターにないか、または OSS インスタンスとコールバックサーバー間のネットワークが切断されています。トラフィックコストを節約し、ネットワーク品質を保証するため、コールバックサーバーを OSS と同じイントラネットに属する ECS に配置することを推奨します。

共通リンク