主题

主题API允许您管理指南主题，并将更复杂的主题开发工作流与指南集成。

API由主题和作业组成。主题资源表示指南主题。作业用于异步操作。

如果您使用多个品牌，请将请求发送到帐户域，而不是品牌域。

如果使用OAuth2身份验证，请将所需的作用域设置为主题:读或主题:写分别执行读操作和所有操作。

JSON格式的主题

主题由具有以下属性的JSON对象表示:

名字	类型	评论
id	字符串	创建主题时自动分配
名字	字符串	主题的名称
版本	字符串	主题的版本号。在主题清单中指定
作者	字符串	主题的作者。在主题清单中指定
生活	布尔	主题当前是否在帮助中心中发布
created_at	时间戳	主题被创造的时间
updated_at	时间戳	主题最后更新的时间
brand_id	字符串	主题的品牌id

例子

             
              {“id”：“asdf123-asdf”，“名称”：“哥本哈根会议”，“作者”：“亚博Zendesk”，“版本”：“1.7.5”，“活”：真正的，“created_at”：“2012 - 04 - 04 - t09:14:57z”，“updated_at”：“2012 - 04 - 04 - t09:14:57z”}

主题列表

GET / api / v2 /指导/主题/主题
GET / api / v2 /指导/主题/主题吗?brand_id = {brand_id}

允许

指导经理

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/themes ? brand_id={brand_id}＼- v - u{email_address}：{密码}

示例响应

             
              状态:200 OK{“主题”:[{“id”:“asdf123-asdf”,“名称”:“哥本哈根会议”,“作者”:“Zende亚博sk”,…}，…］}

展示主题

GET / api / v2 /指导/主题/主题/ {id}

允许

指导经理

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/themes/{id}＼- v - u{email_address}：{密码}

示例响应

             
              状态:200 OK{"主题":{“id”:“asdf123-asdf”,“名称”:“哥本哈根会议”,“作者”:“Zende亚博sk”,…}}

发表的主题

POST / api / v2 /指导/主题/主题/ {id} /出版

允许

指导经理

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/themes/{id}/出版＼- v - u{email_address}：{密码}- x的帖子

示例响应

             
              状态:200 OK{"主题":{“id”:“asdf123-asdf”,“名称”:“哥本哈根会议”,“作者”:“Zende亚博sk”,“生活”:真的…}}

删除主题

删除/ api / v2 /指导/主题/主题/ {id}

允许

指导经理

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/themes/{id}＼- v - u{email_address}：{密码}- x删除

示例响应

             
              状态:204无内容

用于工作的JSON格式

名字	类型	评论
状态	字符串	作业的当前状态。可能的值:pending, completed, failed
错误	数组	作业失败时的错误数组。如果作业挂起或成功，则返回null。看到错误
数据	对象	提供有关创造就业机会的特定工作数据

错误

工作返回一个错误数组中。如果任务待定或成功，则错误属性为空。如果工作不成功，那么错误属性可以包含错误对象数组。错误对象的格式如下:

名字	类型	评论
标题	字符串	错误信息
代码	字符串	错误的唯一标识符。看到失败的工作错误码
元	对象	带有更多错误信息的对象

错误响应示例

             
              状态:404未找到{“错误”:({"title": "Theme not found"，“代码”:“ThemeNotFound”,“状态”:“404”,"元":{“id”:“theme_id”}}］}

             
              状态:400请求错误{“错误”:({“title”:“提供的品牌无效”;“代码”:“InvalidBrand”,“状态”:“400”,"meta":{…}}］}

通用错误码

Http状态	代码	评论
401	InvalidOAuthScopes	提供的验证范围与所需的范围不匹配
400	UnavailableFeatures	主题正在尝试使用当前指南计划中不可用的功能
400	InvalidBrand	品牌标识不正确

主题错误码

Http状态	代码	评论
404	ThemeNotFound	提供的主题id不存在
400	LiveThemeDeleted	品牌的活动主题不能被删除

工作错误码

Http状态	代码	评论
404	JobNotFound	提供的作业id不存在
400	TooManyThemes	允许达到的最大主题数
400	NonUpdatableTheme	试图更新非`api`主题

失败的工作错误码

代码	评论
TooManyThemes	允许达到的最大主题数
NameTooLong	主题名称比允许的长
FileNotSupported	文件不支持，错误的扩展名，dir等。
FileTooBig	添加的文件比允许的文件大
ThemeTooBig	主题大于最大尺寸
FileNameTooLong	文件名超过允许的长度
FileNotFound	找不到所需的文件
FileLimitReached	已达到最大文件数
FileDeletionInProgress	试图更改标记为删除的文件
InvalidTemplates	模板有语法错误
InvalidSetting	设置无效
TooManySettings	超过了允许的设置数量
InvalidManifest	舱单无效
UnsupportedLocale	不支持区域设置
InvalidTranslationFile	翻译文件无效
InvalidThemeVersion	主题版本无效
NonUpdatableTheme	主题无法更新

例子

             
              {“状态”：“等待”，“错误”：零，“数据”：零}

展示工作

GET / api / v2 /指导/主题/工作/ {id}

允许

指导经理

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/jobs/{id}＼- v - u{email_address}：{密码}

示例响应

             
              状态:200 OK{"工作":{“状态”:“失败”,“错误”:({"title": "Theme not found"，“代码”:“ThemeNotFound”,"meta": {}}］}}

创建主题导入作业

POST / api / v2 /指导/主题/工作/主题/进口

端点本身不接收ZIP文件。看到主题导入流程了解更多信息。

这个工作的数据对象具有以下格式:

名字	类型	评论
theme_id	字符串	在创建作业时自动分配
upload.url	字符串	存储位置的一次性URL
upload.parameters	对象	将ZIP文件发送到上传url时使用的参数

请注意:上传参数应被认为是不稳定的，并按原样提供，无需修改。

允许

指导经理

请求体格式

名字	类型	评论
job.attributes.brand_id	字符串	要导入主题的品牌id
job.attributes.format	枚举	有效枚举["zip"]

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/jobs/themes/imports＼- d”{“工作”:{“属性”:{“brand_id”:“brand_id”、“格式”:“zip”}}}”＼- h“application / json内容类型:＼- v - u{email_address}：{密码}- x的帖子

示例响应

             
              状态:202已接受{"工作":{“id”:“a66e7bde543c6b6d018f0e07a654feaf”,“状态”:“等待”,“错误”:空,"数据":{:“theme_id asdf123-asdf”,"上传":{“url”:“storage.zdassets.com/storage-location”,parameters:{…}}}}}

主题导入流程

导入一个主题:

创建主题导入作业创建主题导入作业端点。
中指定的存储位置上传到该文件上传对象。通过向指定的上传url发送POST请求来上传文件。不要指定任何身份验证头。POST请求的内容类型必须多部分/格式的每个参数参数对象必须作为表单字段提供文件字段中包含要上传的ZIP文件。
对象轮询作业状态展示工作端点，以了解主题何时可用。当状态为“完成”时，主题带有theme_id可供使用。避免过于频繁地轮询，以免受到速率限制。示例:每5秒轮询一次。

主题导入工作流的示例脚本

使用以下步骤使用Ruby创建一个简单的主题导入脚本。该脚本不包括错误处理。

安装以下gems:

               
                Gem安装Faraday安装faraday-net_httpGem安装faraday-multipart

创建本地theme_upload.rb文件。将以下脚本放入文件中。用Zendesk帐户信息填写第5-9行。亚博

               
                需要“法拉第”需要“法拉第/ net_http”需要“法拉第/多部分”子域= "File_path = "Brand_id = "Email = "密码= "conn =法拉第。New do |f|f.request: json请求:授权、基本、电子邮件、密码f.response: jsonF.response:logger, nil， {headers: false, bodies: true}f.adapter: net_http结束Response = conn.post("https://#{subdomain}.亚博zendesk.com/api/v2/guide/theming/jobs/themes/imports"，{“工作”:{“属性”:{“brand_id”:“# {brand_id}”,“格式”:“zip”}}})Job_id = response.body['job']['id']storage_url = response.body['工作'](“数据”)(“上传”)(“url”)Storage_parameters = response.body['job']['data']['upload']['parameters']stor_conn = Faraday。New do |f|f.request:多部分f.request: url_encodedf.adapter: net_http结束Storage_body = storage_parameters。(文件:法拉第::UploadIO合并。新(file_path、应用程序/ zip))stor_conn。帖子(storage_url storage_body)10.次做的Job_status_response = conn.get("https://#{subdomain}.亚博zendesk.com/api/v2/guide/theming/jobs/#{job_id}")把job_status_response.body除非job_status_response，否则中断。主体['job']['status'] == 'pending'睡眠(5)结束

在shell中，运行以下命令将主题添加到品牌中:

               
                ruby theme_upload.rb

创建主题更新作业

POST / api / v2 /指导/主题/工作/主题/更新

端点本身不接收ZIP文件。看到主题更新流程了解更多信息。

这个工作的数据对象具有以下格式:

名字	类型	评论
upload.url	字符串	存储位置的一次性URL
upload.parameters	对象	将ZIP文件发送到上传url时使用的参数

请注意:上传参数应被认为是不稳定的，并按原样提供，无需修改。

允许

指导经理

请求体格式

名字	类型	评论
job.attributes.theme_id	字符串	要导出的主题Id
job.attributes.replace_settings	布尔	是否替换当前主题设置
job.attributes.format	枚举	有效枚举["zip"]

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/jobs/themes/updates＼- d”{“工作”:{“属性”:{“theme_id”:“theme_id”、“replace_settings”:真的,“格式”:“zip”}}}”＼- h“application / json内容类型:＼- v - u{email_address}：{密码}- x的帖子

示例响应

             
              状态:202已接受{"工作":{“id”:“a66e7bde543c6b6d018f0e07a654feaf”,“状态”:“等待”,“错误”:空,"数据":{"上传":{“url”:“storage.zdassets.com/storage-location”,parameters:{…}}}}}

主题更新流程

更新主题:

属性创建主题更新作业创建主题更新作业端点。
中指定的存储位置上传到该文件上传对象。通过向指定的上传url发送POST请求来上传文件。不要指定任何身份验证头。POST请求的内容类型必须多部分/格式参数对象中的每个参数都必须作为表单字段提供文件字段中包含要上传的ZIP文件。
对象轮询作业状态展示工作端点，以知道主题何时被更新。当状态为“完成”时，表示主题已经更新到上传的版本。避免过于频繁地轮询，以免受到速率限制。示例:每5秒轮询一次。

创建主题导出作业

POST / api / v2 /指导/主题/工作/主题/出口

端点本身不交付ZIP文件。看到主题导出流程了解更多信息。

这个工作的数据对象具有以下格式:

名字	类型	评论
download.url	字符串	作业完成后可以在哪里下载主题

允许

指导经理

请求体格式

名字	类型	评论
job.attributes.theme_id	字符串	要导出的主题Id
job.attributes.format	枚举	有效枚举["zip"]

使用旋度

             
              旋度https://{子域名}.亚博zendesk.com/api/v2/guide/theming/jobs/themes/exports＼- d”{“工作”:{“属性”:{“theme_id”:“theme_id”、“格式”:“zip”}}}”＼- h“application / json内容类型:＼- v - u{email_address}：{密码}- x的帖子

示例响应

             
              状态:202已接受{"工作":{“id”:“a66e7bde543c6b6d018f0e07a654feaf”,“状态”:“等待”,“错误”:空,"数据":{"下载":{“url”:“storage.zdassets.com/storage-location”}}}}

主题导出流程

导出一个主题:

创建主题导出作业创建主题导出作业端点。
对象轮询作业状态展示工作端点，直到作业不再“挂起”。
当作业状态为“completed”时，使用下载对象中的url下载主题。