创建连接以与外部服务整合

我的服务模式是什么？

Suite

任意服务模式

快速查看：管理中心 > 应用和整合 > 连接 > 连接

连接使您可以安全地存储服务或系统（例如 Slack 或 Shopify）的 API 凭证。您可以在自动协助操作中使用连接对 REST API 调用进行身份验证。您必须是管理员才能创建连接。

注意：本文章中的说明也适用于使用旧版智能机器人生成器调用 API 步骤的帐户。

本文章涵盖以下主题：

• 关于连接
• 创建连接
• 允许的域名
• API 密钥的 HTTP 标头

关于连接

连接支持以下 API 身份验证方法：

• API 密钥
• 基本身份验证
• 不记名密钥
• OAuth 2.0

此身份验证方法决定了连接存储的凭证类型。例如，基本身份验证连接存储用户名和密码。创建连接后，您无法更改其身份验证类型。

不同的 API 支持不同的身份验证方法。要确定 API 调用的适当身份验证方法，请查阅 API 文档。

身份验证类型的 HTTP 标头

当您在自动协助操作中使用连接对 API 调用进行身份验证时，Zendesk 会在 HTTP 标头中传递连接的凭证。Zendesk 根据连接的身份验证类型确定此标头。

身份验证类型	HTTP 标头
API 密钥	在创建连接时设置。请参阅 API 密钥的 HTTP 标头
基本身份验证	Authorization: Basic
不记名密钥	Authorization: Bearer
OAuth 2.0	访问密钥以 Authorization: Bearer 格式发送到服务

有关在操作中使用连接的更多信息，请参阅创建和管理自动协助操作。

创建 OAuth 客户端

OAuth 连接存储服务或系统（例如 Slack、Shopify 或 Zendesk）的 OAuth 2.0 访问密钥。

在使用 OAuth 2.0 身份验证类型创建连接之前，您必须配置 OAuth 客户端。配置 OAuth 客户端时，您需要来自外部系统的 OAuth 配置界面或管理员门户的客户端 ID、客户端密钥、授权 URL、密钥 URL 和范围等凭证。这些凭证是您在外部系统注册客户端应用程序（例如 Zendesk）时生成的。具体步骤因外部服务而异。如果需要，将客户端的回拨 URL 设置为“https://zis.zendesk.com/api/services/zis/connections/oauth/callback”。

注意：我们仅支持与符合 OAuth 2.0 授权框架的外部系统连接。

您可以使用以下 OAuth 2.0 授权类型创建 OAuth 客户端：

• 授权代码
• 客户端凭证

使用授权代码授予类型创建的 OAuth 2.0 客户端支持刷新密钥授予类型。如果系统的访问密钥响应包括非空的 expires_in 和 refresh_token 值，访问密钥将使用刷新密钥自动刷新。

使用客户端凭证授予类型与客户端创建的 OAuth 2.0 连接可能包含密钥过期值。在这些情况下，当密钥过期时，将使用同一个 OAuth 客户端抓取新的访问密钥。

注意：在某些情况下，我们可能会使用一个刷新密钥多次刷新访问密钥。由于某些系统实施了防止重复使用刷新密钥的机制，我们建议尽可能实施宽限期，或使用客户端凭证授予类型。

创建 OAuth 客户端

1. 在管理中心，单击侧栏中的应用和整合 ()，然后选择连接 > 连接。
2. 输入客户端的名称。客户端一经创建即无法更改名称。
3. 输入客户端 ID。这是分配给您的 OAuth 客户端的唯一标识符，和客户端的用户名类似。
4. 输入客户端密码。这将作为您客户端应用程序的密码，并在 Zendesk 和外部系统之间建立信任。
5. （仅限授权代码授予类型）输入授权 URL，即用于接收授权代码的服务器 URL。
6. 输入密钥 URL，即用于接收访问密钥的 URL。
7. 输入以空格分隔的默认作用域列表。作用域是规定客户端应用程序可以代表用户访问何种内容的权限。
8. 单击保存以创建客户端。

创建连接

您可以从管理中心的“连接”页面创建连接。

创建连接

1. 在管理中心，单击侧栏中的应用和整合图标 ()，然后选择连接 > OAuth 客户端。
2. 单击创建连接。
3. 选择身份验证类型。
4. 输入连接的名称。连接一经创建即无法更改名称。
5. 执行以下操作之一：
   • （API 密钥、基本身份验证、不记名密钥）配置连接的身份验证凭证。连接使用这些详细信息对服务或系统的 REST API 调用进行身份验证。
   • (OAuth 2.0) 选择要使用的客户端，并（可选）输入以空格分隔的作用域列表。如果不输入任何作用域，则系统会使用 OAuth 客户端中指定的默认作用域。
6. 输入此连接允许的域名。允许的域名一经创建即无法更改名称。有关更多信息，请参阅允许的域名。
7. 单击保存以创建连接。

创建连接后，您可以从管理中心的“连接”页面查看其详细信息。请参阅管理连接。

注意：当使用 OAuth 2.0 身份验证类型创建连接时，将存储外部系统的访问密钥响应中包含的作用域，而不是创建连接时定义的作用域。此值不能大于 255 个字符。

允许的域名

每个连接都需要一个 URL 主机名作为允许的域名。Zendesk 只会将 API 调用中的连接凭证传递到此主机名。通过其他主机名使用连接会失败。这样有助于防止连接凭证意外泄漏。创建连接后，您无法更改其允许的域名。

例如，您只能使用允许的域名为“api.example.com”的连接对“https://api.example.com”主机名进行 API 调用。

允许的域名的要求

连接的允许域名不得超过 128 个字符。值中的子域名或域名不得超过 63 个字符。该值必须包含有效的域名。

连接始终使用 https 机制。不支持 ftps 等其他机制。

允许的域名的通配符

连接的允许域名支持可选的通配符 (*) 子域名。这样您可以通过裸域名和任何子域名使用连接。例如，您可以使用允许的域名为 *.example.com 的连接对“example.com”或“example.com”的任何子域名的 API 调用进行身份验证。

要使用通配符子域名，允许域名的前两个字符必须是 *.。主机名的其它部分不可使用通配符。例如，您不能在主机名中使用通配符，例如 exam*.com 或 my-*.example.com.

您不能在只有公共域名后缀的主机名中使用通配符，例如 *.com、*.com.au 或 *.myshopify.com。有关公共后缀列表，请参阅 publicsuffix.org 上的公共后缀列表。

API 密钥的 HTTP 标头

在创建 API 密钥连接时，您必须指定 HTTP 标头名称。当使用连接进行 API 调用时，Zendesk 会传递 API 密钥作为此标头的值。

许多 API 使用自定义标头来接受 API 密钥。要确定 API 调用的适当标头名称，请查阅 API 文档。

标头名称要求

API 密钥连接的标头名称不得超过 128 个字符。标头名称只能包含字母、连字符 (-) 和下划线 (_)。

您不能使用以下 HTTP 标头名称：

• accept
• accept-charset
• accept-encoding
• accept-language
• cache-control
• connection
• content-md5
• cookie
• date
• expect
• from
• host
• if-match
• if-modified-since
• if-none-match
• if-range
• if-unmodified-since
• max-forwards
• pragma
• proxy-authenticate
• proxy-authorization
• range
• server
• referer
• te
• trailer
• transfer-encoding
• upgrade
• user-agent
• via
• warning
• www-authenticate
• 开头为以下字符的标头名称：
  • x-amz-
  • x-amzn-
  • x-forwarded-
  • x-zis-