平台技术-SPI服务接入文档
什么是SPI
- 服务商提供接口(Service Provider Interface)
- API:平台提供接口并实现,您来调用
- SPI:平台提供标准,您来实现,可以有多个实现方
SPI入驻流程
您需要做的是第三个方块中的工作。
申请业务场景
首先,您得有一个拥有“三方应用”标签的APP。点这里进行申请。
申请成功后,进入这个应用的控制台,就能看见“API服务提供”菜单
注意:在概览里可以看见当前应用的AppKey和AppSecret。
- AppKey:有两个作用.
- 场景Owner(就是引见您接入SPI的人)将此AppKey与场景绑定后,您就拥有了某场景的开发权,在此页面就能看见这个场景。
- SPI调用方需要在TargetAppkey填写这个AppKey,才能调到您实现的服务;
- AppSecret:开放平台(TOP)在调用您实现的服务时,会对报文进行签名(详见签名相关章节)。签名时就是使用这个密钥。您需要使用这个密钥进行验签。
我们拿“气象”场景举例。当场景Owner将此场景与您的AppKey绑定以后,在这个页面就能看见“气象”场景。
此时的场景状态是“开发中”。除了这个状态,场景还有“上线运行中”、“升级中”等几个状态。
- “开发中”至“上线运行中”:申请发布审核通过;
- “上线运行中”至“升级中”:点击进入升级后,对任何一个API点击升级版本。点击“取消升级”或申请发布并通过审核会重新回到“上线运行中”。
进入场景后可见到场景中的所有待实现的API,见下图。
与此同时,场景旁边是它的当前状态。
阅读文档
开发前一定要先仔细阅读文档,点击“开发文档”后可见到下图。
请严格按照文档进行开发,具体关注:
- 请求方法:POST 或 GET;
- 请求编码:UTF-8 或 GBK;
- 公共请求参数、业务请求参数以及响应参数要与文档完全一致。返回值可参考返回示例;
- 异常处理:按照这里的规范返回指定的字段,开放平台藉此判断您的返回是成功或失败;
- 请求示例:可使用这里的示例替换上您的参数,测试您实现的服务。注意,这个方法对排查错误非常有用。
服务开发
服务开发完成是您自主研发的过程,您只需要严格按照文档中的协议进行开发即可。开发语言、部署环境都没有特别的要求。
为了安全,我们强烈建议您的服务要验证签名以及验证请求方的IP。为了方便您的开发,我们有SDK提供给你,SDK下载页面请看下图。
签名校验
必选!验签的目的是防止黑客恶意调用你的服务,确保服务发起来源是阿里平台。
目前验签方法只提供了JAVA、PHP、.NET三个版本的SDK,其它语言需要自行实现。
签名方法生成规则是:
- 将query参数、header参数存入一个map中备用。为了方便说明,这个map取名为params。注意:query中的sign参数不能放入params;
- 如果body中的类型是form-data,将body中的所以除文件以外的参数放入params。因为一些技术原因,通过form-data传递的文件不进行签名;
- 如果body中的类型是json或xml,暂时将body保存起来后面备用。为了方便说明 ,这段内容取名为body;
- 将params进行按key的字母先后顺序排序,然后遍历它,按key1+value2+key2+value2……的方式形成一个字符串,为了方便说明,后续称之为签名串。如果value为空,则用””来代替。如果body不为空,则在签名串最后增加body的所有内容;
- 在签名串的头和尾加上secret。这个secret是sp申请应用时获得的。至此,签名串生成好了;
- 对签名串进行md5以及hex,最后得到sign。总结一下,生成sign的公式是:
hex(md5(secret+sorted(header_params+url_params+form_params)+body)+secret) - 最后,将生成的sign与从query中获取到的sign进行对比,即可校验签名的正确性。
验签示例代码如下:
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.taobao.api.internal.spi.CheckResult;
import com.taobao.api.internal.spi.SpiUtils;
public class TestHttpServlet extends HttpServlet {
private static final long serialVersionUID = -7841738585932624564L;
protected void doPost(HttpServletRequest req, HttpServletResponse rsp) throws ServletException, IOException {
CheckResult result = SpiUtils.checkSign(req, "fb821bc8785f2409a942eec601e6071d");
System.out.println(result.isSuccess());
System.out.println(result.getRequestBody());
}
}
IP来源校验
必选!防止黑客截取到开放平台发起的HTTP请求,拿到别的地方进行重放攻击。
淘宝开放平台网关的出口IP段可以通过taobao.top.ipout.get来获取,不定期更新,需要定时调用API获取最新数据。
IP来源校验示例代码如下:
private static final long serialVersionUID = -7841738585932624564L;
protected void doPost(HttpServletRequest req, HttpServletResponse rsp) throws ServletException, IOException {
// 最新IP段列表可通过taobao.top.ipout.get获得
List
ipList.add("140.205.144.0/24");
ipList.add("140.205.145.0/24");
ipList.add("140.205.40.0/24");
ipList.add("140.205.39.0/24");
ipList.add("140.205.51.0/24");
ipList.add("140.205.56.0/24");
boolean isSuccess = SpiUtils.checkRemoteIp(req, ipList);
if (!isSuccess) {
rsp.getWriter().write("access denied");
rsp.getWriter().flush();
}
}
}
另外一种做法是在HTTP Server上配置IP访问规则,如在Nginx上配置只允许TOP的IP访问/taobao目录:
allow 140.205.144.0/24;
allow 140.205.145.0/24;
allow 140.205.39.0/24;
allow 140.205.40.0/24;
allow 140.205.51.0/24;
allow 140.205.56.0/24;
deny all;
}
配置服务
点击“开发测试”进行下图的页面:
这里有两个地址输入框:
- 测试环境地址:此地址仅供测试使用。下一节详细讨论。
- 线上环境地址:当此SPI服务发布上线后,线上环境调用的地址就是此URL。
测试服务
共有两个地方或以发起测试,
1) SPI测试工具。点击本页面的“进入测试”即可进入此工具。请见下图:
默认情况下,只有一个测试用例:冒烟测试。这个测试仅仅是由SPI测试工具按照协议拼装一个HTTP请求发送给测试环境地址。
如果希望增加测试用例,请联系SPI平台负责人。
测试结束后,可以在测试详情中查看这次HTTP请求的所有参数。您尤其要关注“响应信息”中的内容,它可能初步检查你的服务是否正常。
2) API测试工具日常、沙箱环境:这里的测试是对SPI完整流程进行的测试,是您的服务发布上线前必不可少的步骤,只有这个步骤通过,才能证明您的服务运行正常。
调用一个TOP API,TOP把请求路由到您的测试环境地址,您需要把AppKey告诉API调用者,后者将在它前面加上“10"填入参数targetAppkey。
您也可以亲自客串api调用者,前提条件是场景owner先将此API加入沙箱,然后您申请调用此api的权限。要注意的是,沙箱测试的targetAppkey也是您的appkey前面加上“10”;还有,签名密钥是沙箱密钥。
API的调用方法可以去这里看文档。
申请发布
测试结束后,点击“完成测试”回到图5的场景列表页。如果您觉得可以将新配置的URL发布生效,点击“申请发布”。如果此场景配置成“需要审核”,则需要SPI平台负责人审核通过方可发布生效;否则,可立即生效。
FAQ
- 关于此文档暂时还没有FAQ