构建您的第一个ZIS集成

本教程向您展示如何从头构建一个简单的ZIS集成。集成将监听票了事件在Zendesk亚博。当它检测到事件时，集成将把票证的id、状态和优先级发布到表示外部应用程序的外部目标。

本教程由以下部分组成:

免责声明Ze亚博ndesk提供本文仅用于指导目的。集成和示例并不适用于生产环境。亚博Zendesk也不提供测试集成的支持。有任何问题请在亚博Zendesk开发者社区或者在网上搜索解决方案。

你需要什么?

要构建示例集成，您将需要以下内容:

用于亚博测试的Zendesk帐户。ZIS在Zendesk Suite增长计划或更高亚博版本，以及支持专业计划或更高版本上得到支持。如果你没有Zendesk测试帐户，你可以亚博获得一个免费的赞助测试帐户。看到申请一个赞助的测试帐户。测试帐号支持ZIS。
是一个管理员的帐户或有访问的人谁是一个管理员。管理员可以给你管理员权限。看到在Zendesk Admin Center中设置角色和访亚博问权限。
表示外部应用程序的外部目标。你可以得到一个免费的目标RequestBin。该站点允许您创建一个唯一的端点URL，该URL将返回您发送给它的任何数据。

注册集成名称

构建集成的第一步是使用ZIS注册服务注册集成的名称。此名称也称为集成键。

您选择的名称必须是全局唯一的，最长可达64个字符。集成名称支持以下字符:小写字母(a-z)、数字、“-”、“_”。

要注册集成名称，请向创建集成端点。

要对请求进行身份验证，可以使用基本身份验证，包括Zendesk用户名和密码或亚博API的令牌。如果您还没有这样做，请检查Admin Center下是否启用了API访问应用和集成>api>亚博Zendesk api。看到使用API仪表板。

本教程提供了相同请求的Postman和curl示例，但是您可以使用任何喜欢的工具来发出请求。

使用邮差

在“邮差”中选择文件>新>HTTP请求。
在Postman请求编辑器中，输入Create Integration端点:
https://{子域名}.zendes亚博k.com/api/services/zis/registry/{集成}
取代{子域名}您的Zendesk子亚博域名和{集成}使用您想要为集成注册的名称。因为它必须是全局唯一的，所以使用特定于你的东西，而不是“zis_tutorial”。
选择帖子如左边的方法。
单击身体选项卡在您的请求路径下面。确保选中raw和JSON选项并进行粘贴{"description": "示例集成"}。
单击授权Tab和下面类型中,选择基本认证，并输入您的Zendesk管理员凭亚博据。
点击发送。

请求和响应在Postman中应该是这样的:

不要混淆标识符值与您刚刚注册的集成名称(miso_integration_3212(在示例中)。ZIS增加了一个zis_的前缀标识符value，它仅用于获取OAuth令牌。集成名称是您在API请求中提供的名称，没有前缀。

保存您注册的集成名称。在这个例子中，它是miso_integration_3212,而不是zis_miso_integration_3212。

使用旋度

在命令行界面中，执行以下操作旋度要求:

               
                旋度https://{子域名}.亚博zendesk.com/api/services/zis/registry/{集成}＼- d'{"description": "示例集成"}'＼- h“application / json内容类型:＼- u{email_address}：{密码}- x的帖子

构建集成

ZIS集成的逻辑在一个ZIS包中定义。ZIS包是一个JSON对象，包含以下类型的嵌套对象:

行动对象，它定义HTTP请求和其他操作
流对象，它们定义了集成的不同状态。每个状态指定集成进入该状态时要运行的操作
JobSpec对象，它指定给定事件发生时要运行的流

在本教程的这一部分中，您将创建一个starter bundle，然后用定义集成逻辑的JSON对象填充它。

创建一个初学者包

在本节中，您将创建一个空的starter bundle，其中包含稍后将添加的以下对象的占位符:

一个行动对象将票证的id、状态和优先级发布到外部目标
一个流对象来运行操作并将票证的数据传递给它
一个JobSpec对象来运行流票了事件，并将新票据的数据传递给流

来创建starter bundle

创建一个JSON文件my_zis_bundle.json。

将以下包骨架添加到文件中:

               
                {“名称”：“我的第一个ZIS集成”，“描述”："将票证数据发送到票证创建上的外部目标"，“zis_template_version”：“2019-10-14”，“亚博电脑端资源”：{“action_post_ticket_data”：{“_placeholder_”：“这里是ZIS动作属性”}，“flow_ticket_created”：{“_placeholder_”：“这里的ZIS流动特性”}，“jobspec_handle_ticket_event”：{“_placeholder_”：“这里是ZIS工作规格属性”}}}

您将在下一节中定义操作、流程和作业规范。

请注意你不应该改变zis_template_version价值。

有关ZIS包的更多信息，请参见ZIS束的解剖和包API。

定义一个ZIS动作

对于集成，您需要一个可以发出HTTP请求的ZIS操作。当集成检测到Ticket Created事件时，它应该发出POST请求，将票据数据发送到模拟外部应用程序的外部目标。您可以通过构建自定义操作来创建特定的功能。有关更多信息，请参见ZIS自定义动作。

假设外部目标需要新的票证id在一个名为X-亚博Zendesk-Ticket-Id还有票状态和优先级的JSON对象中数据。

在curl中，对目标的POST请求可能如下所示:

             
              旋度https://abc123.x.pipedream.net＼- h“关键:X-Ze亚博ndesk-Ticket-Id”＼- h“价值:45326774”＼- d'{"data": {"status": "new"， "priority": "high"}}'＼- h“application / json内容类型:＼- x的帖子

在本节中，您将定义与ZIS操作相同的POST请求。

来定义您的ZIS操作

在你的my_zis_bundle.json文件中的占位符行替换为action_post_ticket_data对象，使用下面的ZIS行动属性(下面第2到21行):

             
              “action_post_ticket_data”：{“类型”：“子::行动::Http”，“属性”：{“名称”：“action_post_ticket_data”，“定义”：{“方法”：“职位”，“url”：“EXTERNAL_TARGET_URL”，“头”：［{“关键”：“X-亚博Zendesk-Ticket-Id”，“美元的价值。”：“.ticketId美元”}]，“requestBody”：{“数据”：{美元”状态。”：“.ticketStatus美元”，“美元优先级。”：“.ticketPriority美元”}}}}}，

将“EXTERNAL_TARGET_URL”占位符替换为您从RequestBin中获得的端点URL。示例:“https : / / abc123.x.pipedream.net”。

你在ZIS行动中做了以下工作:

为你的行动命名action_post_ticket_data。ZIS验证规则要求操作的properties.name与其顶级键相同(在本例中，action_post_ticket_data）
使用了类型属性指定动作的类型为"ZIS:: action::Http"
使用了定义对象来定义HTTP请求

您还使用了名为.ticketId美元，.ticketStatus美元,.ticketPriority美元为动作提供数据。

要在ZIS操作中将变量赋值给属性，请添加“”。属性名后面加$"后缀。例子:美元”状态。”：“.ticketStatus美元”。当数据被发送到目标时，后缀将被省略。

您将在下一节中定义流中的变量。为了给你一个预览，上面的变量在流程中定义如下:

             
              “参数”：{“ticketId美元。”：“.input.ticket_event.ticket.id美元”，“ticketStatus美元。”：“.input.ticket_event.ticket.status美元”，“ticketPriority美元。”：“.input.ticket_event.ticket.priority美元”}

的输入示例中的数据是从作业规范中指定的Ticket Created事件接收的输入数据记录在票了事件触发事件参考文档。例如,“.input.ticket_event.ticket.status美元”对应于文档中示例中的"new"。

ZIS包中的所有参数都使用JSONPath语义。

定义一个ZIS流

既然已经定义了ZIS操作，就可以将其添加到ZIS流中。一个ZIS流为集成定义了一个或多个状态。你可以创建不同的状态的类型但在本教程中，您将创建一个类型为“Action”的状态来运行您定义的操作。

本教程中的集成在创建Zendesk票证时进入其第一个(也是唯一的)状态。亚博在本节中，您将创建一个名为“ZendeskTicketCreated”的状态，并向其添加您的亚博操作。

来定义您的ZIS流

在你的my_zis_bundle.json文件中的占位符行替换为flow_ticket_created对象具有以下ZIS流属性(第2行到第20行):

             
              “flow_ticket_created”：{“类型”：“子:流”，“属性”：{“名称”：“ticket-created-flow”，“定义”：{“StartAt”：“亚博ZendeskTicketCreated”，“州”：{“亚博ZendeskTicketCreated”：{“类型”：“行动”，“ActionName”：“子:集成:行动:action_post_ticket_data”，“参数”：{“ticketId美元。”：“.input.ticket_event.ticket.id美元”，“ticketStatus美元。”：“.input.ticket_event.ticket.status美元”，“ticketPriority美元。”：“.input.ticket_event.ticket.priority美元”}，“结束”：真正的}}}}}，

用您注册的集成名称替换“INTEGRATION”占位符注册集成名称。

您在ZIS流程中做了以下操作:

命名你的流ticket-created-flow
使用(必选)StartAt属性指定由事件触发流时要进入的第一个状态
定义了一个亚博ZendeskTicketCreated在(必需的)州对象
使用了ActionName属性来告诉ZIS当集成进入亚博ZendeskTicketCreated状态
中操作中使用的已定义变量参数对象。的输入从作业规范中指定的Ticket Created事件接收数据票了事件触发事件参考文档。例如,“.input.ticket_event.ticket.id美元”对应于文档中示例中的35436。
集结束对真实的亚博ZendeskTicketCreated状态告诉ZIS在操作运行后退出流

定义ZIS作业规格

一个工作规范像事件处理程序一样工作。它指定在检测到给定事件时运行的流。

作业规范还将事件数据传递到后台的流。数据的格式取决于事件，并记录在ZIS中触发事件参考文档。

本教程中的集成运行您的ticket-created-flow创建票据时的流程。

定义您的ZIS工作规格

在你的my_zis_bundle.json文件中的占位符行替换为jobspec_handle_ticket_event对象具有以下ZIS作业规范属性(第2行到第9行):

             
              “jobspec_handle_ticket_event”：{“类型”：“子::JobSpec”，“属性”：{“名称”：“handle-ticket-created-event”，“event_source”：“支持”，“event_type”：”票。TicketCreated”，“flow_name”：“子:集成:流:ticket-created-flow”}}

用您注册的集成名称替换“INTEGRATION”占位符注册集成名称。

你在ZIS的工作说明书中做了以下几点:

使用了event_source属性告诉ZIS事件的来源是support。看到在作业规范中引用事件在参考文档中。
使用了event_typeproperty告诉ZIS要听”票。TicketCreated”事件。该事件将把数据传递给后台的流。传递到流的数据示例，请参见票了医生。
使用了flow_name属性告诉ZIS运行你的ticket-created-flow流，当它检测到Ticket Created事件时。的flow_name属性对值使用以下格式:子:{集成}:流:{flow_name}。

代码完成

您的操作、流程和作业规范现在构成了一个完整的ZIS包。你的my_zis_bundle.json文件应该如下所示:

             
              {“名称”：“我的第一个ZIS集成”，“描述”："将票证数据发送到票证创建上的外部目标"，“zis_template_version”：“2019-10-14”，“亚博电脑端资源”：{“action_post_ticket_data”：{“类型”：“子::行动::Http”，“属性”：{“名称”：“action_post_ticket_data”，“定义”：{“方法”：“职位”，“url”：“EXTERNAL_TARGET_URL”，“头”：［{“关键”：“X-亚博Zendesk-Ticket-Id”，“美元的价值。”：“.ticketId美元”}]，“requestBody”：{“数据”：{美元”状态。”：“.ticketStatus美元”，“美元优先级。”：“.ticketPriority美元”}}}}}，“flow_ticket_created”：{“类型”：“子:流”，“属性”：{“名称”：“ticket-created-flow”，“定义”：{“StartAt”：“亚博ZendeskTicketCreated”，“州”：{“亚博ZendeskTicketCreated”：{“类型”：“行动”，“ActionName”：“子:集成:行动:action_post_ticket_data”，“参数”：{“ticketId美元。”：“.input.ticket_event.ticket.id美元”，“ticketStatus美元。”：“.input.ticket_event.ticket.status美元”，“ticketPriority美元。”：“.input.ticket_event.ticket.priority美元”}，“结束”：真正的}}}}}，“jobspec_handle_ticket_event”：{“类型”：“子::JobSpec”，“属性”：{“名称”：“handle-ticket-created-event”，“event_source”：“支持”，“event_type”：”票。TicketCreated”，“flow_name”：“子:集成:流:ticket-created-flow”}}}}

不要忘记将“INTEGRATION”替换为集成名称，将“EXTERNAL_TARGET_URL”替换为从RequestBin获得的端点URL，然后保存文件。

部署和测试集成

在创建my_zis_bundle.jsonBundle文件，您可以通过完成以下步骤来部署和测试集成:

私有集成只能安装在套件增长计划或更高版本或专业支持计划或更高版本上。

上传bundle

部署集成的第一步是通过向组件发出API请求来上传包创建或更新包端点。

使用邮差

在“邮差”中选择文件>新>HTTP请求。
在Postman请求编辑器中，输入Upload或Update Bundle端点:
https://{子域名}.zendes亚博k.com/api/services/zis/registry/{集成}/包
取代{子域名}您的Zendesk子亚博域名和{集成}使用您注册的集成名称。
选择帖子如左边的方法。
单击身体选项卡在您的请求路径下面。确保选择了raw和JSON选项，并从您的my_zis_bundle.json文件。
单击授权Tab和下面类型中,选择基本认证，并输入您的Zendesk管理员凭亚博据。
点击发送。

ZIS将对包执行一些基本的验证，并报告响应中的任何问题。

如果请求成功，则返回一个空200好了响应。

请求和响应在Postman中应该是这样的:

使用旋度

在命令行界面中，导航到包含my_zis_bundle.json文件。

             
              旋度https：//{子域名}。亚博。com/api/服务/子/注册表/{集成}/包\-d @my_zis_bundle。json \-H“application / json内容类型:＼-v-u{电子邮件}：{密码}-X帖子

安装作业规范

下一个部署步骤是安装包中指定的作业规范。ZIS将从您刚刚上传的包中获取作业规范。

要安装作业规范，请向安装作业规范使用以下格式指定作业规范名称的端点:子:{集成}:job_spec: {job_spec_name}。

使用邮差

在“邮差”中选择文件>新>HTTP请求。
在Postman请求编辑器中，输入Install Job Spec端点:
https://{子域名}.zendes亚博k.com/api/services/zis/registry/job_specs/install
取代{子域名}使用Zendesk子亚博域名。
添加查询参数job_spec_name值为子:{集成}:job_spec: handle-ticket-created-event。
取代{集成}使用您注册的集成名称。
选择帖子如左边的方法。
单击授权选项卡上,选择基本认证作为类型，并输入您的Zendesk管理员凭证。亚博
点击发送。

如果请求成功，则返回一个空200好了响应。

请求和响应在Postman中应该是这样的:

使用旋度

             
              旋度“https://{子域名}.zendes亚博k.com/api/services/zis/registry/job_specs/install ? job_spec_name =子:{集成}:job_spec: handle-ticket-created-event”＼-v-u{电子邮件}：{密码}-X帖子

请确保将端点路径用引号括起来，因为它包含特殊字符。

测试集成

您可以通过在Zendesk中创建一个新票证来测试您的集成。亚博

在Ze亚博ndesk中，创建一个票证，并给它一个状态和优先级。

您可以使用Zendesk代理工作亚博区或发出以下curl请求:

               
                旋度https://{subdomain}.zen亚博desk.com/api/v2/tickets.json \-d“票”:{“主题”:“我的打印机着火了!”，“优先级”:“紧急”，“状态”:“打开”，“评论”:{“主体”:“烟雾很鲜艳”。}}} \-H“Content-Type: application/json”-v -u {email_address}:{password} -X POST

导航到RequestBin指示板。
您应该看到一个带有票证id的报头，以及一个带有票证状态和优先级的JSON有效负载。

如果什么都没有发生，那么检查Zendesk Admin Center中的集成日志是一个很好的故障排除起点:亚博

以管理员身份登录您的Zende亚博sk帐户。
在Admin Center中，单击侧边栏中的Apps和集成，然后选择integration > Logs。

有关更多信息，请参见查看集成日志在Zendes亚博k帮助中心。

祝贺您，您刚刚从零开始创建了第一个ZIS集成。

开始

集成设计指南

开发人员指南

亚博Zendesk集成服务示例

亚博Zendesk集成服务教程

构建您的第一个ZIS集成

你需要什么?

注册集成名称

构建集成

创建一个初学者包

定义一个ZIS动作

定义一个ZIS流

定义ZIS作业规格

代码完成

部署和测试集成

上传bundle

安装作业规范

测试集成