平台技术-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<String> ipList = new ArrayList<String>();
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