平臺(tái)技術(shù)-SPI服務(wù)接入文檔
什么是SPI
- 服務(wù)商提供接口（Service Provider Interface）
- API：平臺(tái)提供接口并實(shí)現(xiàn)，您來調(diào)用
- SPI：平臺(tái)提供標(biāo)準(zhǔn)，您來實(shí)現(xiàn)，可以有多個(gè)實(shí)現(xiàn)方
SPI入駐流程
您需要做的是第三個(gè)方塊中的工作。
申請(qǐng)業(yè)務(wù)場(chǎng)景
首先，您得有一個(gè)擁有“三方應(yīng)用”標(biāo)簽的APP。點(diǎn)這里進(jìn)行申請(qǐng)。
申請(qǐng)成功后，進(jìn)入這個(gè)應(yīng)用的控制臺(tái)，就能看見“API服務(wù)提供”菜單
注意：在概覽里可以看見當(dāng)前應(yīng)用的AppKey和AppSecret。
- AppKey：有兩個(gè)作用.
- 場(chǎng)景Owner（就是引見您接入SPI的人）將此AppKey與場(chǎng)景綁定后，您就擁有了某場(chǎng)景的開發(fā)權(quán)，在此頁(yè)面就能看見這個(gè)場(chǎng)景。
- SPI調(diào)用方需要在TargetAppkey填寫這個(gè)AppKey，才能調(diào)到您實(shí)現(xiàn)的服務(wù)；
- AppSecret：開放平臺(tái)(TOP）在調(diào)用您實(shí)現(xiàn)的服務(wù)時(shí)，會(huì)對(duì)報(bào)文進(jìn)行簽名（詳見簽名相關(guān)章節(jié)）。簽名時(shí)就是使用這個(gè)密鑰。您需要使用這個(gè)密鑰進(jìn)行驗(yàn)簽。
我們拿“氣象”場(chǎng)景舉例。當(dāng)場(chǎng)景Owner將此場(chǎng)景與您的AppKey綁定以后，在這個(gè)頁(yè)面就能看見“氣象”場(chǎng)景。
此時(shí)的場(chǎng)景狀態(tài)是“開發(fā)中”。除了這個(gè)狀態(tài)，場(chǎng)景還有“上線運(yùn)行中”、“升級(jí)中”等幾個(gè)狀態(tài)。
- “開發(fā)中”至“上線運(yùn)行中”：申請(qǐng)發(fā)布審核通過；
- “上線運(yùn)行中”至“升級(jí)中”：點(diǎn)擊進(jìn)入升級(jí)后，對(duì)任何一個(gè)API點(diǎn)擊升級(jí)版本。點(diǎn)擊“取消升級(jí)”或申請(qǐng)發(fā)布并通過審核會(huì)重新回到“上線運(yùn)行中”。
進(jìn)入場(chǎng)景后可見到場(chǎng)景中的所有待實(shí)現(xiàn)的API，見下圖。
與此同時(shí)，場(chǎng)景旁邊是它的當(dāng)前狀態(tài)。
閱讀文檔
開發(fā)前一定要先仔細(xì)閱讀文檔，點(diǎn)擊“開發(fā)文檔”后可見到下圖。
請(qǐng)嚴(yán)格按照文檔進(jìn)行開發(fā)，具體關(guān)注：
- 請(qǐng)求方法：POST 或 GET;
- 請(qǐng)求編碼：UTF-8 或 GBK；
- 公共請(qǐng)求參數(shù)、業(yè)務(wù)請(qǐng)求參數(shù)以及響應(yīng)參數(shù)要與文檔完全一致。返回值可參考返回示例；
- 異常處理：按照這里的規(guī)范返回指定的字段，開放平臺(tái)藉此判斷您的返回是成功或失??；
- 請(qǐng)求示例：可使用這里的示例替換上您的參數(shù)，測(cè)試您實(shí)現(xiàn)的服務(wù)。注意，這個(gè)方法對(duì)排查錯(cuò)誤非常有用。
服務(wù)開發(fā)
服務(wù)開發(fā)完成是您自主研發(fā)的過程，您只需要嚴(yán)格按照文檔中的協(xié)議進(jìn)行開發(fā)即可。開發(fā)語言、部署環(huán)境都沒有特別的要求。
為了安全，我們強(qiáng)烈建議您的服務(wù)要驗(yàn)證簽名以及驗(yàn)證請(qǐng)求方的IP。為了方便您的開發(fā)，我們有SDK提供給你，SDK下載頁(yè)面請(qǐng)看下圖。
簽名校驗(yàn)
必選！驗(yàn)簽的目的是防止黑客惡意調(diào)用你的服務(wù)，確保服務(wù)發(fā)起來源是阿里平臺(tái)。
目前驗(yàn)簽方法只提供了JAVA、PHP、.NET三個(gè)版本的SDK，其它語言需要自行實(shí)現(xiàn)。
簽名方法生成規(guī)則是：
- 將query參數(shù)、header參數(shù)存入一個(gè)map中備用。為了方便說明，這個(gè)map取名為params。注意：query中的sign參數(shù)不能放入params；
- 如果body中的類型是form-data，將body中的所以除文件以外的參數(shù)放入params。因?yàn)橐恍┘夹g(shù)原因，通過form-data傳遞的文件不進(jìn)行簽名；
- 如果body中的類型是json或xml，暫時(shí)將body保存起來后面?zhèn)溆?。為了方便說明 ，這段內(nèi)容取名為body；
- 將params進(jìn)行按key的字母先后順序排序，然后遍歷它，按key1+value2+key2+value2……的方式形成一個(gè)字符串，為了方便說明，后續(xù)稱之為簽名串。如果value為空，則用””來代替。如果body不為空，則在簽名串最后增加body的所有內(nèi)容；
- 在簽名串的頭和尾加上secret。這個(gè)secret是sp申請(qǐng)應(yīng)用時(shí)獲得的。至此，簽名串生成好了；
- 對(duì)簽名串進(jìn)行md5以及hex，最后得到sign?？偨Y(jié)一下，生成sign的公式是：
hex(md5(secret+sorted(header_params+url_params+form_params)+body)+secret) - 最后，將生成的sign與從query中獲取到的sign進(jìn)行對(duì)比，即可校驗(yàn)簽名的正確性。
驗(yàn)簽示例代碼如下：
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來源校驗(yàn)
必選！防止黑客截取到開放平臺(tái)發(fā)起的HTTP請(qǐng)求，拿到別的地方進(jìn)行重放攻擊。
淘寶開放平臺(tái)網(wǎng)關(guān)的出口IP段可以通過taobao.top.ipout.get來獲取，不定期更新，需要定時(shí)調(diào)用API獲取最新數(shù)據(jù)。
IP來源校驗(yàn)示例代碼如下：
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訪問規(guī)則，如在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;
}
配置服務(wù)
點(diǎn)擊“開發(fā)測(cè)試”進(jìn)行下圖的頁(yè)面：
這里有兩個(gè)地址輸入框：
- 測(cè)試環(huán)境地址：此地址僅供測(cè)試使用。下一節(jié)詳細(xì)討論。
- 線上環(huán)境地址：當(dāng)此SPI服務(wù)發(fā)布上線后，線上環(huán)境調(diào)用的地址就是此URL。
測(cè)試服務(wù)
共有兩個(gè)地方或以發(fā)起測(cè)試，
1) SPI測(cè)試工具。點(diǎn)擊本頁(yè)面的“進(jìn)入測(cè)試”即可進(jìn)入此工具。請(qǐng)見下圖：
默認(rèn)情況下，只有一個(gè)測(cè)試用例：冒煙測(cè)試。這個(gè)測(cè)試僅僅是由SPI測(cè)試工具按照協(xié)議拼裝一個(gè)HTTP請(qǐng)求發(fā)送給測(cè)試環(huán)境地址。
如果希望增加測(cè)試用例，請(qǐng)聯(lián)系SPI平臺(tái)負(fù)責(zé)人。
測(cè)試結(jié)束后，可以在測(cè)試詳情中查看這次HTTP請(qǐng)求的所有參數(shù)。您尤其要關(guān)注“響應(yīng)信息”中的內(nèi)容，它可能初步檢查你的服務(wù)是否正常。
2) API測(cè)試工具日常、沙箱環(huán)境：這里的測(cè)試是對(duì)SPI完整流程進(jìn)行的測(cè)試，是您的服務(wù)發(fā)布上線前必不可少的步驟，只有這個(gè)步驟通過，才能證明您的服務(wù)運(yùn)行正常。
調(diào)用一個(gè)TOP API，TOP把請(qǐng)求路由到您的測(cè)試環(huán)境地址，您需要把AppKey告訴API調(diào)用者，后者將在它前面加上“10"填入?yún)?shù)targetAppkey。
您也可以親自客串a(chǎn)pi調(diào)用者，前提條件是場(chǎng)景owner先將此API加入沙箱，然后您申請(qǐng)調(diào)用此api的權(quán)限。要注意的是，沙箱測(cè)試的targetAppkey也是您的appkey前面加上“10”；還有，簽名密鑰是沙箱密鑰。
API的調(diào)用方法可以去這里看文檔。
申請(qǐng)發(fā)布
測(cè)試結(jié)束后，點(diǎn)擊“完成測(cè)試”回到圖5的場(chǎng)景列表頁(yè)。如果您覺得可以將新配置的URL發(fā)布生效，點(diǎn)擊“申請(qǐng)發(fā)布”。如果此場(chǎng)景配置成“需要審核”，則需要SPI平臺(tái)負(fù)責(zé)人審核通過方可發(fā)布生效；否則，可立即生效。
FAQ
- 關(guān)于此文檔暫時(shí)還沒有FAQ