ZIS自定义动作
自定义操作是HTTP请求的包装器。您可以在action状态下使用自定义操作向Zendesk或第三方服务(如Slack或Shopify)发出API请求。亚博
定义自定义操作
要使用自定义操作，必须将该操作定义为ZIS包中的独立资源。下面的示例定义了一个自定义操作，该操作将消息发布到外部API。
“external_api.post_message”：｛“类型”：“子::行动::Http”，“属性”：｛“名称”：“external_api.post_message”，“定义”：｛“方法”：“职位”，“美元url。”：“.external_api_url美元”，“requestBody”：｛“美元文本。”：“.message美元”｝｝｝｝
在action状态下使用自定义操作
要在action状态下调用自定义操作，请在状态中使用“zis:INTEGRATION:action:CUSTOM_ACTION_NAME”ActionName．将“INTEGRATION”替换为集成键。将“CUSTOM_ACTION_NAME”替换为properties.name自定义操作定义中的值。例子:
“PostTicketCreatedMessageToExternalApi”：｛“类型”：“行动”，“ActionName”：“子:example_integration:行动:external_api.post_message”，“参数”：｛“external_api_url”：“EXTERNAL_API_URL”，”消息。”：" ID为{{$.input.ticket_event.ticket.id}}的新票据已被创建!"｝，“下一个”：“NextState”｝
重要的是:自定义操作定义必须与action状态在同一个bundle中。Action状态不能从另一个bundle中调用Action。
操作定义支持的属性
自定义操作定义支持以下属性。
| 的名字 | 类型 | 强制性的 | 描述 |
|---|---|---|---|
| 类型 | 字符串 | 真正的 | 资源名称。对于自定义动作定义，这个值必须是"ZIS:: action::Http" |
| 属性 | 对象 | 真正的 | 资源的属性 |
| properties.name | 字符串 | 真正的 | 集成中操作的唯一名称。必须与资源的键匹配。最多20个字符，由小写字母(a-z)、大写字母(a-z)、数字和下划线(_)组成。 |
| properties.definition | 对象 | 真正的 | 为动作定义HTTP请求 |
| properties.definition.method | 字符串 | 真正的 | 请求的HTTP方法。取值范围为GET、HEAD、PUT、POST、DELETE、OPTIONS、PATCH、TRACE。 |
| properties.definition.url | 字符串 | 需要url或路径 |
HTTP请求的URL。不能和路径．看到指定请求路径或URL |
| properties.definition.path | 字符串 | 需要url或路径 |
Zendesk API端点的相对路径。亚博不能和url．看到指定请求路径或URL |
| properties.definition.connectionName | 字符串 | 假 | 项目名称连接用于授权HTTP请求。看到使用连接对ZIS流中的API请求进行身份验证 |
| properties.definition.headers | 对象数组 | 假 | HTTP请求的头值。格式化为对象的数组关键而且价值属性。看到接受的HTTP报头值 |
| properties.definition.queryParams | 对象数组 | 假 | 查询HTTP请求的参数。格式化为对象的数组关键而且价值属性 |
| properties.definition.contentType | 字符串 | 假 | HTTP请求体的媒体类型。有效值为“application/json”和“application/x-www-form-urlencoded”。默认为"application/json" |
| properties.definition.requestBody | 对象 | 假 | HTTP请求的主体 |
指定请求路径或URL
类指定HTTP请求URL时，可以定义自定义操作路径或url选择。
要向集成的Zende亚博sk实例发出Zendesk API请求，请使用路径选择。ZIS自动解析实例的子域和主机域。例如，ZIS解决了一个路径/api/v2/tickets/123到https路径价值。
要向外部站点或其他Zendesk实例发出请求，请使用亚博url选择。的urlvalue必须是绝对URL，例如“https”
接受的HTTP报头值
的头选项包含请求的HTTP头作为JSON对象数组。每个对象包含一个键-值对。键是HTTP头名称。HTTP报头值。
对于一个ZIS自定义动作，HTTP头名称只能包含:
字母数字字符(a-z, a-z, 0-9)
以下特殊字符:
！，＃，＄，％，＆，＇，＊，+，-，．，＾，＿，｀，|，～
HTTP头值只能包含可见字符、制表符和空格。
向自定义动作传递参数
定义自定义操作时，可以使用JSONPath为值创建占位符。调用action时，使用action状态参数为占位符传递一个值。
例如，以下自定义操作定义包含“＄.message”占位符。
“example.post_new_user_message”：｛“类型”：“子::行动::Http”，“属性”：｛“名称”：“example.post_new_user_message”，“定义”：｛“方法”：“职位”，“美元url。”：“https://example.com”，“requestBody”：｛“美元文本。”：“.message美元”｝｝｝｝
下面的Action状态传递一个值＄.message”参数．运行时，状态将替换＄.message"具有此值的占位符。
“PostNewUserMessageToExampleSite”：｛“类型”：“行动”，“ActionName”：“子:example_integration:行动:example.post_new_user_message”，“参数”：｛”消息。”："已为{{$.input.user_event.user.email}}创建新用户。"｝，“下一个”：“NextState”｝
注意:不能在JSON属性键中使用参数占位符。相反，使用Transform操作创建一个使用参考路径作为钥匙。然后可以将该对象作为参数值传递。有关示例，请参见ZIS Bundle:使用jq创建HTTP请求体．
验证操作的API请求
您可以使用连接对自定义操作的API请求进行身份验证。连接包含服务或系统(如Slack或Zendesk)的凭据。亚博看到理解连接．
使用ZIS jwt验证请求
您可以使用JSON Web令牌(jwt)来验证请求是否来自ZIS集成。当自定义操作向非zendesk URL发出请求时，ZIS在亚博X-ZIS-Authorization请求头。您可以使用集成的JWT公钥验证JWT的签名。当你注册集成．有关此设置的示例，请参见使用jwt验证来自ZIS的请求．
注意:ZIS jwt是不可互换的亚博Zendesk应用框架(ZAF) JWTs．ZIS JWT签名采用RS256签名算法。ZAF JWT签名只支持HS256签名算法。中的ZIS只发送ZIS jwtX-ZIS-Authorization请求头。你可以在任何请求头中发送ZAF jwt。
ZIS JWT声称
ZIS智威汤逊的有效载荷包含以下声明。
| 的名字 | 类型 | 描述 |
|---|---|---|
| 经验值 | 整数 | JWT过期的Unix时间戳(从Unix纪元开始的秒数)。对于ZIS JWTs，该经验值是5分钟后吗iat |
| iat | 整数 | 发出JWT时的Unix时间戳 |
| 国际空间站 | 字符串 | JWT的发行者。对于ZIS JWTs，该国际空间站“子” |
在ResultPath中捕获操作的响应
要使用操作的响应，请指定ResultPath．如果HTTP响应是JSON格式的，则有效负载可在“＄{{YOUR_RESULT_PATH}}”。否则，响应可在“＄{{YOUR_RESULT_PATH}} .__httpresponse”。
在这个例子中，一个动作搜索一个具有特定ID的Zendesk票据:亚博
“亚博zendesk.get_ticket_by_id_action”：｛“类型”：“子::行动::Http”，“属性”：｛“名称”：“亚博zendesk.get_ticket_by_id_action”，“定义”：｛“方法”：“获得”，美元”的道路。”：“/ api / v2 /票/ {{$ .ticket_id}} . json”，“connectionName”：“亚博zendesk”｝｝｝
这可以在流中引用。例子:
“GetTicketByID”：｛“类型”：“行动”，“ActionName”：“子:example_integration:行动:zendes亚博k.get_ticket_by_id_action”，“参数”：｛“ticket_id美元。”：“.ticket_id美元”｝，“ResultPath”：“.get_ticket_by_id_result美元”，“下一个”：“UseMyTicketResults”｝
在上面的例子中，如果Zendesk API找到并返回具有相亚博应ID的票据，则票据有效负载可用于UseMyTicketResults状态在"＄.get_ticket_by_id_result”。
JSON数组响应
如果操作响应的根对象是一个JSON数组，则必须设置ResultPath到非根路径。例如,ResultPath也许吧。”＄.my_result" but not "＄"．
以JSON数组作为根对象的示例动作响应:
［｛“id”：1，“名称”：“约翰·史密斯”｝，｛“id”：2，“名称”：“简·史密斯”｝］
设置非根用户失败ResultPath将导致流中稍后的状态无法解析元数据，例如“＄.account_id"和"＄.input”。
处理错误
如果自定义动作的HTTP请求失败或接收到非2xx HTTP响应状态码，动作状态将返回一个运行时错误。默认情况下，这会导致整个ZIS流失败。
如果自定义操作的HTTP请求接收到429或500 HTTP响应状态码，ZIS将尝试重试失败的流。看到ZIS流重试逻辑．
你可以使用抓块以避免在Action状态返回运行时错误时ZIS流失败。看到使用Catch块．
使流中的操作可以访问数据
流可以访问一个JSON对象，其中包括触发事件的有效负载(“＄.input”),“＄.account_id”、“＄.subdomain"，和"＄.integration_key”。您可以将对象添加到＄对象使用ResultPath对于操作，使来自一个状态的数据可用于后续状态。
限制
自定义操作不能接收超过2 MB的响应有效负载。如果响应超过这个限制，action状态将返回一个运行时错误。看到流状态重试和错误处理
自定义操作的HTTP请求有10秒的超时。如果请求在超时时间内没有收到响应，Action状态将返回一个运行时错误。看到流状态重试和错误处理
额外的信息
- 中的示例自定义操作子的例子
- 使用jwt验证来自ZIS的请求