什么是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 java.io.IOException;

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来源校验示例代码如下：

public class TestHttpServlet extends HttpServlet {

	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目录：

location /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