API 和脚本

本帮助页面上的信息同时适用于 CXone Studio 和 Desktop Studio。

在 Studio 脚本中，您可以连接到使用 SOAP 或 RESTful API 标准的 Web 服务。

支持的选项

Studio 支持以下连接 Web 服务的方式：

选项 详细信息
REST API Studio 操作

REST API Studio 操作可使您从脚本进行 RESTful API 调用。此方法：

  • 与在 SNIPPET 操作中进行 RESTful 调用相比，可以处理更高的负载，尤其是大规模负载。
  • 是在脚本中进行 API 调用的首选方法。
  • 是在您的调用包含 JSON 时使用的选项。

Integration Hub

Integration Hub是 CXone 中的 应用，您可以在其中配置要在 平台 中使用的身份验证和 API 请求。它还允许您以加密格式存储敏感数据，例如密码或密钥，以便在脚本中使用。

CONNECTREQUEST 操作和 CONNECTAUTH 操作可使您使用配置的身份验证详细信息和您脚本中的请求。
CXoneAPI Studio 操作 Studio 有许多可使您从脚本调用 CXone API 的 API 操作。并非每个 CXone API 都可作为操作，但当有一个可用时，您应使用它，而不是其他方法。您可以在 Desktop Studio 中的“框架”选项卡的 API 部分以及 CXone Studio 的“API 操作”选项板中找到这些 API 操作。
SNIPPET 操作

您可以在 SNIPPET 操作中编写代码，以便从脚本连接到 RESTful 或 SOAP Web 服务。这不是进行 REST 调用的推荐方法，因为它会减慢联系处理速度。但是，如果出现以下情况，则必须使用此方法：

  • 您的调用包含 XML。
  • 您正在连接到 SOAP 服务。
CRM 工作流集成 当您需要对组织的 CRM 进行 API 调用时，请设置 CRM关闭 管理联系人、销售信息、支持详细信息和案例历史记录等事项的第三方系统。 工作流集成。在 CXone Agent、CXone Agent Embedded 和 CXone Agent Integrated 中支持此功能。

已返回数据大小的限制

CXone 平台 可使 REST API 返回最多 32 KB 的数据。此限制可防止群集不稳定和中断。它被严格执行。

此限制适用于连接到 Web 服务的任何方法，包括 REST API 操作和使用 SNIPPET 操作进行调用。如果可以，请对 REST API 使用 REST API 操作，而不是 SNIPPET 操作。REST API 的返回限制为 32 KB，但与 SNIPPET 方法相比，它能够处理更重的负载。

要减少返回数据的大小：

  • 筛选 API 响应中的数据。 例如，如果使用 NICE 报告 API 获取联系人，则可以按联系人的 startDate 和 endDate 筛选结果。此 API 调用还允许返回并限制最大项目数。请参阅您正在调用的 API 的文档，确定您可以使用什么筛选。
  • 更新 API 请求，以便仅返回您需要的数据。 例如，如果使用 NICE 报告 API 获取联系人，则可以使用 contactId 或 agentId 字段仅返回相关数据。请参阅您正在调用的 API 的文档，确定您可以使用哪些数据限制。

如果无法执行上述任一选项，请构建中间件。

-1 错误代码

-1 错误代码是一个内部代码，用于确定 API 调用已出错。具体来说，此代码表示将不会返回 HTTP 状态代码的情况，或者返回了 HTTP 状态代码但无法将其传递给脚本的情况。

-1 错误代码附带的状态描述可帮助您确定此问题。此代码附带的状态描述包括：

  • 请求已中止：操作超时。 该请求可能已被处理，也可能未被处理。应在设置循环以响应 -1 状态代码之前进行验证。您可能需要使用 ProxyTimeoutSeconds 属性来更改此调用中的超时设置。

  • JSON 基元无效。 JSON 解析器对响应感到困惑。响应可能包含无效字符或者不是 JSON。通常，当以 HTML 形式发送响应时会发生此错误。您可以在代码片段调试器中测试响应。REST API 响应不是有效的 JSON 或 XML 一个方块，箭头从中心指向右上角。 知识库文章可能会提供帮助。

  • 根级别的数据无效。 XML 解析器对响应感到困惑。响应可能包含无效字符或者不是 XML。通常，当以 HTML 形式发送响应时会发生此错误。REST API 响应不是有效的 JSON 或 XML 一个方块，箭头从中心指向右上角。 知识库文章可能会提供帮助。

  • “doctype”是一个意外令牌。预计令牌是“DOCTYPE”。请参阅此列表中的根级别的数据无效。

  • 第 x 行位置 x 上的“br”开始标记与“body”的结束标记不匹配。 请参阅此列表中的根级别的数据无效。

  • 底层连接已关闭：发送时发生意外错误。 通常这意味着 TLS 握手存在问题。这也可能是由以下方面导致的：防火墙上未打开 IP 或端口；使用不受支持的旧 TLS 版本；证书无效或过期；将 IP 地址与 HTTPS 结合使用；或者类似问题。使用接收服务器端的防火墙日志对此响应进行故障排除。

  • 底层连接已关闭：无法建立 SSL/TLS 安全通道的信任关系。 请参阅此列表中的底层连接已关闭：发送时发生意外错误。

  • 请求被中止：无法创建 SSL/TLS 安全通道。 请参阅此列表中的底层连接已关闭：发送时发生意外错误。

  • 响应太大。(> 32 KB)。响应包含超过 32 KB 的数据。发生这种情况时，响应将被丢弃，因为系统无法在一个变量中存储超过 32 KB 的数据。必须修改或筛选响应，以减少返回的数据量。