本文記錄我在對接位元組旗下產品火山雲旗下雲游戲產品 OpenApi 介面文檔時遇到的坑，希望能幫助大家（火山雲旗下雲游戲產品的文檔坑很多，我算是從零到一都踩了一遍，特此記錄，希望大家引以為鑒）。 1. 文檔問題 很經典的開局一張圖，對接全靠問， 這裡給大家強調下，當要跟第三方產品對接時，一定要確認拿到 ...
本文記錄我在對接位元組旗下產品火山雲旗下雲游戲產品 OpenApi 介面文檔時遇到的坑，希望能幫助大家（火山雲旗下雲游戲產品的文檔坑很多，我算是從零到一都踩了一遍，特此記錄，希望大家引以為鑒）。
1. 文檔問題
很經典的開局一張圖，對接全靠問，
這裡給大家強調下，當要跟第三方產品對接時，一定要確認拿到的文檔是不是最新版本。
比如我在這次對接中，第一次拿到的文檔是產品給的，在業務中需要用到一個用戶主動退出游戲的介面，於是我在第一份文檔裡面找到一個用戶退出游戲的介面 RomoveUser。
但是當我在控制台調用此介面報錯後，去群里一問才發現，對方建議我使用官網公佈的最新介面文檔。
進入官網發現 RemoveUser 這個介面已經是歷史介面了，官方建議換到 BanRoomUser 介面。
OK，這裡算是踩到了第一個坑，文檔版本不是最新。
ps：還要說一下，火山雲旗下雲游戲的這個 OpenApi 介面文檔需要在群里聯繫他們開白才能看到，說實話給我的感覺很奇怪，懷疑產品是否有趕鴨子上架問題，暫且懷疑他們的目的是防止不明攻擊吧。
2. OpenApi 示例 demo
第三方介面的接入一般都需要做鑒權。火山雲旗下雲游戲產品的 OpenApi 介面接入當然也不例外。於是我開始了第二個踩坑之旅，那就是他們給出的 OpenApi 示例 demo 的使用過於簡單。
火山雲旗下雲游戲產品的 OpenApi 示例 demo 寫的很簡單，只提供了一個 GET 請求示例。
OpenApi 示例 demo 地址：https://github.com/volcengine/veGame
但是在我司的業務場景還是上個問題，需要一個用戶主動退出游戲的介面，在火山雲官網的 OpenApi 文檔中我也找到了這個介面，就是上文提到的 BanRoomUser 介面。
但是在官方文檔中 BanRoomUser 介面是一個 POST JSON 格式的請求。官方給出的 OpenApi 示例 demo 中並沒有關於 POST JSON 請求的示例代碼，所以只能靠我一個人查看他們提供的 SDK 依賴源碼硬猜來寫...，這就很讓人頭痛了。
好在我翻閱他們 SDK 源碼中找到一個靠譜的 json(...) 請求方法，來完成這個 POST JSON 請求。
OK，說乾就乾，直接寫好示例代碼，開始發送 POST JSON 請求，
what f**k？什麼鬼，返回了我一個 null，此時我的內心中充滿了一個大大的問號。
我開始懷疑我的代碼是不是寫錯了。但是當我經歷過數次源碼 debug 以及調用其他 OpenApi 介面測試並得到正確返回後，我堅定的認為我沒錯，這就是火山雲 OpenApi 的 bug！
OK，說乾就乾，直接反饋給火山那邊。
接著火山那邊的人就聯繫說下午兩點開會一起遠程共用我的屏幕看看，OK 欣然接收，讓他們見證下他們寫的 bug！
...
時間來到下午兩點，當我共用屏幕給位元組工程師演示這個 bug 時，我的控制台列印如下，
woca，竟然不是 null！好在我腦袋靈活，思路清晰，瞬間想到我改了一個參數 GameId，之前返回 null 時，我傳的 GameId 是一個假數據，現在我傳的是一個真數據。造成了返回不一致。
OK，找到了返回正常的原因，當我把 GameId 改成假數據時，如我所願，返回了一個 null。
自此，我也就在位元組工程師的圍觀下，復現了他們的 OpenApi 介面的線上 bug。大功告成。
3. 鑒權失敗
位元組提供的 OpenApi 示例 demo 現在算是跑通了，但是由於我司項目一些依賴限制問題，我們不能直接引入火山雲旗下雲游戲產品的 SDK 依賴。所以我還得手動編寫生成簽名的代碼。於是我開始了第三個踩坑之旅，那就是 GET 請求驗簽成功 POST 請求驗簽失敗的問題。
這裡先說一下，火山雲提供了手動生成簽名的示例代碼
Java 生成簽名的代碼：https://github.com/volcengine/volc-openapi-demos/blob/main/signature/java/Sign.java
這裡我也是直接把簽名代碼拿來即用就行，一開始接入生成簽名代碼非常順利，GET 請求的 OpenApi 介面都是可以順利調通的，但是當我調用 BanRoomUser 介面時（沒錯，又是這個介面，踩的三個坑都與這個介面有關），直接提示驗簽失敗！
OK，開始排查為什麼簽名失敗。
查看源碼發現，POST JSON 請求時的 contentType 還是 application/x-www-form-urlencoded，直覺告訴我這裡不對，所以改成 application/json 試試，看看控制台返回，
很好，還是驗簽失敗！！！
我儘力了兄弟們，這個坑踩的我是無話可說。直接聯繫直接位元組開發人員看下我的請求內容是哪裡有問題。
在與位元組開發人員一起觀摩我寫的代碼以及生成的簽名之後，大家都沒找到問題所在。那沒辦法了，只能上伺服器看介面請求日誌了。
大家可以看出問題在哪裡嗎？沒錯我剛剛不是把 contentType 改成了 application/json 嗎，為什麼日誌顯示的 contentType 是 application/json; charset=utf-8！。
OK，到這裡問題也找到了，原因是我這個項目用的 http 請求工具是 okhttp3。他自動給我拼接上去的！
那麼怎麼解決嘞，替換 http3 工具的話，改造成本比較大，所以我就順勢把代碼的 contentType 也改成
application/json; charset=utf-8。
在測試一遍，看看控制台列印。
OK，拿到成功響應，自此也就解決了第三個坑，POST JSON 請求時的驗簽不匹配問題。
最後給大家貼出手動生成驗簽的代碼，有需要自取。
@Slf4j
public class Sign {
private static final BitSet URLENCODER = new BitSet(256);
private static final String CONST_ENCODE = "0123456789ABCDEF";
public static final Charset UTF_8 = StandardCharsets.UTF_8;
private final String region;
private final String service;
private final String host;
private final String path;
private final String ak;
private final String sk;
static {
int i;
for (i = 97; i <= 122; ++i) {
URLENCODER.set(i);
}
for (i = 65; i <= 90; ++i) {
URLENCODER.set(i);
}
for (i = 48; i <= 57; ++i) {
URLENCODER.set(i);
}
URLENCODER.set('-');
URLENCODER.set('_');
URLENCODER.set('.');
URLENCODER.set('~');
}
public Sign(String region, String service, String host, String path, String ak, String sk) {
this.region = region;
this.service = service;
this.host = host;
this.path = path;
this.ak = ak;
this.sk = sk;
}
public Headers calcAuthorization(String method, Map<String, String> queryList, byte[] body,
Date date, String action, String version) throws Exception {
// 請求頭
Map<String, String> headerMap = new HashMap<>();
String contentType = "application/x-www-form-urlencoded; charset=utf-8";
if (body == null) {
body = new byte[0];
} else {
contentType = "application/json; charset=utf-8";
}
String xContentSha256 = hashSHA256(body);
SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMdd'T'HHmmss'Z'");
sdf.setTimeZone(TimeZone.getTimeZone("GMT"));
// String xDate = "20240515T061353Z";
String xDate = sdf.format(date);
String shortXDate = xDate.substring(0, 8);
String signHeader = "content-type;host;x-content-sha256;x-date";
SortedMap<String, String> realQueryList = new TreeMap<>(queryList);
realQueryList.put("Action", action);
realQueryList.put("Version", version);
StringBuilder querySB = new StringBuilder();
for (String key : realQueryList.keySet()) {
querySB.append(signStringEncoder(key)).append("=").append(signStringEncoder(realQueryList.get(key))).append("&");
}
querySB.deleteCharAt(querySB.length() - 1);
String canonicalStringBuilder = method + "\n" + path + "\n" + querySB + "\n" +
"content-type:" + contentType + "\n" +
"host:" + host + "\n" +
"x-content-sha256:" + xContentSha256 + "\n" +
"x-date:" + xDate + "\n" +
"\n" +
signHeader + "\n" +
xContentSha256;
// log.info("canonicalStringBuilder is {}", canonicalStringBuilder);
String hashcanonicalString = hashSHA256(canonicalStringBuilder.getBytes());
String credentialScope = shortXDate + "/" + region + "/" + service + "/request";
String signString = "HMAC-SHA256" + "\n" + xDate + "\n" + credentialScope + "\n" + hashcanonicalString;
// log.info("signString is {}", signString);
byte[] signKey = genSigningSecretKeyV4(sk, shortXDate, region, service);
String signature = HexUtil.encodeHexStr(hmacSHA256(signKey, signString));
String auth = "HMAC-SHA256" +
" Credential=" + ak + "/" + credentialScope +
", SignedHeaders=" + signHeader +
", Signature=" + signature;
headerMap.put("Authorization", auth);
headerMap.put("X-Date", xDate);
headerMap.put("X-Content-Sha256", xContentSha256);
headerMap.put("Host", host);
headerMap.put("Content-Type", contentType);
headerMap.put("User-Agent", "volc-sdk-java/v");
headerMap.put("Accept", "application/json");
return Headers.of(headerMap);
}
private static String signStringEncoder(String source) {
if (source == null) {
return null;
}
StringBuilder buf = new StringBuilder(source.length());
ByteBuffer bb = UTF_8.encode(source);
while (bb.hasRemaining()) {
int b = bb.get() & 255;
if (URLENCODER.get(b)) {
buf.append((char) b);
} else if (b == 32) {
buf.append("%20");
} else {
buf.append("%");
char hex1 = CONST_ENCODE.charAt(b >> 4);
char hex2 = CONST_ENCODE.charAt(b & 15);
buf.append(hex1);
buf.append(hex2);
}
}
return buf.toString();
}
public static String hashSHA256(byte[] content) throws Exception {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
// return HexFormat.of().formatHex(md.digest(content));
return HexUtil.encodeHexStr(md.digest(content));
} catch (Exception e) {
throw new Exception(
"Unable to compute hash while signing request: "
+ e.getMessage(), e);
}
}
public static byte[] hmacSHA256(byte[] key, String content) throws Exception {
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(key, "HmacSHA256"));
return mac.doFinal(content.getBytes());
} catch (Exception e) {
throw new Exception(
"Unable to calculate a request signature: "
+ e.getMessage(), e);
}
}
private byte[] genSigningSecretKeyV4(String secretKey, String date, String region, String service) throws Exception {
byte[] kDate = hmacSHA256((secretKey).getBytes(), date);
byte[] kRegion = hmacSHA256(kDate, region);
byte[] kService = hmacSHA256(kRegion, service);
return hmacSHA256(kService, "request");
}
}
總結
在與火山雲旗下雲游戲產品的 OpenApi 介面對接過程中，我總共踩了三個坑。一是文檔版本不是最新，二是官方提供的 OpenApi 示例 demo 過於簡單，三是官方提供的驗簽代碼沒有考慮到 POST JSON 請求場景下的 contentType 設置問題。
在這裡也想給大家傳個話，沒有必要神話大廠，大廠也有 bug，大廠的產品也會服務中斷。比如火山雲旗下雲游戲產品的 OpenApi 介面文檔示例 demo 簡陋，手動生成簽名代碼場景單一，覆蓋不全等問題，最後就是竟然還返回了一個 null 給我！不過此次對接過程中，在我反饋 OpenApi 介面各種問題時，群里小伙伴都能及時回應以及拉群溝通查看問題解決問題的態度點個贊
