關于上傳回調

OSS在文件上傳完成時可以提供回調（Callback）給用戶的回調服務器（Callback Server）。在上傳請求中攜帶相應的回調參數，即能實現上傳回調。支持上傳回調的 API 接口有：PutObject、PostObject、CompleteMultipartUpload。更詳細的介紹請參見開發指南中的上傳回調和Callback API。

應用場景

• 通知

  上傳回調的一種典型應用是授權的第三方上傳文件時指定回調參數。上傳完成后OSS向回調服務器發送回調請求。回調服務器收到回調請求后，記錄上傳信息。

• 處理、審查、統計等

  回調服務器收到回調請求后，對上傳的文件做處理、審查、統計等。

數據流

OSS上傳回調流程如下圖：

OSS上傳回調流程解釋如下：

SDK/PostObject

上傳時可以通過設置回調參數，指定回調服務器URL、發送給回調服務器的數據、格式等。回調服務器處理回調時，需要一些上下文信息，如bucket、object等，通過系統變量指定；系統變量以外的上下文信息，通過自定義變量指定。

上傳回調包括以下參數：

通過上傳請求攜帶上傳回調參數有兩種實現方式：

• 通過消息頭中的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\":${bucket}, \"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示例中的 callbackBody 包括如${bucket}、${object}、${size} 的變量，即為OSS定義的系統變量，OSS回調時會用實際值替換掉系統變量。OSS定義的系統變量如下表：

CallbackJson示例中的callbackBody 包括如${x:my_var}的變量，即自定義變量，OSS回調時會用自定義的值替換掉自定義變量。自定義變量的值可以在上傳請求中定義并攜帶，有以下兩種方式：

• 通過消息頭中的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"
}

SDK使用示例

部分SDK對上述步驟進行了封裝，如Java、JS，部分SDK需要使用上面的規則生成上傳回調參數和自定義變量，如Python、PHP、C。SDK的使用示例如下：

PostObject使用示例

PostObject支持上傳回調，回調參數通過表單域callback攜帶，自定義變量通過獨立的表單域攜帶，詳情請參見PostObjet。

PostObject的使用示例如下：

回調服務器

回調服務器（Callback Server），是一個HTTP服務器，處理OSS發送的回調請求，POST消息。回調服務器的URL即上傳回調參數中的callbackUrl。回調服務器是用戶自己實現的處理邏輯，實現上傳數據的記錄、審查、處理、統計等。

• 回調簽名

  回調服務器為了確認收到的POST請求來自于OSS的上傳回調，需要驗證該POST消息的簽名。回調服務器也可以不驗證簽名，直接處理該消息。為了提高回調服務器的安全性，建議驗證消息簽名。回調簽名規則請參見回調簽名。

  說明

  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。
  Ruby	oss-callback-server	執行ruby aliyun_oss_callback_server.rb。

調試步驟

上傳回調的調試分為兩部分：上傳的客戶端、處理回調的回調服務器。建議先調試客戶端上傳部分，再調試回調服務器部分。兩部分單獨調試完成后，再運行完整的上傳回調。

• 調試客戶端

  客戶端調試時，可使用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命令調試，下面幾個命令可能會用到：

  # 向回調服務器發送消息體為 `object=test_obj` 的 `POST` 請求，可以使用如下命令 
  curl -d "object=test_obj"  http://oss-demo.aliyuncs.com:23450 -v
  # 向回調服務器發送消息體為文件 `post.txt` 內容的 `POST` 請求，可以使用如下命令 
  curl -d @post.txt  http://oss-demo.aliyuncs.com:23450 -v
  #向回調服務器發送消息體為文件 `post.txt` 內容的 `POST` 請求，并攜帶指定的消息頭 `Content-Type`
  curl -d @post.txt -H "Content-Type: application/json" http://oss-demo.aliyuncs.com:23450 -v

  說明

  • 調試回調服務器時，可以先忽略簽名驗證部分，因為cURL模擬簽名功能比較困難。

  • 簽名驗證功能OSS示例中已經提供，建議直接使用。

  • 回調服務器建議有日志功能，記錄收到的所有消息，方便調試、跟蹤。

  • 回調服務器正確處理回調請求后，一定要返回200，而不是其它的20x。

  • 回調服務器返回給OSS的消息體，一定要是JSON格式，Content-Type設置為application/json。

常見錯誤及原因

• InvalidArgument

  <Error>
    <Code>InvalidArgument</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

  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:5000ms, timeout:5000ms (err -4, errno115)</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與回調服務器的網絡不通。推薦在ECS上部署回調服務器，與OSS同屬內網可以節省流量費用，同時保證網絡質量。

• 返回的Body非JSON格式

  示例如下：

  

  錯誤原因有以下兩種情況。

  • 應用服務器返回給OSS的Body不是JSON格式。如下圖所示：

    Resp_body不是合法的JSON格式，OSS就會報上述錯誤。這種一般比較明顯，還有比較隱蔽的。例如應用服務器處理過程中拋出異常，導致沒有按照預期返回給OSS，而是返回了一些棧信息等。

  • 應用服務器返回給OSS的Body中帶有bom頭。

    這類錯誤常見于用php編寫的應用服務器中。由于php返回了bom頭，導致OSS收到的Body中多了三個字節，不符合JSON格式，因此報上述錯誤。如果在應用服務器端抓包，可以看到以下信息。

    

    上圖中ef bb bf這三個字節就是bom頭。

    說明

    應用服務器返回OSS響應時，請去掉bom頭。

• 錯誤的status

  此類錯誤較多，例如502、400等。示例如下：

  
  說明

  • 400或者其他的status比如404/403等是指應用服務器返回給OSS的HTTP status是400或者404/403等，正常情況下應用服務器必須返回200給OSS。

  • 502是由于應用服務器根本就沒有開啟Web服務，沒有監聽OSS發過來的回調請求。

• 超時

  示例如下：

  
  說明

  出于安全考慮，OSS的回調請求只會等待5秒。如果5秒后還沒有返回，那么OSS就會主動斷開與應用服務器的連接，并返回給客戶端超時錯誤，錯誤信息中的IP可以忽略。