OSS在文件上传完成时可以提供回调（Callback）给用户的回调服务器（Callback Server）。在上传请求中携带相应的回调参数，即能实现上传回调。支持上传回调的 API 接口有：PutObject、PostObject、CompleteMultipartUpload。更详细的介绍请参见开发指南中的上传回调和Callback API。

回调服务器（Callback Server），有时也叫业务服务器。

通知

上传回调的一种典型应用是授权的第三方上传文件时指定回调参数。上传完成后OSS向回调服务器发送回调请求。回调服务器收到回调请求后，记录上传信息。

处理、审查、统计等

回调服务器收到回调请求后，对上传的文件做处理、审查、统计等。

OSS上传回调流程如下图：

OSS上传回调流程解释如下：

数据流

含义

说明

1

上传文件并携带回调参数。格式请参见PostObject。

通过SDK调用API接口（PutObject、CompleteMultipartUpload、PostObject）完成。

2

OSS存储文件后发起回调

OSS向上传请求中指定的CallbackUrl发起POST请求，回调超时时间是5秒。 超时时间为固定值，不支持配置。

回调请求POST的格式请参见发起回调请求。

3

回调服务器返回处理结果

回调服务器返回的消息体一定要是JSON格式。

OSS认为非200请求为回调失败。参数无效、回调失败返回40x；超时、无法连接返回50x。

4

OSS返回上传、回调结果

上传、回调都成功，返回200。

上传成功、回调失败返回203，ErrorCode为CallbackFailed，ErrorMessage描述错误原因。

上传时可以通过设置回调参数，指定回调服务器URL、发送给回调服务器的数据、格式等。回调服务器处理回调时，需要一些上下文信息，如bucket、object等，通过系统变量指定；系统变量以外的上下文信息，通过自定义变量指定。

上传回调包括以下参数：

字段

含义

说明

callbackUrl

回调服务器地址

必选参数

callbackHost

回调请求消息头中Host的值

可选参数，默认为callbackUrl

callbackBody

回调请求的消息体

必选参数，内容可以包括系统变量和自定义变量

callbackBodyType

回调请求消息头中Content-Type的值，即callbackBody的数据格式

可选参数，支持application/x-www-form-urlencoded和application/json，默认为前者

通过上传请求携带上传回调参数有两种实现方式：

通过消息头中的x-oss-callback，携带回调参数。这种方式比较常用，推荐该方式。

通过QueryString的callback，携带回调参数。

x-oss-callback或callback的值生成规则如下：

CallbackJson的值，示例如下：

或

CallbackJson示例中的 callbackBody 包括如${bucket}、${object}、${size} 的变量，即为OSS定义的系统变量，OSS回调时会用实际值替换掉系统变量。OSS定义的系统变量如下表：

变量

含义

${bucket}

存储空间名称

${object}

文件名称

${etag}

文件的ETag

${size}

文件大小

${mimeType}

文件类型，如image/jpeg等

${imageInfo.height}

图片高度

${imageInfo.width}

图片宽度

${imageInfo.format}

图片格式，如jpg、png等

系统变量大小写敏感。

系统变量的格式为 ${bucket}。

imageInfo针对于图片格式，非图片格式值为空。

CallbackJson示例中的callbackBody 包括如${x:my_var}的变量，即自定义变量，OSS回调时会用自定义的值替换掉自定义变量。自定义变量的值可以在上传请求中定义并携带，有以下两种方式：

通过消息头中的x-oss-callback-var，携带自定义变量。这种方式比较常用，也是推荐方式。

通过QueryString的callback-var，携带自定义变量。

x-oss-callback-var 或 callback-var 的生成规则如下：

CallbackVarJson 值的示例如下：

自定义变量必须以x：开头，大小写敏感，格式为${x:my_var}。

自定义变量的长度受消息头、URL的长度限制，建议自定义变量不超过10个，总长度不超过512Byte。

部分SDK对上述步骤进行了封装，如Java、JS，部分SDK需要使用上面的规则生成上传回调参数和自定义变量，如Python、PHP、C。SDK的使用示例如下：

SDK

上传回调示例

说明

Java

CallbackSample.java

注意CallbackBody中的转义字符。

Python

object_callback.py

-

PHP

Callback.php

上传的$options中OSS_CALLBACK和OSS_CALLBACK_VAR不需要base64，SDK会处理。

C#

UploadCallbackSample.cs

使用using读取 PutObjectResult.ResponseStream ，但要确保关闭PutObjectResult.ResponseStream。

JS

object.test.js

-

C

oss_callback_sample.c

-

Ruby

callback.rb

-

iOS

上传后回调通知

的格式为x:var1。

Android

上传后回调通知

注意CallbackBody中的转义字符。

Go SDK暂不支持上传回调。

PostObject支持上传回调，回调参数通过表单域callback携带，自定义变量通过独立的表单域携带，详情请参见PostObjet。

PostObject的使用示例如下：

SDK

上传回调示例

Java

PostObjectSample.java

Python

object_post.py

JS

JavaScript客户端签名直传

C#

PostPolicySample.cs

回调服务器（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命令调试，下面几个命令可能会用到：

调试回调服务器时，可以先忽略签名验证部分，因为cURL模拟签名功能比较困难。

签名验证功能OSS示例中已经提供，建议直接使用。

回调服务器建议有日志功能，记录收到的所有消息，方便调试、跟踪。

回调服务器正确处理回调请求后，一定要返回200，而不是其它的20x。

回调服务器返回给OSS的消息体，一定要是JSON格式，Content-Type设置为application/json。

InvalidArgument

回调参数设置错误，或参数格式错误。常见的错误是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：

回调服务器返回给OSS的消息体非JSON格式。您可以通过curl -d "" -v或抓包确认内容。Windows下推荐使用工具Wireshark 抓包，Linux下使用命令tcpdump抓包。一些非法返回消息体如下：OK，\357\273\277{"Status":"OK"}（即含有ef bb bf三个字节的BOM头）等。

示例2：

回调服务器处理时间超过5秒，OSS认为超时。建议回调服务器的处理逻辑修改为异步，保证在5秒内处理完毕并返回结果给OSS。

示例3：

回调服务器处理时间超过5秒，OSS认为超时。

示例4：

回调服务器返回给OSS的消息的状态码是400，请检查回调服务器的处理逻辑。

示例5：

回调服务器未启动，或者缺少上传回调参数中的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可以忽略。