概述

ZOLOZ支援兩種主流的網關接入方式，公私密金鑰接入方式和AK/SK接入方式。客戶可根據實際業務需求，選擇適合的接入方式。

通過公私密金鑰方式接入ZOLOZ網關

ZOLOZ API獨立於程式設計語言並由網關服務對外開放。在接入ZOLOZ API之前，您需要確保可以與ZOLOZ網關服務進行通訊。本文介紹使用Java庫或ZOLOZ輔助指令碼接入ZOLOZ API的方法，以及如果是自行實現的網關協議，如何使用ZOLOZ輔助指令碼來驗證自己的實現。

前提條件

• 網關服務基於網關協議而實現，請確保您已瞭解ZOLOZ網關協議。

• 您已擷取與網關服務通訊時使用的API憑證，請參見擷取API 憑證。

接入方法

要實現與網關服務通訊，一是可以整合已有的網關協議庫，二是自行實現網關協議。

• ZOLOZ提供多個庫供您根據您的程式設計語言和環境進行選擇。

• Java庫：當您的程式設計語言是Java時使用此庫，請參見添加Java庫。

• 輔助指令碼：當您需要直接從shell調用ZOLZO API時使用此shell指令碼，請參見使用輔助指令碼。

• 如果您是自行實現的網關協議，也可以使用ZOLOZ輔助指令碼來驗證自己的實現，請參見自行實現網關協議進行接入。

Authentication test API說明

本文使用Authentication test API進行示範。Authentication test API是一個特殊的API，與特定產品無關，用於身分識別驗證測試。Authentication test API支援所有有效JSON對象，並返回相同的JSON對象，類似echo命令。

和其他API 一樣，Authentication test API也建立在網關服務之上，當您成功地調用Authentication test API後，整合其他API將非常簡單。

方法一：通過已有庫接入ZOLOZ API

添加Java庫

ZOLOZ Java庫發布在Maven中央存放庫中。以下介紹如何使用公用Java庫與網關服務互動並調用ZOLOZ API。

1. 引入API SDK。

   在專案的POM檔案中添加以下依賴項，將庫引入專案中。如需擷取最新版本的依賴項，請單擊這裡。

<dependency>
 <groupId>com.zoloz.api.sdk</groupId>
 <artifactId>zoloz-api-sdk</artifactId>
 <version>1.0.2</version>
</dependency>

2. 匯入OpenApiClient類。

import com.zoloz.api.sdk.client.OpenApiClient;

3. 執行個體化並配置OpenApiClient類。

//Set proper values to following vairables
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
String merchantPrivateKey = "<The merchant's private key content encoded in base64>";

//Instantiate an OpenApiClient object with signature validation and encryption both enabled by default
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//NOTE: uncomment the following line if you want to skip signature validation for response
//client.setSigned(false);      
//NOTE: uncomment the following line if you want to disable encryption
//client.setEncrypted(false);  

您需要將代碼中的以下欄位替換成您的真實資訊。如需擷取clientId、zolozPublicKey、merchantPrivateKey，請參見擷取API 憑證。

• clientId：客戶ID。

• zolozPublicKey：ZOLOZ交易公開金鑰，採用Base64編碼格式。

• merchantPrivateKey：商戶交易私密金鑰，採用Base64編碼格式。

• setHostUrl：ZOLOZ網關URL，如需擷取ZOLOZ網關URL，請參見選擇網站和環境。

4. 調用ZOLOZ API。

//Set the name of authentication test API 
String apiName = "v1.zoloz.authentication.test";

//Set the request, a simple JSON object
String request = "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

使用輔助指令碼

1. 擷取輔助指令碼。

# Download the script to local.
wget https://raw.githubusercontent.com/zoloz-pte-ltd/zoloz-api-script/master/zoloz.sh

# Allow the script to be executed.
chmod u+x zoloz.sh

2. 在POSIX Shell環境中運行指令碼調用ZOLOZ API。

# Assume that zoloz.sh is in current working directory.
./zoloz.sh \
 -c 2188000123456789 \
 -P merchant_private_key.pem \
 -K 'MIIBIj...QIDAQAB' \
 -a /api/v1/zoloz/authentication/test \
 -d '{\n "title": "hello",\n "description": "just for demonstration."\n}'

上述代碼中使用的樣本值僅供參考，在實際使用過程中，您需要將以下欄位替換成您的真實資訊。如需擷取客戶ID、ZOLOZ交易公開金鑰，請參見擷取API 憑證。

• -c：指客戶ID。

• -P：指商戶交易私密金鑰。代碼中的“merchant_private_key.pem”是私密金鑰的樣本值，您需要將其替換為商戶交易私密金鑰的真實路徑。

• -K：指ZOLOZ交易公開金鑰。

• -a：指API的路徑，上述代碼中為示範指定了身分識別驗證測試API。

• -d：指請求的內容。

除了上面列出的選項外，您還可以根據需要添加以下選項：

• -e：禁用加密。

• -i：跳過響應簽名驗證。

方法二：自行實現網關協議進行接入

您可以自行實現網關協議來接入ZOLOZ API，接入後您可以根據以下方法通過ZOLOZ輔助指令碼來驗證接入結果。

1. 執行您的實作類別來調用API，並記錄流程詳細資料。

   需要記錄的資訊如下：

   • 通話中使用的請求時間

   • 用於請求加密隨機產生的AES密鑰

   • 加密的請求內容

   • 請求籤名

2. 調用輔助指令碼以使用相同的請求調用相同的API，並添加以下選項。

   • -v或-vv：列印詳細資料供後續驗證。

   • -t <request time>：將請求時間指定為步驟1中調用API請求的時間。

   • -k <AES128 key>：指定AES128作為步驟1中使用的密鑰來加密請求內容。

以下樣本介紹了如何運行指令碼。

./zoloz.sh \
 -c 2**************4 \
 -P merchant_private_key.pem \
 -K 'MIIBIj...QIDAQAB' \
 -a /api/v1/zoloz/authentication/test \
 -d '{
 "title": "hello",
 "description": "This is just a demonstration."
}' \
 -vv \
 -k 31313131313131313131313131313131 \
 -t 2020-12-01T00:00:00+0800

下圖顯示了API調用過程的詳細輸出。

圖1. 使用ZOLOZ輔助指令碼中API調用的詳細輸出

3. 將步驟1記錄的流程詳細資料與步驟2列印的詳細輸出進行比較。

   1. 驗證請求加密。

      檢查您的加密請求內容與上圖②中request body欄位顯示的內容是否相同。

      注意：通常RSA加密會添加隨機資訊避免可能存在的攻擊，因此您的實現對AES128祕密金鑰加密會產生不同的結果，此時您可以比較請求內容加密。

   2. 驗證請求籤名。

      檢查您在要求標頭中填寫的請求籤名與上圖③中urlencoded request signature欄位顯示的內容是否相同。

   3. 驗證響應簽名。

      確認上圖④中response signature欄位顯示的簽名是否可以通過您的實現對目標內容的簽名進行驗證，目標內容為上圖④中的response content to be verified欄位。

   4. 驗證響應解密。

      • 檢查您的實現是否可以將加密的AES128密鑰（上圖⑤中的response encrypted symmetric key欄位）解密為相同的AES128密鑰（上圖⑤中的response symmetric key欄位）。

      • 檢查您的實現是否可以將加密的響應內容（上圖⑤中的response body欄位）解密為相同的明文內容（上圖⑤中的response content欄位）。

相關資料

JAR和ZOLOZ輔助指令碼在Github上已開源，您可以通過下方連結擷取原始碼。

• Java庫

• ZOLOZ輔助指令碼

通過AK/SK方式接入ZOLOZ網關

ZOLOZ API獨立於程式設計語言，通過網關服務對外開放。在接入ZOLOZ API之前，您需要確保可以與ZOLOZ網關服務進行通訊。本文介紹使用AK/SK方式接入ZOLOZ網關的方法。

接入方法

要實現與ZOLOZ網關服務通訊，一是可以整合已有的網關協議庫，二是自行實現網關協議。

• ZOLOZ提供了多個庫，供您根據您的程式設計語言和開發環境進行選擇。如果您的程式設計語言是Java，請參見方法一：通過已有Java庫接入ZOLOZ API。

• 如果您選擇自行實現網關協議，請參見方法二：自行實現網關協議接入ZOLOZ API。

Authentication test API說明

本文使用Authentication test API進行示範。Authentication test API是一個特殊的API，與特定產品無關，用於身分識別驗證測試。Authentication test API支援所有有效JSON對象，並返回相同的JSON對象，類似echo命令。

和其他API 一樣，Authentication test API也建立在網關服務之上，當您成功地調用Authentication test API後，整合其他API將非常簡單。同時本文提供了一個Postman檔案範例，您可以通過Postman發送請求進行API測試。

方法一：通過已有Java庫接入ZOLOZ API

ZOLOZ Java庫發布在Maven中央存放庫中。以下是使用公用Java庫與網關服務互動並調用ZOLOZ API的步驟。

1. 引入API SDK。

   在專案的POM檔案中添加以下依賴項，將ZOLOZ Java庫引入專案中。請確保API SDK為1.1.0及以上版本，單擊這裡可擷取最新版本的依賴項。

<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>1.1.0</version>
</dependency>

2. 匯入OpenApiClient類。

import com.zoloz.api.sdk.client.OpenApiClient;

3. 執行個體化並配置OpenApiClient類。

   請將代碼中的以下欄位替換成您的真實資訊。如需擷取clientId、accessKey、secretKey，請參見AK/SK管理。

   • clientId：客戶ID。

   • accessKey/secretKey：一組用於身分識別驗證和授權的金鑰組。

   • setHostUrl：ZOLOZ網關URL。如需擷取ZOLOZ網關URL，請參見選擇網站和環境。

//Set proper values to following vairablesString clientId = "<Client ID>";
String accessKey = "<ACCESS KEY>";
String secretKey = "<SECRET KEY>";

//Instantiate an OpenApiClient object OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setAccessKey(accessKey);
client.setSecretKey(secretKey);

4. 調用ZOLOZ API。

//Set the name of authentication test API 
String apiName = "v1.zoloz.authentication.test";

//Set the request, a simple JSON object
String request = "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

方法二：自行實現網關協議接入ZOLOZ API

自行實現網關協議接入ZOLOZ API時，您需要按照指定的報文結構發送請求，詳見請求報文的結構。以下是使用secretKey進行HmacSHA256演算法產生簽名的步驟。

1. 解碼Base64密鑰。

   使用支援URL安全字元集（即使用-替換+，_替換/）的標準Base64解碼函數，將secretKey從Base64編碼轉換為原始位元組資料。

   注意：部分語言預設的Base64解碼器可能不支援URL安全字元，此時需手動替換或使用專用庫。

2. 初始化HMAC-SHA256。

   1. 建立HMAC-SHA256執行個體。

   2. 將解碼後的位元組數組作為密鑰傳入，初始化HMAC-SHA256演算法。

      注意：密鑰類型需要為位元組流（byte[]），不支援字串。

3. 計算簽名。

   1. 將待簽名字串以UTF-8編碼轉換為位元組數組。

   2. 使用HMAC-SHA256演算法對位元組數組進行簽名計算，以產生簽名結果。

4. 編碼簽名結果。

   使用Base64編碼函數對簽名結果進行編碼，將簽名結果轉換為URL安全的Base64字串。請確保輸出內容符合URL安全格式：

   • 替換Base64字元中的+為-，/為_。

   • 刪除末尾的填充字元=。

5. 驗證簽名。

   將使用代碼產生的簽名與Postman產生的簽名進行比對，驗證簽名是否一致。

使用Postman測試API

Postman是一款常用的API測試載入器，廣泛用於開發、測試和調試API介面。以下是使用Postman進行API測試的詳細步驟。

1. 匯入Postman集合。

   1. 開啟並下載設定檔。

   2. 開啟Postman，單擊Import。

   3. 將下載的設定檔拖拽到匯入視窗或選擇檔案進行上傳。

2. 佈建要求地址。

   將{host}替換為實際請求的伺服器位址。

   https://{host}/api/v1/zoloz/authentication/test

3. 配置認證資訊。

   1. 在Postman中開啟請求的Pre-request Script標籤。

   2. 修改以下三個常量。

      const ACCESS_KEY = "your Access key";   // 替換成您的Access Key
      const SECRET_KEY = "your secret key";   // 替換成您的Secret Key
      const CLIENT_ID = "your client id";     // 替換成您的Client ID

4. 執行API請求。

   1. 切換到Body標籤，使用預設測試資料進行請求。

      {
          "title": "hello",
          "description": "just for demonstration."}

   2. 單擊Send發送請求。

5. 返回測試結果。

   {
       "result": {
           "resultCode": "SUCCESS",
           "resultMessage": "{\"title\":\"hello\",\"description\":\"just for demonstration.\"}",
           "resultStatus": "S"    }
   }