Callback - Object Storage Service

OSS支援在檔案上傳後自動觸發回調，通知應用伺服器執行後續操作。

使用限制

地區限制
華東1（杭州）、華東2（上海）、華北1（青島）、華北2（北京）、華北 3（張家口）、華北5（呼和浩特）、華北6（烏蘭察布）、華南1（深圳）、華南2（河源）、華南3（廣州）、西南1（成都）、中國香港、美國（矽谷）、美國（維吉尼亞）、日本（東京）、新加坡、馬來西亞（吉隆坡）、印尼（雅加達）、菲律賓（馬尼拉）、德國（法蘭克福）、英國（倫敦）、阿聯酋（杜拜）地區支援設定Callback。
回調行為說明
- 回調請求必須在5秒內響應，逾時將視為失敗。
- 回調失敗不影響檔案上傳成功。
- 回調失敗不會自動重試。
介面支援
PutObject、PostObject、CompleteMultipartUpload介面支援設定 Callback。V2 SDK 基於以上基礎介面封裝的檔案上傳管理器、預簽名 URL 也支援設定 Callback。

回調流程概覽

OSS 回調具體步驟如下：

用戶端上傳檔案（附帶回調參數）
上傳檔案時，用戶端需要攜帶 Callback 參數，指定回調伺服器的地址和回調內容。若需要傳遞自訂變數，還可以選擇附加callback-var參數。
OSS 隱藏檔並發送回調請求
檔案上傳成功後，OSS 以 POST 方式向回調 URL 發送請求，包含檔案資訊（如 bucket、object、size、ETag等）及自訂參數。
伺服器處理回調並返迴響應
伺服器接收回調請求後，驗證請求籤名（可選）以確保安全，5 秒內完成處理並返回 JSON 響應。HTTP 狀態代碼 200 表示成功，非 200 視為回調失敗。
OSS 返回上傳結果
在回調響應成功後，OSS會根據應用伺服器的返回結果向用戶端提供最終處理結果。

開發實現指南

上傳回調的調試包含兩部分：用戶端上傳和服務端回調處理。建議先調試用戶端上傳部分，再調試應用伺服器部分，兩部分均調試完成後，再進行完整的聯調驗證。

用戶端實現

以下內容主要說明上傳回調參數的構造邏輯與處理流程。如需快速實現上傳回調功能，建議參考SDK提供的範例程式碼。

為了讓 OSS 在檔案上傳完成後自動觸發回調，您需要通過上傳請求傳入兩個參數：callback和（可選的）callback-var。

構造callback參數。
該參數用於定義應用伺服器位址、請求內容格式等資訊，必須以 JSON 格式構造並進行 Base 64 編碼。
1. 最簡配置樣本：
```
{
"callbackUrl":"http://oss-demo.aliyuncs.com:23450",
"callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}"
}
```
  在該樣本中：
  - callbackUrl：應用伺服器位址，需根據實際地址修改。此處以http://oss-demo.aliyuncs.com:23450為例。
  - callbackBody：回調請求體的內容。您可以使用預留位置動態傳入上傳資訊，例如${bucket}表示Bucket名稱、${object}表示檔案完整路徑，還可以使用${x:xxx}引用自訂變數。OSS 會在回調時將這些預留位置替換為實際值。更多可傳入的資訊請參見callbackBody支援的系統參數。
2. 進階配置樣本：
```
{
"callbackUrl":"http://oss-demo.aliyuncs.com:23450",
"callbackHost":"oss-cn-hangzhou.aliyuncs.com",
"callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}",
"callbackBodyType":"application/x-www-form-urlencoded",
"callbackSNI":false
}
```
  詳細欄位說明請參見：callback參數詳情。
構造callback-var參數（可選）
重要
callback-var參數必須符合 JSON 格式。其中，每個自訂參數的 key 必須以 x: 開頭且僅能使用小寫字母，例如x:uid。
該參數用於嚮應用伺服器傳遞自訂商務資訊，例如使用者識別碼、訂單號等。例如：
```
{
  "x:uid": "12345",
  "x:order_id": "67890"
}
```
callback-var必須與 callbackBody 配合使用。對於上述樣本中的自訂參數使用者id（uid）和訂單號（order_id），在callbackBody中需要通過預留位置${x:xxx} 來引用。例如：
```
{
  "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
  "callbackBody": "uid=${x:uid}&order=${x:order_id}"
}
```
實際回調時，OSS會發送以下內容（假設callbackBodyType為 application/x-www-form-urlencoded）：
```
uid=12345&order=67890
```

在構造好callback 和callback-var參數後，您需要將它們進行Base64編碼。

樣本：callback參數編碼

原始callback參數

{
    "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
    "callbackHost": "your.callback.com",
    "callbackBody": "bucket=${bucket}&object=${object}&uid=${x:uid}&order=${x:order_id}",
    "callbackBodyType": "application/x-www-form-urlencoded",
    "callbackSNI": false
}

Base64編碼後的結果：

eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

樣本：callback-var參數編碼

原始callback-var參數：

{
  "x:uid": "12345",
  "x:order_id": "67890"
}

Base64編碼後的結果：

eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=

將編碼後的參數附加到請求中。

完成編碼後，您可以通過以下方式將編碼後的參數傳遞給OSS。

在Header中攜帶參數（推薦）

適用於通過SDK或後端代碼上傳對象的情境，安全性高，推薦優先使用。您可通過設定HTTP頭部欄位x-oss-callback和x-oss-callback-var來傳遞迴調參數：

x-oss-callback：Base 64 編碼後的 callback 參數
x-oss-callback-var（可選）：Base 64 編碼後的 callback-var 參數

注意：計算請求籤名時，這兩個參數必須包含在Canonical Headers中，以確保請求合法。

樣本：通過 Header 傳遞迴調參數

PUT /your_object HTTP/1.1
Host: callback-test.oss-test.aliyun-inc.com
Accept-Encoding: identity
Content-Length: 5
x-oss-callback-var: eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=
User-Agent: aliyun-sdk-python/0.4.0 (Linux/2.6.32-220.23.2.ali1089.el5.x86_64/x86_64;2.5.4)
x-oss-callback: eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9
Host: callback-test.oss-test.aliyun-inc.com
Expect: 100-Continue
Date: Wed, 26 Apr 2023 03:46:17 GMT
Content-Type: text/plain
Authorization: OSS qn6q**************:77Dv****************
Test

在POST請求的Body中使用表單域來攜帶參數

僅適用於PostObject介面上傳，回調參數只能通過 POST 請求的 Body 中的表單域傳遞。

callback參數：需作為獨立表單項傳入，值為Base64編碼後的JSON配置。

--9431149156168
Content-Disposition: form-data; name="callback"
eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

callback-var參數（自訂參數）：每個自訂欄位必須作為獨立表單項傳入，不能封裝成一個整體的callback-var欄位。
例如，對於自訂參數uid和order_id：
```
{
  "x:uid": "12345",
  "x:order_id": "67890"
}
```
應轉換為表單中的兩個獨立欄位。
```
--9431149156168
Content-Disposition: form-data; name="x:uid"
12345
--9431149156168
Content-Disposition: form-data; name="x:order_id"
67890
```

驗證callback參數（可選）：您可以在 policy 中指定 callback 參數的校正條件。如果未設定，則上傳時不會校正該參數。例如：

{ "expiration": "2021-12-01T12:00:00.000Z",
  "conditions": [
    {"bucket": "examplebucket" },
    {"callback": "eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9"},
    ["starts-with", "$key", "user/eric/"]
  ]
}

在URL中攜帶參數

該方式常用於預簽名URL上傳檔案的情境，通過將回調參數 Base 64 編碼後拼接在 URL 中實現自動回調。但由於回調資訊暴露在 URL 中，存在一定的安全風險，僅建議用於臨時訪問或低敏感情境。

如果您選擇通過 URL 攜帶回調參數，則必須包含callback參數，callback-var參數為可選。簽名計算時，這些參數需作為Canonical Query String的一部分參與計算。更多資訊，請參見簽名版本4。

樣本：

PUT /your_object?OSSAccessKeyId=LTAI******************&Signature=vjby*************************************&Expires=1682484377&callback-var=eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=&callback=eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9 HTTP/1.1
Host: callback-test.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 26 Apr 2023 03:46:17 GMT
Content-Length: 5
Content-Type: text/plain

服務端實現

以下為服務端的處理流程。各語言的程式碼範例請參見服務端程式碼範例。

應用伺服器需要具備以下能力：

接收OSS發送的POST請求

當檔案上傳成功後，OSS 會根據回調參數，自動向您配置的應用伺服器發送一個POST請求。樣本如下：

POST /test HTTP/1.1
Host: your.callback.com
Connection: close
Authorization: GevnM3**********3j7AKluzWnubHSVWI4dY3VsIfUHYWnyw==
Content-MD5: iKU/O/JB***ZMd8Ftg==
Content-Type: application/x-www-form-urlencoded
Date: Tue, 07 May 2024 03:06:13 GMT
User-Agent: aliyun-oss-callback
x-oss-bucket: your_bucket
x-oss-pub-key-url: aHR0cHM6Ly9nb3NzcHVi**********vY2FsbGJeV92MS5wZW0=
x-oss-request-id: 66399AA50*****3334673EC2
x-oss-requester: 23313******948342006
x-oss-signature-version: 1.0
x-oss-tag: CALLBACK
bucket=your_bucket&object=your_object&uid=12345&order_id=67890

驗證請求籤名確保安全（可選）
為確保回調請求來自 OSS，建議在應用伺服器中對請求籤名進行驗證。具體驗證方法，請參見建議配置。
說明
簽名驗證不是必選項，您可按需決定是否啟用。
返回回調響應
應用伺服器收到回調請求後，需要向OSS返迴響應。回調響應必須符合以下要求：
- 正常情況下，應用伺服器應返回 HTTP/1.1 200 OK。
- 回應標頭中必須包含Content-Length。
- 響應體格式支援JSON或XML，此處以 JSON 為例。如果您希望使用XML作為響應體格式，在回應標頭中添加Content-Type: application/xml即可。
例如，此處應用伺服器返回了{"Status": "OK"}
注意：本樣本中的Python版本為2.7.6，實際開發建議使用Python 3。
```
HTTP/1.0 200 OK
Server: BaseHTTP/0.3 Python/2.7.6
Date: Mon, 14 Sep 2015 12:37:27 GMT
Content-Type: application/json
Content-Length: 9
{"Status": "OK"}
```
之後OSS會將該響應內容透傳給用戶端。樣本如下：
```
HTTP/1.1 200 OK
Date: Mon, 14 Sep 2015 12:37:27 GMT
Content-Type: application/json
Content-Length: 9
Connection: keep-alive
ETag: "D8E8FCA2DC0F896FD7CB4CB0031BA249"
Server: AliyunOSS
x-oss-bucket-version: 1442231779
x-oss-request-id: 55F6BF87207FB30F2640C548
{"Status": "OK"}
```
重要
對於CompleteMultipartUpload請求，如果原本的響應body中存在內容（例如JSON格式的資訊），啟用上傳回調後，該內容會被回調返回的覆蓋，例如此處被{"Status": "OK"}覆蓋。

建議配置

驗證請求籤名確保安全

在設定回調參數後，OSS會根據您配置的callbackUrl發送POST回調請求到應用伺服器。為確保請求來自OSS，您可以對回調請求中的簽名進行驗證。以下是驗證過程的詳細步驟。

用戶端產生簽名（由OSS完成）
OSS 使用 RSA 非對稱式加密演算法，結合 MD5 雜湊，對請求內容產生簽名，並將簽名添加到要求標頭的 authorization 欄位中。
- 簽名計算方式如下：
```
authorization = base64_encode(rsa_sign(private_key, url_decode(path) + query_string + '\n' + body, md5))
```
  說明
  其中，private_key為私密金鑰，path為回調請求的資源路徑，query_string為查詢字串，body為回調的訊息體。
- 產生簽名的步驟：
  1. 擷取待簽名字串：資源路徑經過URL解碼後，會附加原始的查詢字串、一個斷行符號符以及回調訊息體。
  2. RSA簽名：使用金鑰組待簽名字串進行簽名，簽名的雜湊函數為md5。
  3. 將簽名後的結果做Base64編碼，擷取最終的簽名，然後將簽名放在回調請求的authorization頭中。
- 產生簽名的樣本：
```
POST /index.php?id=1&index=2 HTTP/1.0
Host: 172.16.XX.XX
Connection: close
Content-Length: 18
authorization: kKQeGTRccDKyHB3H9vF+xYMSrmhMZj****/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****
Content-Type: application/x-www-form-urlencoded
User-Agent: http-client/0.0.1
x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnsr****
bucket=examplebucket
```
  path為/index.php，query_string為?id=1&index=2，body為bucket=examplebucket，最終簽名結果為kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****。
回調伺服器驗證簽名
您的應用伺服器需對OSS請求進行簽名驗證，以確認請求來源的合法性。驗證步驟如下：
1. 擷取公開金鑰：
  從要求標頭的 x-oss-pub-key-url 欄位擷取 Base 64 編碼的公開金鑰 URL，並進行解碼。
```
public_key = urlopen(base64_decode(x-oss-pub-key-url頭的值))
```
  解碼前的樣本值：
```
aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ==
```
  解碼後：
```
http://gosspublic.alicdn.com/callback_pub_key_v1.pem
```
  說明
  公開金鑰URL必須以http://gosspublic.alicdn.com/或者https://gosspublic.alicdn.com/開頭。由於公開金鑰地址的內容不變，建議緩衝公開金鑰以避免因網路波動影響服務。
2. 解碼簽名。
  從要求標頭的 authorization 欄位擷取簽名，並進行 Base64 解碼：
```
signature = base64_decode(authorization頭的值)
```
3. 構造待驗證字串。
  將資源路徑、查詢字串、分行符號和回調訊息體按如下格式拼接：
```
sign_str = url_decode(path) + query_string + ‘\n’ + body
```
4. 執行簽名驗證。
  使用 MD5 雜湊加 RSA 公開金鑰進行驗證：
```
result = rsa_verify(public_key, md5(sign_str), signature)
```

驗證簽名樣本

以Python 3為例，示範應用伺服器中驗證簽名的方法，此樣本需要安裝M2Crypto庫。

import http.client
import base64
import hashlib
import urllib.request
import urllib.parse
import socket
from http.server import BaseHTTPRequestHandler, HTTPServer
from M2Crypto import RSA
from M2Crypto import BIO
def get_local_ip():
    try:
        csock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
        csock.connect(('8.8.8.8', 80))
        (addr, port) = csock.getsockname()
        csock.close()
        return addr
    except socket.error:
        return ""
class MyHTTPRequestHandler(BaseHTTPRequestHandler):
    '''
    def log_message(self, format, *args):
        return
    '''
    def do_POST(self):
        #get public key
        pub_key_url = ''
        try:
            pub_key_url_base64 = self.headers['x-oss-pub-key-url']
            pub_key_url = base64.b64decode(pub_key_url_base64).decode()
            if not pub_key_url.startswith("http://gosspublic.alicdn.com/") and not pub_key_url.startswith("https://gosspublic.alicdn.com/"):
                self.send_response(400)
                self.end_headers()
                return
            url_reader = urllib.request.urlopen(pub_key_url)
            #you can cache it,recommend caching public key content based on the public key address
            pub_key = url_reader.read() 
        except Exception as e:
            print('pub_key_url : ' + pub_key_url)
            print('Get pub key failed! Error:', str(e))
            self.send_response(400)
            self.end_headers()
            return
        #get authorization
        authorization_base64 = self.headers['authorization']
        authorization = base64.b64decode(authorization_base64)
        #get callback body
        content_length = self.headers['content-length']
        callback_body = self.rfile.read(int(content_length))
        #compose authorization string
        auth_str = ''
        pos = self.path.find('?')
        if -1 == pos:
            auth_str = urllib.parse.unquote(self.path) + '\n' + callback_body.decode()
        else:
            auth_str = urllib.parse.unquote(self.path[0:pos]) + self.path[pos:] + '\n' + callback_body.decode()
        print(auth_str)
        #verify authorization
        auth_md5 = hashlib.md5(auth_str.encode()).digest()
        bio = BIO.MemoryBuffer(pub_key)
        rsa_pub = RSA.load_pub_key_bio(bio)
        try:
            result = rsa_pub.verify(auth_md5, authorization, 'md5')
        except:
            result = False
        if not result:
            print('Authorization verify failed!')
            print('Public key : %s' % (pub_key))
            print('Auth string : %s' % (auth_str))
            self.send_response(400)
            self.end_headers()
            return
        #do something according to callback_body
        #response to OSS
        resp_body = '{"Status":"OK"}'
        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.send_header('Content-Length', str(len(resp_body)))
        self.end_headers()
        self.wfile.write(resp_body.encode())
class MyHTTPServer(HTTPServer):
    def __init__(self, host, port):
        super().__init__((host, port), MyHTTPRequestHandler)
if __name__ == '__main__':
    server_ip = get_local_ip()
    server_port = 23451
    server = MyHTTPServer(server_ip, server_port)
    server.serve_forever()

其他語言的服務端代碼請參見下表。

SDK語言	描述
Java	下載地址：Java 運行方法：解壓包運行`java -jar oss-callback-server-demo.jar 9000`（9000指啟動並執行連接埠，可以自行指定）。
Python	下載地址：Python 運行方法：解壓包直接運行`python callback_app_server.py`，運行該程式需要安裝RSA的依賴。
PHP	下載地址：PHP 運行方法：部署到Apache環境下，因為PHP本身語言的特點，取一些資料頭部會依賴於環境。所以可以參考例子根據所在環境修改。
.NET	下載地址：.NET 運行方法：解壓後參看`README.md`。
Node.js	下載地址：Node.js 運行方法：解壓包直接運行`node example.js`。
Ruby	下載地址：Ruby 運行方法：ruby aliyun_oss_callback_server.rb

callback參數詳情

以下是callback參數的詳細說明，用於配置OSS檔案上傳成功後的回調請求內容與行為。

欄位	是否必選	描述
callbackUrl	是	檔案上傳成功後，OSS向此URL發送POST回調請求。支援同時配置最多5個URL，多個URL間以分號（;）分隔。OSS會依次發送請求，直到第一個回調請求成功返回。支援HTTPS協議地址。不支援填寫IPV6地址，也不支援填寫指向IPV6地址的網域名稱。為了保證正確處理中文等情況，callbackUrl需做URL編碼處理，例如`https://example.com/中文.php?key=value&中文名稱=中文值`需要編碼為`https://example.com/%E4%B8%AD%E6%96%87.php?key=value&%E4%B8%AD%E6%96%87%E5%90%8D%E7%A7%B0=%E4%B8%AD%E6%96%87%E5%80%BC`。
callbackBody	是	發起回調時請求體的內容，格式需與 callbackType 參數保持一致：當 callbackType 為預設值`application/x-www-form-urlencoded`時，callbackBody 應為索引值對格式，例如：`bucket=${bucket}&object=${object}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}` 當 callbackType 為`application/json`時，callbackBody 應為 JSON格式，例如：`{\"bucket\":${bucket},\"object\":${object},\"mimeType\":${mimeType},\"size\":${size},\"my_var1\":${x:my_var1},\"my_var2\":${x:my_var2}}` callbackBody 支援引用 OSS 系統參數、自訂變數和常量。系統參數說明請參見callbackBody支援的系統參數。
callbackHost	否	發起回調請求時Host頭的值，格式為網域名稱或IP地址。如果沒有配置callbackHost，則解析callbackUrl中的URL，並將解析的Host填充到callbackHost中。
callbackSNI	否	是否在回調請求中攜帶 SNI（用 HTTPS請求中標識網域名稱並返回正確認證）。當 callbackUrl 使用 HTTPS 時，建議開啟該參數，否則可能因認證不匹配導致回調失敗（如 502 callback failed）。取值如下： true：發送SNI。 false（預設值）：不發送SNI。說明英國（倫敦）地區始終發送SNI，不受此參數控制。
callbackBodyType	否	發起回調請求的Content-Type，即`callbackBody`的資料格式。支援以下兩種類型： application/x-www-form-urlencoded（預設值）將經過URL編碼的值替換callbackBody中的變數。 application/json 按照JSON格式替換callbackBody中的變數。

callbackBody支援的系統參數

callback參數中callbackBody欄位支援引用多個系統參數，用於在回調請求中傳遞上傳檔案的相關資訊。支援的系統參數如下表所示：

系統參數	含義
bucket	儲存空間名稱。
object	對象（檔案）的完整路徑。
etag	檔案的ETag，即返回給使用者的ETag欄位。
size	Object大小。調用CompleteMultipartUpload時，size為整個Object的大小。
mimeType	資源類型，例如jpeg圖片的資源類型為image/jpeg。
imageInfo.height	圖片高度。該變數僅適用於圖片格式，對於非圖片格式，該變數的值為空白。
imageInfo.width	圖片寬度。該變數僅適用於圖片格式，對於非圖片格式，該變數的值為空白。
imageInfo.format	圖片格式，例如JPG、PNG等。該變數僅適用於圖片格式，對於非圖片格式，該變數的值為空白。
crc64	與上傳檔案後返回的x-oss-hash-crc64ecma頭內容一致。
contentMd5	與上傳檔案後返回的Content-MD5頭內容一致。重要僅在調用PutObject和PostObject介面上傳檔案時，該變數的值不為空白。
vpcId	發起請求的用戶端所在的VpcId。如果不是通過VPC發起請求，則該變數的值為空白。
clientIp	發起請求的用戶端IP地址。
reqId	發起請求的RequestId。
operation	發起請求的介面名稱，例如PutObject、PostObject等。

SDK

以下為用戶端實現的樣本demo。

	簡單上傳（使用PutObject介面）	分區上傳（使用CompleteMultipartUpload介面）	使用預簽名URL上傳（使用PutObject介面）
Java	demo	demo	demo
Python V2	demo	-	demo
Go V2	demo	demo	demo

錯誤排查

OSS返回的錯誤資訊中包含EC錯誤碼，使用Callback過程若出現錯誤，您可以使用EC碼進行排查。EC碼與錯誤原因一一對應。與Callback相關的EC錯誤碼，請參見07-CALLBACK。

常見問題

OSS上傳檔案失敗後是否會發送回調通知給應用伺服器？

不會。OSS上傳檔案成功後會執行回調，如果上傳失敗，則不執行回調，直接返回錯誤資訊。

報錯Response body is not valid json format.如何處理？

應用伺服器處理過程中拋出異常，導致返回給OSS的Body不是JSON格式，如以下代碼所示：
```
#response to OSS
resp_body = '{"Status":"OK"}'
self.send_response(200)
self.send_header('Content-Type', 'application/json')
self.send_header('Content-Length', str(len(resp_body)))
self.end_headers()
self.wfile.write(resp_body)
```
解決方案：
- 通過以下命令確認內容。
```
curl -d "<Content>" <CallbackServerURL> -v
```
- 通過抓包確認內容。
  Windows下推薦使用工具Wireshark抓包，Linux下使用命令tcpdump抓包。

應用伺服器返回給OSS的Body中帶有BOM頭。

這類錯誤常見於使用PHP SDK編寫的應用伺服器中。由於PHP SDK返回了BOM頭，導致OSS收到的Body中多了三個位元組，出現不符合JSON格式的Body。如以下報文所示，ef bb bf這三個位元組為BOM頭。

Frame 6: 448 bytes on wire (3584 bits), 448 bytes captured (3584 bits)
Ethernet II, Src: Inventec_5e:4f:5c (00:8c:fa:5e:4f:5c), Dst: Inventec_5e:4b:64 (00:8c:fa:5e:4b:64)
Internet Protocol Version 4, Src: 10.101.166.30, Dst: 10.101.166.53
Transmission Control Protocol, Src Port: 8083 (8083), Dst Port: 49607 (49607), Seq: 1, Ack: 518, Len: 382
Hypertext Transfer Protocol
Line-based text data: text/html
  \357\273\277{"Status":"Ok"}
0090  64 20 48 61 74 29 0d 0a  53 65 74 2d 43 6f 6f 6b   d Hat).. Set-Cook
00a0  69 65 3a 20 50 48 50 53  45 53 53 49 44 3d 66 61   ie: PHPS ESSID=fa
00b0  74 37 33 6e 74 6c 70 68  30 6e 63 67 38 68 33 30   t73ntlph 0ncg8h30
00c0  65 6e 75 35 31 34 67 31  3b 20 48 74 74 70 4f 6e   enu514g1 ; HttpOn
00d0  6c 79 0d 0a 45 78 70 69  72 65 73 3a 20 54 68 75   ly..Expi res: Thu
00e0  2c 20 31 39 20 4e 6f 76  20 31 39 38 31 20 30 38   , 19 Nov  1981 08
00f0  3a 35 32 3a 30 30 20 47  4d 54 0d 0a 43 61 63 68   :52:00 G MT..Cach
0100  65 2d 43 6f 6e 74 72 6f  6c 3a 20 6e 6f 2d 73 74   e-Contro l: no-st
0110  6f 72 65 2c 20 6e 6f 2d  63 61 63 68 65 2c 20 6d   ore, no- cache, m
0120  75 73 74 2d 72 65 76 61  6c 69 64 61 74 65 2c 20   ust-reva lidate,
0130  70 6f 73 74 2d 63 68 65  63 6b 3d 30 2c 20 70 72   post-che ck=0, pr
0140  65 2d 63 68 65 63 6b 3d  30 0d 0a 50 72 61 67 6d   e-check= 0..Pragm
0150  61 3a 20 6e 6f 2d 63 61  63 68 65 0d 0a 43 6f 6e   a: no-ca che..Con
0160  74 65 6e 74 2d 4c 65 6e  67 74 68 3a 20 31 38 0d   tent-Len gth: 18.
0170  0a 43 6f 6e 6e 65 63 74  69 6f 6e 3a 20 63 6c 6f   .Connect ion: clo
0180  73 65 0d 0a 43 6f 6e 74  65 6e 74 2d 54 79 70 65   se..Cont ent-Type
0190  3a 20 74 65 78 74 2f 68  74 6d 6c 3b 20 63 68 61   : text/h tml; cha
01a0  72 73 65 74 3d 55 54 46  2d 38 0d 0a 0d 0a ef bb   rset=UTF -8.....
01b0  bf 7b 22 53 74 61 74 75  73 22 3a 22 4f 6b 22 7d   .{"Statu s":"Ok"}

解決方案：刪除應用伺服器返回OSS Body中的BOM頭。