要在 Support+Chat 帐户和 第 4 阶段 Chat 帐户中使用 Chat API，您需要生成 OAuth 访问密钥对 API 请求进行身份验证。不支持基本身份验证。但是，首次生成密钥可能会有点困惑，因此本教程将通过示例逐步说明如何手动生成密钥。完成后，您应有一个密钥，可在 Chat API 请求中使用该密钥来读取和写入数据。

如果您要构建应用程序，则应将密钥生成功能构建到您的应用中，实现此流程自动化。

有两种方法可以为 Chat API 创建访问密钥：一种更快、更方便，用于测试环境（使用“隐式”授权流程）；另一种更长、更正式，用于生产环境（使用“授权代码”授权）。流程）。本教程将针对这两方面进行介绍。

条件

本教程适用于已应用上一文章中所述所有更改的整合 Chat 帐户。此功能目前正在逐步推出，因此某些帐户可能会先于其他帐户需要。如果您不确定您的帐户是否已收到所有的更改，请随时联系我们的支持团队，他们会为您进行确认。

注意：帐户更改的一个副作用是需要重新创建 OAuth 密钥。如果您在更改到达您的帐户之前已完成本教程，则之后您将需要再次执行这些步骤。

步骤

OAuth“隐式”授权工作流程 包含以下步骤：

  1. 创建 OAuth API 客户端
  2. 使用第 1 步中的信息完成 OAuth 隐式授予工作流程，以获取密钥

创建 OAuth API 客户端

首先，我们需要一个 API 客户端。前往 Zendesk Chat > 帐户 > API 和 SDK，然后单击 添加 API 客户端 按钮。输入所选客户和公司的名称，为重定向 URL 输入http://localhost:8080更新。它应如下所示：

单击 Create API Client（创建 API 客户端）完成设置。您将看到一个弹出窗口，其中包含客户端 ID 和密钥。非常重要：客户端密钥仅显示一次，因此请记下它以供以后使用。如下所示：

现在我们的 API 客户端已准备就绪，请记下您的客户端 ID 和客户端密钥，然后单击 好的，知道了。我们现已准备就绪，可以完成 OAuth 授权工作流程。

完成 OAuth 隐式授予工作流程以获取密钥

此方法使用 OAuth“隐式”授权工作流程。另一种方法是使用 OAuth“授权代码”授予工作流程（如下一部分所示）。如果手动进行，与稍后显示的授权代码授予流程相比，此方法步骤更少，更方便。

1.按照上面的“创建 OAuth API 客户端”步骤进行操作。

2.从 OAuth 客户端收集此信息

  • 客户端 ID：CLIENT_ID
  • 您的 Zendesk 子域名

3.使用您自己的CLIENT_ID 和 SUBDOMAIN 来设置以下 URL 的格式，将其粘贴到新的浏览器标签中，然后按 Enter 键。

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

注意：

  • 如果 Chat OAuth 客户端只有一个重定向 URL 值，则可以选择传递 redirect_uri 值。系统将默认使用 OAuth 客户端的重定向 URL 值。
  • 如果 OAuth 客户端有多个重定向 URL 值，则需要传递一个 redirect_uri 值。如果传递了 redirect_uri 值 ，则 需要对其进行 URL 编码。在上面的例子中，可选的 redirect 参数为：redirect_uri=http%3A%2F%2Flocalhost%3A8080

4.随即进行通话，可能要求您登录并选择“允许”以生成密钥。

如果调用成功，您浏览器的地址字段将包含新的 OAuth 密钥（作为 access_token 值返回）。

尽管浏览器主窗口中显示了看似错误的消息，但如果浏览器的 URL 字段中返回“access_token”，则说明操作成功！

这里是工作流程演示：

 

生成密钥的更长的替代方法

这些步骤与上一节一样创建一个密钥，但演示了 OAuth“授权代码”授予流程。记下您的 OAuth 客户端详情，这些信息将在下文中使用。

将使用占位符而不是真实数据 —— 请记住，您的 OAuth 客户端密钥相当于您 Chat 帐户的密码，因此应格外小心。

  • 客户端 ID： CLIENT_ID
  • 客户端密钥： CLIENT_SECRET
  • 重定向 URI： http://localhost:8080
  • 子域名：您的 Zendesk 子域名；例如，如果您的帐户位于 niall.zendesk.com，此值为 niall
  • 授权代码： 我们还没有

1.准备第一个 URL

我们将在这里创建一个 URL 以请求授权代码。您需要前往 https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new，并添加一些查询参数以传递上述一些信息。这次我们需要：

  • response_type：始终为 code
  • redirect_uri：我们将在授予访问权限后重定向到哪里，http://localhost:8080 以获得教程的
  • client_id：特定于您，如之前所述
  • scope：此密钥将具有的访问权限，我们将选择read 和 write
    • 如果针对 Chat 对话 API使用密钥，则还包括“chat”范围。
  • subdomain：您的 Zendesk 子域名

总之，再进行 URL 编码，您会得到一个如下所示的最终 URL：

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

与 CLIENT_ID 和 SUBDOMAIN 区别仅在于您自己的 URL。

2.准备 cURL 通话

在实际访问该 URL 之前，让我们先构建稍后将运行的 cURL 调用。这次我们需要：

  • grant_type：始终为 authorization_code
  • code：这将在我们允许 URL 访问后获取
  • client_id：您的客户端 ID
  • client_secret：您的客户端密钥
  • redirect_uri：同上一步 - http://localhost:8080
  • scope：同上一个步骤相同 - read 和 write

将所有这些放在一起后，我们会得到一个如下所示的命令：

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

请记住：您应该已经有 CLIENT_ID 和 CLIENT_SECRET 现在，但我们没有 AUTH_CODE 还没有。

3.获取授权代码

现在转到我们在第 1 步中生成的 URL。您将看到这样的页面：

单击 允许 以授予访问权限，您将被重定向到重定向 URL。它看起来像是一个损坏的页面，但重要的是要在 URL 中查看授权代码，即之后的所有内容 ?code=

复制该代码，让我们为最后一步做好准备！授权码短期内有效。如果您等待超过几分钟，可能需要重新运行上述步骤以获取新的代码值。

4.进行 cURL 调用以获取密钥

返回到我们在第 2 步中构建的 cURL 调用，它如下所示

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

替换AUTH_CODE 替换为第 3 步中的代码，然后从终端应用程序运行命令。您将收到 JSON 对象形式的响应，如下所示：

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5.测试新密钥

建议您先进行测试以确认其是否如预期工作，因此我们现在就可以进行此操作。最简单的方法是直接拨打 GET 收件人： /api/v2/chats查看帐户信息：

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

替换 TOKEN 替换为第 4 步中检索的内容。 

其它信息

机密 client_type

上述部分演示了“隐式”授权类型和“授权代码”授权类型。Chat API 还支持使用客户端凭证的保密授予类型。参考文档中的 机密授权类型对此有更多描述。

对于管理员和专员用于报告指标等用途的 API 调用，最好获取机密授予类型的 OAuth 密钥。您将需要设置 client_type 为“机密”。默认情况下，此值设置为“public”。这只能通过 API 完成，可通过以下方式实现：

1.获取客户端 ID

首先我们需要您的新客户端的 ID。您可使用新密钥通过以下调用获取此密钥：

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

这将显示您所有的客户端。可以只有一个，但如果您有多个，您应挑选一个要更新的，并记下其 ID。

2.更新 client_type

有了客户端 ID 后，即可运行以下 cURL 调用来更新客户端 ID client_type 属性：

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

该操作完成后，您的密钥可用于受限端点。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。

由 Zendesk 提供技术支持