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 vairables
String 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."
}

1. 单击Send发送请求。

5. 返回测试结果。
   

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