编码和哈希处理字符串

Studio 支持多个函数，您可以使用这些函数对脚本中的数据进行编码或哈希处理。编码和哈希处理均将数据转换为不同的格式。数据变化的方式和您可以用它能做的事情是不同的：

  • 编码：此过程将数据转换为可以在脚本中使用或传递到其他系统的格式。编码使用的方案或方法通常是公开的。因此，转换并不安全。然而，编码的目的不是为了保护数据，而是为了确保它可以在接收系统上正确使用。可以反转编码以将数据还原为原始格式。
  • 哈希处理：这是一个将数据转换为固定长度字母数字字符串的单向过程。散列字符串有时也称为散列。散列通常用于验证数据的完整性。当两个相同的字符串使用相同的算法进行哈希处理时，其哈希值是相同的。如果用相同算法创建的两个哈希值不匹配，则表明原始字符串也是不同的。此过程可用于验证安全数据，例如数字签名或密码，而无需以纯文本形式传递敏感数据。

此外，Studio 支持使用 OAuth 进行授权。这是一种为 CXone 与其他系统之间的交互提供安全性的方法。

本页面提供有关可在 Studio 脚本中使用的函数的信息，以对字符串进行编码或散列，或者使用 OAuth 设置授权流程。它不提供有关如何实施这些解决方案的信息。有关这些函数使用的算法的更多信息，请参阅互联网工程任务组 (IETF) 网站。

哈希处理是不可逆的。谨慎使用任何对字符串进行哈希处理的函数，并确保在将其用于实时数据之前了解如何实现它。

RestProxy

对 Studio 中的字符串进行编码和哈希处理需要使用 RestProxy，该服务允许您使用脚本访问 RESTful API。它还允许您访问用于编码和哈希处理的函数。在编码或哈希处理字符串时可使用的函数示例片段均包含以下访问 RestProxy 的语句：

ASSIGN restProxy = new UCN.Data.RESTProxy()

请务必按照所示方式在变量赋值中包含 UCN.Data.RESTProxy()。RESTProxy() 函数允许您访问用于编码和哈希处理数据的函数。

示例

我们提供了每个函数的 Snippet 代码示例，供您在脚本中使用。该代码也可以从描述每个功能的表中的帮助页面中复制。

  1. 下载示例脚本 ZIP 文件。
  2. 解压缩 ZIP 文件的内容。其中包含两个脚本文件：

    • EncodeAndHashScriptExample.xml，其中包含一个可以在其中测试函数的示例脚本。

    • ExampleSnippetActions.xml，其中此页面上的每种算法均包含一个代码段操作。每个代码段均包含该函数的示例代码。

  3. 将两个 XML 文件导入到 Studio 中。
  4. 从 ExampleSnippetActions.xml 文件中的代码段操作中复制要使用的函数的代码片段。
  5. 将复制的代码粘贴到 EncodeAndHashScriptExample.xml 文件中的代码段操作中。
  6. 设置模拟交互并单击 Start with Trace。您还可以在代码段编辑器窗口中使用调试器。这两个选项都允许您查看代码片段中变量内容的变化。

字符串编码函数

编码将数据转换为不同的格式。您可以使用它来传输大量数据，或传输所使用的协议无法传输的数据。编码数据可以转换回其原始格式。

您可以使用两个函数对字符串进行编码。两者都使用 Base64 方案对数据进行编码。

函数名称 描述
EncodeBase64(string)

某些协议无法传输二进制数据。您可以使用该函数将 string 参数传递的二进制数据转换为可传输的格式。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodeThis = "This is the source data."
ASSIGN hashB64 = restProxy.EncodeBase64(encodeThis)
EncodeBase64Url(URL)

Base64 函数可用于对 Web 应用程序中的 URL 进行编码。然而，编码中使用了三个特殊字符，必须在 URL 中对它们进行不同的解析。字符为加号 (+)、正斜杠 ( /) 和等号 ( = )。您可以使用 EncodeBase64Url 函数对作为 URL 参数实参传递的 URL 进行正确编码。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodeThis = "https://example.com"
ASSIGN hashB64url = restProxy.EncodeBase64Url(encodeThis)

字符串解码函数

使用此函数可解码使用 EncodeBase64 函数编码的字符串。

函数名称 描述
DecodeBase64 (string)

此函数将编码数据 (string) 恢复为其原始格式。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodedString = "234sdf"
ASSIGN decodedString = restProxy.DecodeBase64(encodedString)

使用密钥对字符串进行哈希处理的函数

哈希函数使用数学计算来生成固定长度的输出字符串。输出字符串称为哈希，可用于验证哈希数据的真实性。您可以使用它们来验证密码、数字签名等。例如，您可以存储密码的哈希版本。当用户输入密码时，您可以对其进行哈希处理，并将其与您存储的密码的哈希版本进行比较。如果它们相同，则密码正确。

本节中描述的哈希函数都是键控哈希算法。它们使用基于哈希的消息验证代码 (HMAC) 算法。每个算法都会产生特定长度的散列输出。HMAC 算法使用密钥和哈希函数的组合来生成哈希输出。HMAC 流程：

  1. 将密钥与消息数据混合。
  2. 使用哈希函数对结果进行哈希处理。
  3. 再次将哈希值与密钥混合。
  4. 再次应用哈希函数。

哈希函数是单向的。这意味着它们无法撤消。因此，这些函数不能用于加密数据。加密也使用密钥，就像本节中的哈希函数一样。然而，加密算法不包括散列算法，并且是可逆的。Studio 不提供任何加密功能。

您的组织有责任获取密钥并与接收实体或系统共享。

保护密钥的安全。如果密钥丢失，则用它散列的所有数据将不再可用。即使字符串相同，也无法比较使用两个不同键散列的字符串。

函数名称 描述
EncodeHS256(stringText, secretKey)

此函数使用 HMACSHA256，这是一种从 SHA-256 哈希算法构建的密钥哈希算法，并用作基于哈希的消息身份验证代码 (HMAC)。它生成长度为 256 位的散列输出，由源数据 stringText 和 secretKey 组成。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS256 = restProxy.EncodeHS256(hashThis, key)
EncodeHS256NoBaseEncoding(stringText, secretKey)

该函数与 EncodeHS256 相同，但不包含 Base64 编码。哈希输出由源数据 stringText 和 secretKey 组成。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS256NoB64= restProxy.EncodeHS256NoBase64Encoding(hashThis, key)
EncodeHS384(stringText, secretKey)

此函数使用 HMACSHA384，这是一种基于 SHA-384 哈希算法构造的密钥哈希算法，并用作基于哈希的消息身份验证代码 (HMAC)。它生成长度为 384 位的散列输出，由源数据 stringText 和 secretKey 组成。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS384= restProxy.EncodeHS384(hashThis, key)
EncodeHS512(string Text, secretKey) 此函数使用 HMACSHA512 ，这是一种从 SHA-512 哈希算法构造的密钥哈希算法，并用作基于哈希的消息身份验证代码 (HMAC)。它生成长度为 512 位的散列输出，由源数据 stringText 和 secretKey 组成。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS512 = restProxy.EncodeHS512(hashThis, key)

使用令牌和 OAuth 进行授权的函数

OAuth 和使用 JSON 网络令牌（JWT 或令牌）的基于令牌的身份验证是在应用程序中构建身份验证流的两种标准。您可以将它们结合使用，以确保客户端应用程序能有效验证用户详细信息。当身份验证服务器通过 OAuth 成功验证用户凭据时，它还必须将用户详细信息传输给客户端应用程序。

要使用这些功能，必须有一个可用的身份验证服务器。使用令牌时，OAuth 服务器会在授权流程完成后将令牌发送到客户端应用程序。令牌包含最终用户的信息。

脚本中可用的函数结合了用于用户和客户端身份验证的 OAuth 标准和 HMACSHA256 哈希算法。OAuth 标准在 RFC7523 中定义，它与 Studio 中的函数名称相同。

您可以在 Studio 脚本中使用以下函数，将授权流与 OAuth 和令牌结合起来：

  • RFC7523GrantWithHS256(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

  • RFC7523GrantWithHS256Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

  • RFC7523GrantWithHS384(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

  • RFC7523GrantWithHS384Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

  • RFC7523GrantWithHS512(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

  • RFC7523GrantWithHS512Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

令牌由三部分组成：标头、有效负载和签名。这些函数有多个参数，提供用于创建这些部件的数据。参数定义如下表所示：

参数 类型 描述
apiURL 字符串 您要连接的 API 端点的 URL。
key 字符串 您希望脚本在使用此函数进行哈希处理时使用的密钥。
iss 字符串 令牌的发行者。
sub 字符串 令牌的主题。
aud 字符串 令牌的预期用户。通常，这是客户端要访问的授权服务器。
jwtHeaderData 动态数据 您希望包含在令牌标题中的数据。
jwtPayloadData 动态数据 保存您需要包含在令牌中的任何有效负载的键值对。这可能包括令牌的到期时间。这在下面的示例代码段中显示为 payload.exp。
queryParams 动态数据 保存要包含在令牌中的查询参数的键值对。这仅包含在扩展函数中。
requestHeaders 动态数据 保存请求头信息的键值对。这仅包含在扩展函数中。

示例脚本中的 Snippet 操作包含以下代码：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN key = "key"
ASSIGN url = "https://example.com"
ASSIGN iss = "some issuer"
ASSIGN sub = "some subscriber"
ASSIGN aud = "some audience"

DYNAMIC headerData
DYNAMIC payloadData
DYNAMIC queryParams //only in the Extended functions
DYNAMIC requestHeaders //only in the Extended functions
payloadData.ist=155533969
payloadData.exp=155533969

ASSIGN hash=restProxy.RFC7523GrantWithHS256(url, key, iss, sub, aud, headerData, payloadData)
ASSIGN hash=restProxy.RFC7523GrantWithHS256Extended(url, key, iss, sub, aud, headerData, payloadData, queryParams, requestHeaders)

示例脚本包含每个可用函数的代码。此示例仅涵盖了六个可用函数中的两个。