文档 API参考

从Zendesk应用程序发出API请求亚博

您可以使用Zendesk应用程序亚博框架(ZAF)客户端请求()方法从客户端Zendesk应用程序进行REST API调用和其他HTTP请求。该方法允许您:亚博

  • 调用第三方api时避免跨域限制
  • 在进行身份验证请求时，避免在浏览器中泄露秘密
  • 管理第三方服务的OAuth 2.0访问令牌
  • 使用浏览器cookie验证亚博Zendesk API请求

该方法以JavaScript的形式返回请求的结果承诺对象。该方法不支持上传或下载二进制文件。

向第三方API发出请求

默认情况下，请求()方法通过Zendesk代理服务器将请求路由到非Zendesk亚博 url。例如，下面的请求使用代理服务器进行API调用。

             

              
常量客户端=ZAFClient.初始化（）；常量选项={url：“https://api.example.com”，类型：“获得”，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

要显式使用Zendesk代理服务器，请设亚博置歌珥选项为false。下面的请求和前面的请求是等价的。

             

              
常量客户端=ZAFClient.初始化（）；常量选项={url：“https://api.example.com”，类型：“获得”，歌珥：假，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

使用Zendesk代理服务器的好处亚博

使用Zendes亚博k代理服务器可以帮助您避免同源策略限制.这些限制可以阻止客户端请求访问另一个域中的资源。亚博电脑端使用代理发出的服务器端请求没有相同的限制。

使用Zendes亚博k代理服务器还可以让您访问以下ZAF功能:

这些特性在请求()方法。

使用安全设置

客户端HTTP请求的设置在浏览器的开发工具中可见。这些设置通常包含机密，例如API身份验证凭据。在浏览器中泄露机密会带来安全风险。

安全设置允许您在HTTP请求中安全地使用秘密。中使用设置占位符代替实际值请求()调用。浏览器的开发工具中只显示占位符，而不显示值。Zend亚博esk代理服务器稍后将设置的值插入到浏览器之外。

安全设置要求

要在请求中使用安全设置，响应服务器必须:

  • 允许来自Zendesk IP地址的请求。亚博方法可以获取这些IP地址范围列出Zen亚博desk公共ip端点

  • 提供有效且完整的SSL证书链。例如,curl https://{服务器}/不会因SSL错误而失败，使用标准的根证书集，例如发布在Ubuntu包

配置和传递安全设置

安全设置需要更改应用程序的清单文件。Ze亚博ndesk管理员还必须在应用程序安装期间配置该设置。

  1. 在应用的manifest.json文件，添加一个设置对象到顶层参数财产。设置对象的安全属性为true。

                   
    
                
    {…“参数”：［{“名称”：“apiToken”，“类型”：“文本”，“安全”：真正的}]}

    有关其他受支持的属性，请参见设置属性.

  2. 在manifest.json，将API端点的域添加到顶层domainWhitelist数组中。取值中不要包含“https://”。

                   
    
                
    {…“domainWhitelist”：［“api.example.com”]，“参数”：［{“名称”：“apiToken”，“类型”：“文本”，“安全”：真正的}，]}

  3. 在应用的请求()调用，使用{{设置。名称}}安全设置值的占位符。设置安全选项为true。

                   
    
                
    常量选项={url：“https://api.example.com/list”，类型：“获得”，头：{授权：“基本{{setting.apiToken}}”，}，接受：“application / json”，安全：真正的，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

    注意:类型之外不能使用安全设置占位符请求()调用。

  4. 在安装应用程序时，管理员会收到输入安全设置值的提示。

当应用程序做出请求()调用时，浏览器的开发工具只显示设置占位符。Zend亚博esk代理服务器将设置的值插入到浏览器外部。

安全设置限制

管理第三方OAuth访问令牌

ZAF使用oauth设置类型来管理第三方OAuth访问令牌。如果应用程序包含此设置类型，则在应用程序安装时显示OAuth提示。

Ze亚博ndesk管理员可以使用此提示启动第三方服务的OAuth流。如果流程完成，ZAF存储生成的访问令牌。

您可以将令牌的设置占位符传递给请求()调用。浏览器的开发工具中只显示占位符，而不显示令牌。Zend亚博esk代理服务器稍后将令牌插入到浏览器之外。

重要的是:的oauth设置type仅支持授权码授予类型。您不能将该设置与其他OAuth授权类型一起使用。

使用第三方OAuth访问令牌

的oauth设置需要更改应用程序的清单文件。Ze亚博ndesk管理员还必须在应用程序安装期间完成OAuth流程。

  1. 在第三方服务中创建OAuth客户端。这些步骤因服务而异。将客户端的回调URL设置为“https://” zis.亚博zendesk.com/api/services/zis/connections/oauth/callback”。完成后，服务应该提供客户端id和秘密。

    该服务的文件还应提供:

  2. 在应用的manifest.json文件，添加一个顶级oauth对象。使用步骤1中的OAuth客户端详细信息设置对象的属性值。

                   
    
                
    {…“oauth”：{“client_id”：“CLIENT_ID”，“client_secret”：“CLIENT_SECRET”，“authorize_uri”：“https://api.example.com/oauth/authorize”，“access_token_uri”：“https://api.example.com/oauth/access_token”，“范围”：“读写“}}

  3. 在manifest.json，在顶层添加一个设置对象参数财产。设置对象的类型来oauth.

                   
    
                
    {“参数”：［{“名称”：“令牌”，“类型”：“oauth”}]，“oauth”：{“client_id”：“CLIENT_ID”，“client_secret”：“CLIENT_SECRET”，“authorize_uri”：“https://api.example.com/oauth/authorize”，“access_token_uri”：“https://api.example.com/oauth/access_token”，“范围”：“读写“}}

  4. 在应用的请求()调用，使用{{设置。名称}}令牌的占位符。设置安全选项为true。

                   
    
                
    常量选项={url：“https://api.example.com/list”，类型：“获得”，头：{授权：“不记名{{setting.token}}”，}，安全：真正的，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

  5. 当管理员安装应用程序时，一个OAuth身份验证页。该部分包含一个文本链接使用{app_name}登录.

    管理员可以单击该链接，使用第三方服务启动OAuth流。如果管理员完成OAuth流程，则OAuth身份验证部分显示一个复选标记图标。

当应用程序做出请求()调用时，浏览器的开发工具只显示设置占位符。Zend亚博esk代理服务器将访问令牌插入到浏览器外部。

刷新第三方访问令牌

ZAF自动刷新过期的访问令牌访问令牌响应包括非空expires_in和refresh_token值。对于不提供这些值的第三方服务，ZAF无法刷新访问令牌。

使用OAuth参数

一些第三方服务在OAuth中包含自定义查询参数授权代码响应.例如，下面的授权代码响应包含一个自定义商店参数。

             

              
https：//例子.com/重定向？代码=xyz&状态=美国广播公司&商店=myshop

方法中添加设置对象，以存储此类参数的值参数财产manifest.json.对于对象的名字，使用查询参数的键和oauth_前缀。设置对象的类型“隐藏”。

             

              
{…“参数”：［{“名称”：“令牌”，“类型”：“oauth”}，{“名称”：“oauth_shop”，“类型”：“隐藏”}]…}

您可以使用ZAF客户端访问设置值元数据()方法。

             

              
客户端.元数据（）.然后（（元数据）= >{控制台.日志（元数据.设置.oauth_shop）；}）；

编码和发送ZAF jwt

的请求()方法支持编码和发送JSON网络令牌(JWTs).您可以使用ZAF JWT在请求中发送任意数据。您还可以使用JWT来确保来自Zendesk应用程序的请求是合法的。亚博响应服务器可以使用共享密钥验证JWT的签名。Zend亚博esk代理服务器将编码后的jwt插入到浏览器外部。

重要的是:ZAF jwt签名但不加密。不要在ZAF jwt中包含秘密，例如密码。

编码并发送一个ZAF JWT令牌:

  1. 包括一个jwt对象中的请求()调用的选项。在对象中，包括以下属性:

    • 一个jwt.algorithm“HS256”。ZAF JWT签名只支持HS256算法。

    • 一个jwt.secret_key它使用了安全设置因为它的价值。

    • 一个可选的jwt.expiry持续时间，以秒为单位。ZAF使用这个持续时间来计算JWT经验值索赔。有效期从JWT发行之日起算。缺省为5分钟。

    • 一个可选的jwt.claims对象，该对象包含JWT的声明，包括任何自定义声明。Zend亚博esk代理服务器会自动添加iat和经验值索赔。如果您指定iat或经验值声明，服务器会覆盖它们。

    另外，设置安全选项为true。

                   
    
                
    常量选项={url：“https://api.example.com/post”，类型：“职位”，头：{授权：“不记名{{jwt.token}}”，}，jwt：{算法：“HS256”，secret_key：“{{setting.shared_secret}}”，到期：3600，索赔：{jti：“8883362531196.326”，国际空间站：“some_subdomain”，}，}，安全：真正的，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

    重要的是:ZAF jwt只支持Latin-1 (ISO 8859-1) UTF-8字符子集。非UTF-8字符被解析为UTF-8。

  2. 在请求()调用，使用{{jwt.token}}ZAF JWT的占位符。

                   
    
                
    常量选项={url：“https://api.example.com/post”，类型：“职位”，头：{授权：“不记名{{jwt.token}}”，}，jwt：{算法：“HS256”，secret_key：“{{setting.shared_secret}}”，到期：3600，索赔：{jti：“8883362531196.326”，国际空间站：“some_subdomain”，}，}，安全：真正的，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

当应用程序做出请求()调用时，浏览器的开发工具只在请求中显示占位符。Zend亚博esk代理服务器将JWT插入到浏览器外部。

发出CORS请求

如果API支持跨地域资源共享，您可以在没有Zendesk代理服务器的情况下向API发出客户端请求。亚博这被称为CORS请求。若要发出CORS请求，请设置歌珥选项为true。

             

              
常量选项={url：“https://api.example.com/list”，类型：“获得”，歌珥：真正的，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

重要的是:只对不需要身份验证的API调用使用CORS请求。在CORS请求中使用秘密可能会泄露浏览器中的秘密。

CORS请求不通过Zendesk代理服务器路由，不支持以下ZAF特性:亚博

如果歌珥是真的，安全选项被忽略。

做一个Zendes亚博k API请求

你也可以使用请求()方法向Zendesk API发出请求。亚博为了验证请求，ZAF客户端使用浏览器的Zendesk会话cookie。亚博

对象中的端点路径url选择。不要包含Zendesk域或子域。亚博

例如，下面的请求调用Ticketing API创建机票端点。

             

              
常量选项={url：“/ api / v2 / tickets.json”，类型：“职位”，contentType：“application / json”，数据：JSON.stringify（{票：{主题：“测试票#1”，评论：{身体：“这是一张测试票”}}}），}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

下面的请求调用核心销售CRM API达成协议端点。

             

              
常量选项={url：“/ v2 /交易”，类型：“职位”，contentType：“application / json”，数据：JSON.stringify（{数据：{名字：“网站设计”，contact_id：1}}），}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

对Zendesk api亚博的请求总是从浏览器发出的，而不管歌珥选择。您不能使用Zendesk代理服务器向Zendesk API发亚博出请求。

Zendesk API请求的速率亚博限制

请求()对Zendesk 亚博api的调用受速率限制。看到速度限制在ZAF API参考。

如果一个请求()呼叫速率受限，ZAF会在延迟后自动重试请求。若要禁用重试行为，请设置autoRetry选项假.

             

              
常量选项={url：“/ api / v2 / tickets.json”，类型：“获得”，autoRetry：假，}；客户端.请求（选项）.然后（（响应）= >{控制台.日志（响应）；}）；

Zendesk API请求的限制亚博