概述

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