接入 ZOLOZ 网关

2022-05-09 03:03

ZOLOZ API 独立于编程语言并由网关服务对外开放。在接入 ZOLOZ API 前，您首先应确保可以与 ZOLOZ 网关服务进行通信。

前置条件

由于网关服务基于网关协议实的，请确保已了解 ZOLOZ 网关协议。您可以通过 ZOLOZ 网关协议了解网关协议，以及协议中的规则。
已获取与网关服务交互中使用的 API 凭证，关于如何获取 API 凭证请参考获取 API 凭证。

关于任务

要实现与网关服务通信，既支持接入已有的网关协议库，也支持自行实现网关协议。

ZOLOZ 提供多个库供您根据您的编程语言和环境进行选择：

Java 库：当您的编程语言是 Java 时使用此库。
辅助脚本：当您需要直接从 shell 调用 ZOLZO API 时使用此 shell 脚本。 ZOLOZ 辅助程序脚本还为您提供了高级用法来验证您自己的实现。

此任务向您介绍如何使用 Java 库或 ZOLOZ 帮助程序脚本集成 ZOLOZ API。它还提供了有关如何使用 ZOLOZ 帮助程序脚本验证您自己的网关协议实现的说明。

Authentication API 说明

此任务使用 Authentication API 进行演示。 Authentication API 是一个特殊的 API，与特定产品无关，用于身份验证测试。它接受任何有效的 JSON 对象，并简单地使用相同的 JSON 对象进行响应，类似于 echo 命令。

和其它 API 一样，Authentication API 也建立在网关服务之上，因此如果成功地调用 Authentication API，则集成其它 API 将非常容易。

操作步骤

接入 ZOLOZ API

添加库

ZOLOZ Java 库发布在 Maven 中央存储库上。以下步骤演示了如何使用公共 Java 库与网关服务交互并调用 API。

通过将以下依赖项添加到 POM 文件中，在您的 maven 项目中引入该库。

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

导入 OpenApiClient 类。

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

实例化一个 OpenApiClient 实例并使用 API 凭据配置该实例，包括客户端 ID、ZOLOZ 交易公钥、编码的商家交易私钥。

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);  

对于 ZOLOZ 网关 URL的更多信息，请参见选择开发环境和服务端。

调用 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);

辅助脚本

获取辅助脚本

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

在 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}'

-c 指的是您的客户端 ID。上面片段中使用的“2188000123456789”是一个示例值，您需要将其替换为从 ZOLOZ 门户获得的客户端 ID。
-P 指的是您的商家私钥。上面代码段中的“merchant_private_key.pem”是私钥的示例值。您需要将其替换为商家私钥的真实路径，其中对应的公钥已在 ZOLOZ 门户中注册。
-K 指的是 ZOLOZ 公钥的内容。上面片段中的“MIIBIj...QIDAQAB”是 ZOLOZ 公钥的示例值。您需要将其替换为从 ZOLOZ 门户获取的公钥。
-a 指的是 API 的路径。在上面的代码片段中，为演示指定了身份验证测试 API。
-d 指的是请求的内容。

除了上面列出的选项外，您还可以根据需要添加以下选项：

-e ：禁用加密
-i ：跳过响应签名验证

验证结果

如果您是自己实现网关协议的，则建议您按照以下说明使用 ZOLOZ 辅助程序脚本来验证接入结果。

调用您自己的实现来调用 API 并记录流程详细信息，包括：

通话中使用的请求时间
用于请求加密随机生成的 AES 密钥
加密的请求内容
请求签名

调用辅助脚本以使用相同的请求调用相同的 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 调用过程的详细输出。

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

将步骤 1 中记录的流程详细信息与步骤 2 中打印的详细输出进行比较。

验证请求加密。检查您的加密请求内容是否与图1（2）中的请求正文中显示的内容相同。
注意：通常 RSA 加密的实现会添加随机信息以避免可能的攻击，因此正如预期的那样，您的实现会为 AES128 密钥加密产生不同的结果。但是，您可以比较请求内容加密，因为它是可验证的。
验证请求签名。检查你在请求头中填写的请求签名是否与图1（3）中urlencoded请求签名字段中显示的一致。
验证响应签名。确认图1 （4）的响应签名域显示的签名是否可以通过你的实现对目标内容的签名验证，目标内容显示在图1(4)的待验证响应内容域。
验证响应解密。检查您自己的实现是否可以将加密的 AES128 密钥（图 1（5）中的响应加密对称密钥字段）解密为相同的 AES128 密钥（图 1（5）中的响应对称密钥字段）。并检查您的实现是否可以将加密的响应内容（图 1（5）中的响应正文字段）解密为相同的纯内容（图 1（5）中的响应内容字段）。