要在 Support+Chat 帐户和 第 4 阶段 Chat 帐户中使用 Chat API,您需要生成 OAuth 访问密钥以对 API 请求进行身份验证。不支持基本身份验证。然而,第一次生成密钥可能会有些混乱,因此本教程提供了如何手动生成密钥的逐步示例。完成后,您应有一个密钥,可在 Chat API 请求中使用它来读取和写入数据。
如果您正在构建应用程序,则应将密钥生成功能构建到您的应用中,以使该过程自动化。
有两种方法可以为 Chat API 创建访问密钥 —— 一种用于测试环境的更快、更方便的方法(使用“隐式”授予流程),另一种用于生产环境的更长、更正式的方法(使用“授权代码”授予)流)。本教程涵盖了两者。
条件
本教程适用于已应用上述文章中提及的所有更改的整合 Chat 帐户。此功能目前正在逐步推出,因此某些帐户可能会先于其他帐户需要它。如果您不确定您的帐户是否已收到所有的更改,请联系我们的支持团队,他们可以为您确认。
注意:帐户更改的一个副作用是需要重新创建 OAuth 密钥。如果您在更改到达您的帐户之前完成了本教程,那么之后您将需要再次完成这些步骤。
程序
OAuth“隐式”授予工作流程 包括以下步骤:
- 创建 OAuth API 客户端
- 使用步骤 1 中的信息完成 OAuth 隐式授予工作流程以获取密钥
创建 OAuth API 客户端
首先,我们需要一个 API 客户端。前往 Zendesk Chat > 帐户 > API 和 SDK,然后单击 添加 API 客户端 按钮。为您选择的客户和公司输入一个名称,并为重定向 URL 输入http://localhost:8080
。它应如下所示:
单击“ 创建 API 客户端 ”以完成设置。您将看到一个带有客户端 ID 和密钥的弹出窗口。非常重要:客户端密钥仅显示一次,因此请记下它以供日后使用。如下所示:
现在我们的 API 客户端已准备就绪,请记下您的客户端 ID 和客户端密钥,然后单击“ 好,知道了”。我们现已准备就绪,可以完成 OAuth 授权工作流程。
完成 OAuth 隐式授予工作流程以获取密钥
此方法使用 OAuth“隐式”授权流程。另一种方法是使用 OAuth“授权代码”授权流程(如下所示)。如果手动进行,此方法比稍后显示的授权代码授予流程步骤更少,更方便。
1.按照上面的“创建 OAuth API 客户端”步骤进行操作
2.从 OAuth 客户端收集此信息
- 客户端 ID:CLIENT_ID
- 您的 Zendesk 子域名
3.使用您自己的 CLIENT_ID 和 SUBDOMAIN 设置以下 URL 的格式,将其粘贴到新的浏览器标签中,然后按 Enter。
https://www.zopim.com/oauth2/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN
注释:
- 如果 Chat OAuth 客户端只有一个重定向 URL 值,则传递重定向 URL 值是可选的。系统将默认使用 OAuth 客户端的一个重定向 URL 值。
- 如果 OAuth 客户端有多个重定向 URL 值,则需要传递一个 redirect_uri 值。如果传递了一个 redirect_uri 值 , 那么它需要进行 URL 编码。在上面的例子中,可选的重定向参数为: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://www.zopim.com/oauth2/authorizations/new
,并添加一些查询参数以传递上述信息。这次我们需要:
-
response_type
: 这将始终是code
-
redirect_uri
:授予访问权限后我们将被重定向到的地方,http://localhost:8080
对于我们的教程 -
client_id
:特定于您,如前所述 -
scope
:此密钥具有的访问权限,我们将选择read
和write
- 如果对 Chat Conversations API使用密钥,还包括“chat”范围。
- 如果对 Chat Conversations API使用密钥,还包括“chat”范围。
-
subdomain
:您的 Zendesk 子域名
把它和 URL 编码放在一起,您将得到一个如下所示的最终 URL:
https://www.zopim.com/oauth2/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://www.zopim.com/oauth2/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
请记住:您应该已经有 CLIENT_ID
和 CLIENT_SECRET
现在,但我们没有 AUTH_CODE
刚刚。
3.获取您的授权代码
现在转到我们在第 1 步中生成的 URL。您将看到这样的页面:
单击“ 允许 ”以授予访问权限,您将被重定向到重定向 URL。它看起来像是一个损坏的页面,但重要的是查看 URL 以了解授权代码是什么,即之后的所有内容 ?code=
复制该代码,让我们为最后一步做好准备!授权代码仅在短时间内有效。如果您等待超过几分钟,则可能需要重新运行上述步骤以获取新的代码值。
4.进行 cURL 调用以获取您的密钥
参考我们在第 2 步中构建的 cURL 调用,如下所示
curl https://www.zopim.com/oauth2/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://www.zopim.com/api/v2/chats -H "Authorization: Bearer TOKEN"
替换 TOKEN
以及在第 4 步中检索到的内容。
其它信息
机密 client_type
上面的部分演示了“隐式”授权类型和“授权代码”授权类型。Zendesk Chat 还支持另外两种授权类型:“password”和“client_credentials”。参考文档中的 机密授权类型对此进行了更多描述。
对于管理员和专员用于报告指标之类的 API 调用,获取具有这些授权类型之一的 OAuth 密钥可能更可取。您需要将 client_type
为“机密”。默认情况下,此值设置为“public”。这只能通过 API 完成,可通过以下方式实现:
1.获取客户端 ID
首先,我们需要您的新客户端的 ID。您可以使用新密钥获取此密钥,方法如下:
curl https://www.zopim.com/api/v2/oauth/clients -H "Authorization: Bearer TOKEN"
这将显示您所有的客户。您可能只有一个,但如果有很多,则应选择要更新的一个,并记下其 ID。
2.更新 client_type
现在您已获得客户端的 ID,您可以运行以下 cURL 调用来更新 client_type
属性:
curl https://www.zopim.com/api/v2/oauth/clients/ID -d '{"client_type": "confidential"}' \
-X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"
完成后,您的密钥可用于受限端点。
翻译免责声明:本文章使用自动翻译软件翻译,以便您了解基本内容。 我们已采取合理措施提供准确翻译,但不保证翻译准确性
如对翻译准确性有任何疑问,请以文章的英语版本为准。