平台技术-SPI服务接入文档

什么是SPI

  • 服务商提供接口(Service Provider Interface)
    • API:平台提供接口并实现,您来调用
    • SPI:平台提供标准,您来实现,可以有多个实现方

image

SPI入驻流程

image

您需要做的是第三个方块中的工作。

申请业务场景

首先,您得有一个拥有“三方应用”标签的APP。点这里进行申请。

申请成功后,进入这个应用的控制台,就能看见“API服务提供”菜单

image

注意:在概览里可以看见当前应用的AppKey和AppSecret。

  • AppKey:有两个作用.
    • 场景Owner(就是引见您接入SPI的人)将此AppKey与场景绑定后,您就拥有了某场景的开发权,在此页面就能看见这个场景。
    • SPI调用方需要在TargetAppkey填写这个AppKey,才能调到您实现的服务;
  • AppSecret:开放平台(TOP)在调用您实现的服务时,会对报文进行签名(详见签名相关章节)。签名时就是使用这个密钥。您需要使用这个密钥进行验签。

我们拿“气象”场景举例。当场景Owner将此场景与您的AppKey绑定以后,在这个页面就能看见“气象”场景。

此时的场景状态是“开发中”。除了这个状态,场景还有“上线运行中”、“升级中”等几个状态。

  • “开发中”至“上线运行中”:申请发布审核通过;
  • “上线运行中”至“升级中”:点击进入升级后,对任何一个API点击升级版本。点击“取消升级”或申请发布并通过审核会重新回到“上线运行中”。

image

进入场景后可见到场景中的所有待实现的API,见下图。

image

与此同时,场景旁边是它的当前状态。

阅读文档

开发前一定要先仔细阅读文档,点击“开发文档”后可见到下图。

image

请严格按照文档进行开发,具体关注:

  • 请求方法:POST 或 GET;
  • 请求编码:UTF-8 或 GBK;
  • 公共请求参数、业务请求参数以及响应参数要与文档完全一致。返回值可参考返回示例;
  • 异常处理:按照这里的规范返回指定的字段,开放平台藉此判断您的返回是成功或失败;
  • 请求示例:可使用这里的示例替换上您的参数,测试您实现的服务。注意,这个方法对排查错误非常有用。

服务开发

服务开发完成是您自主研发的过程,您只需要严格按照文档中的协议进行开发即可。开发语言、部署环境都没有特别的要求。

为了安全,我们强烈建议您的服务要验证签名以及验证请求方的IP。为了方便您的开发,我们有SDK提供给你,SDK下载页面请看下图。

image

签名校验

必选!验签的目的是防止黑客恶意调用你的服务,确保服务发起来源是阿里平台。

目前验签方法只提供了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());
    }
 
}
注:HTTP请求中的URL参数编码字符集、字符串转字节流进行MD5摘要时的字符集要保持一致,否则会导致含中文参数的签名与TOP不一致。

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;
}

配置服务

点击“开发测试”进行下图的页面:

image

这里有两个地址输入框:

  • 测试环境地址:此地址仅供测试使用。下一节详细讨论。
  • 线上环境地址:当此SPI服务发布上线后,线上环境调用的地址就是此URL。

测试服务

共有两个地方或以发起测试,

1) SPI测试工具。点击本页面的“进入测试”即可进入此工具。请见下图:

image

默认情况下,只有一个测试用例:冒烟测试。这个测试仅仅是由SPI测试工具按照协议拼装一个HTTP请求发送给测试环境地址。

如果希望增加测试用例,请联系SPI平台负责人。

测试结束后,可以在测试详情中查看这次HTTP请求的所有参数。您尤其要关注“响应信息”中的内容,它可能初步检查你的服务是否正常。

image

2) API测试工具日常、沙箱环境:这里的测试是对SPI完整流程进行的测试,是您的服务发布上线前必不可少的步骤,只有这个步骤通过,才能证明您的服务运行正常。

调用一个TOP API,TOP把请求路由到您的测试环境地址,您需要把AppKey告诉API调用者,后者将在它前面加上“10"填入参数targetAppkey。

您也可以亲自客串api调用者,前提条件是场景owner先将此API加入沙箱,然后您申请调用此api的权限。要注意的是,沙箱测试的targetAppkey也是您的appkey前面加上“10”;还有,签名密钥是沙箱密钥。

API的调用方法可以去这里看文档。

申请发布

测试结束后,点击“完成测试”回到图5的场景列表页。如果您觉得可以将新配置的URL发布生效,点击“申请发布”。如果此场景配置成“需要审核”,则需要SPI平台负责人审核通过方可发布生效;否则,可立即生效。

FAQ

  • 关于此文档暂时还没有FAQ