ZOLOZZOLOZDOCS

接入ZOLOZ网关

ZOLOZ API独立于编程语言并由网关服务对外开放。在接入ZOLOZ API之前，您需要确保可以与ZOLOZ网关服务进行通信。本文介绍使用Java库或ZOLOZ辅助脚本接入ZOLOZ API的方法，以及如果是自行实现的网关协议，如何使用ZOLOZ辅助脚本来验证自己的实现。

前提条件

  • 网关服务基于网关协议而实现，请确保您已了解ZOLOZ网关协议。
  • 您您已获取与网关服务通信时使用的API凭证，请参见获取API凭证。

接入方法

要实现与网关服务通信，一是可以集成已有的网关协议库，二是自行实现网关协议。

  • ZOLOZ提供多个库供您根据您的编程语言和环境进行选择。
    • Java库：当您的编程语言是Java时使用此库，请参见添加Java库。
    • 辅助脚本：当您需要直接从shell调用ZOLZO API时使用此shell脚本，请参见使用辅助脚本。

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文件中添加以下依赖项，将库引入项目中。如需获取最新版本的依赖项，请单击这里。
copy
<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>1.0.2</version>
</dependency>
  1. 导入OpenApiClient类。
copy
import com.zoloz.api.sdk.client.OpenApiClient;
  1. 实例化并配置OpenApiClient类。
copy
//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，请参见选择站点和环境。
  1. 调用ZOLOZ API。
copy
//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. 获取辅助脚本。
copy
# 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
  1. 在POSIX Shell环境中运行脚本调用ZOLOZ API。
copy
# 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密钥
    • 加密的请求内容
    • 请求签名
  1. 调用辅助脚本以使用相同的请求调用相同的API，并添加以下选项。
    • -v或-vv：使用该选项打印详细信息供后续验证。
    • -t <request time>：使用该选项将请求时间指定为步骤1中调用API请求的时间。
    • -k <AES128 key>：使用该选项指定AES128作为步骤1中使用的密钥来加密请求内容。

以下示例介绍了如何运行脚本。

copy
./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调用过程的详细输出。

image.png

图1. 使用ZOLOZ辅助脚本中API调用的详细输出

  1. 将步骤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上已开源，您可以通过下方链接获取源代码。