签名哈希生成

如需调用 zeuz 基础 API,您首先必须登录 zeuz。登录后,您还需要对每个 API 请求进行认证,在请求中附上签名哈希,签名哈希是您 API 请求的认证凭证。

请使用 zeuz 返回给您登录函数的数据生成签名哈希。

登录设置和签名哈希生成都必须包含在脚本中。您既可以在登录脚本中生成签名哈希,也可以在 API 请求脚本中生成签名哈希,具体取决于您的设置选择。

下方的步骤和示例代码向您展示了签名哈希的生成脚本中必须包含的内容,其中涵盖了 API 认证概览 中的任务 4. 生成用于附在 API 请求上的签名哈希

关于 API 认证概览 中的任务 3. 登录 zeuz 并生成会话密钥 和任务 4. 生成用于附在 API 请求上的签名哈希 的完整工作示例,请参阅 示例代码

警告:签名哈希脚本不是必须的。

请参阅下方的 我是否需要签名哈希脚本?

资讯:我是否需要签名哈希脚本?

在开始之前,请参阅 API 简介,检查您是否可以使用 SDK 下载中提供的封装之一或 Go SDK 来访问 zeuz API。如果您可以使用封装或 Go SDK,就不需要自己编写认证脚本。

在下列情况下,必须直接访问 zeuz 基础 API:

  • 您不使用 Unity、虚幻引擎或 Go 开发游戏。

  • 您想调用 zeuz API 为您的游戏建立工具,例如,将您的游戏集成到 CI/CD 管道中。


签名哈希生成流程

下列图片使用示例代码中的函数名和变量名,概述了签名哈希的生成流程:

图像:签名哈希生成流程

图像:签名哈希生成流程

前期准备

在生成签名哈希之前,请确保您已经:

  • 阅读 zeuz API 的介绍信息。

    请参阅 API 简介

  • 阅读 zeuz 基础 API 的认证过程,了解需要完成哪些设置。

    请参阅 API 认证概览

  • 创建脚本来登录 zeuz 并生成会话密钥。

    详情请参阅 API 登录

如何生成签名哈希

请使用来自 登录脚本 的会话密钥,加上新的 nonce 和新的时间戳,生成另一个称为签名哈希的哈希密码。

然后将签名哈希附到您的 API 请求上,直至会话密钥过期 (会话密钥在创建后的 24 小时过期)。

C++ 代码示例包含下列内容:

  • 生成一个签名哈希
  • auth_check API 端点发送一个 JSON 数据包
  • 解析 invalid_sessionsession_expired 错误的返回值

如果该登录会话有效,您可以继续并进一步发送 API 请求。反之,如果该登录会话无效,您需要重新登录。

C++ 代码示例如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
#include <jsoncpp/json/writer.h>
#include <jsoncpp/json/reader.h>

// 检查时间戳是否有效。
bool ZeuzApi::check_session(long now, LoginData login_data) {
    // 检查过期时间是否在 60 秒后。
    if (now > (login_data.ValidThru - (60 * 1000000))) {
        return false;
    }
    return true;
}

// 根据 auth_check API 端点调整格式。
// 请参阅 API 参考文档:doc.zeuz.io/reference#auth_check
std::string format_to_json_payload(std::string request_id, std::string session, std::string sign_hash, long time, std::string session_id) {
   Json::Value data;
   Json::FastWriter writer;
   data["ReqID"] = request_id;
   data["Session"] = session;
   data["SignHash"] = sign_hash;
   data["Time"] = Json::Int64(time);
   data["Data"] = session_id;
   return writer.write(data);
}

// 调用 auth_check API 端点,
// 验证登录会话是否有效。
bool ZeuzApi::auth_check(LoginData login_data) {
   auto now = zeuz_now();
   if (!check_session(now, login_data)) {
       // 如会话过期,则永久失效。
       return false;
   }
   auto request_id = generate_nonce(10);

    // 生成签名哈希。
auto sign_hash = zeuz_hash(std::to_string(now) + request_id + login_data.SessionKey);

    // 将签名哈希和其他请求数据添加到请求。
auto data = format_to_json_payload(request_id, login_data.SessionId, sign_hash, now, login_data.SessionId);
   response = post_request("https://zcp.zeuz.io/api/v1/auth_check", data);

   // 解析 JSON 响应并提取响应中的值。
   Json::Reader reader;
   Json::Value response_json;
   if (!reader.parse(response, response_json)) {
      // 注意:在生产代码中,使用 C++ 异常作为替代。
      throw std::string("could not parse response data ( " + response + ")");
   }

   // 检查是否设置错误字段。
   auto error = response_json["Error"].asString();
   if (!error.empty()) {
      if (error.rfind("invalid_session", 0) == 0 ||
          error.rfind("session_expired", 0) == 0) {
          // 如会话过期,需重新登录。
          return false;
      } else {
          throw std::string("could not check session (" + response + ")");
      }
   }

   // 如没有收到错误信息,则会话有效。
   return true;
}

下一步:把签名哈希附在 API 请求上

现在您已生成签名哈希,可以把它附到您的 API 请求中。更多阐释,请参阅 示例代码 中的示例四。

如需一些规避会话密钥过期限制的方法,请参阅 设计考量


2021年8月9日 该文档已更新并通过审校:添加生成签名哈希的流程图

2021年5月12日 该文档已创建并通过审校


最近更新时间: October 20, 2021 (a9e55e2d)