使用ZCLI

请注意: Zend亚博esk ZCLI (Command Line Interface)目前处于公测阶段。它完全由Zendesk支持，但可能随时更改。亚博

ZCLI是一个用于开发Zendesk应用程序的命令行工具。亚博您可以使用ZCLI在本地构建、测试和打包Zendesk应用程序。亚博ZCLI用于替换ZAT (Zende亚博sk App Tools)， ZAT目前处于维护模式。

在开始之前

要安装ZCLI，您需要以下内容:

Node.js 14.17.3或更高版本
如果你使用的是Linux，根据你的发行版，你需要运行:
- Debian / Ubuntu:安装libsecret-1-dev
- Red hat的:Sudo yum安装libsecret-devel
- Arch Linux:sudo pacman -S libsecret

安装和更新ZCLI

将ZCLI作为Node.js包安装。

安装ZCLI

在你的电脑终端上运行:

               
                npm安装@亚博zendesk / zcli - g

确认ZCLI已经安装并可以使用:

               
                zcli帮助

该命令返回已安装的ZCLI版本和其他帮助信息。

如果需要更新ZCLI，请重新运行安装命令。如果您安装的版本已经过期，ZCLI会发出警告。

命令

本文介绍了最常见的ZCLI命令。有关完整的命令列表，请参阅GitHub上的ZCLI文档．

App配置文件

亚博Zendesk应用程序支持可选zcli.apps.config.json文件在应用程序的根目录。您可以使用该文件:

存储应用程序id。这个id在Zendesk实例中是唯一的。亚博
定义测试安装

注意:如果您以前使用过ZAT，zcli.apps.config.json取代了.zat而且settings.yml文件。

身份验证

以下ZCLI命令需要使用Zendesk进行身份验证:亚博

应用程序:创建
应用:包
应用:更新
应用:验证

您可以使用以下方法之一验证ZCLI:

重要的是:如果您是使用Windows子系统for Linux (WSL)的Windows用户，请使用环境变量．要在Linux环境中管理概要文件，ZCLI需要X11。X11在大多数Windows机器上不受支持，即使使用WSL也是如此。

配置文件

每个ZCLI配置文件都与Zendesk子域相关联。亚博要添加配置文件，运行:

             
              Zcli login -i

当出现提示时，输入子域、电子邮件地址和密码。如果您正在使用API令牌，请将“/token”附加到您的电子邮件地址，并输入您的API令牌作为密码。

登录命令为您输入的子域创建一个概要文件。ZCLI将凭据安全地保存在操作系统(OS)的密钥存储库中。

更新概要文件

ZCLI支持每个子域一个配置文件。要更改子域的凭据，请运行Zcli login -i再次命令。当出现提示时，输入您的新凭证。

转换配置文件

要获得可用配置文件的列表，运行:

             
              zcli概要:列表

该命令按子域返回可用概要文件的列表，包括活动的概要文件。

使用实例切换当前配置文件。

             
              zcli概要:使用｛子域名}

取代{子域名}使用列表中的子域。

删除配置文件

要删除活动配置文件，执行以下命令:

             
              zcli注销

当您删除一个概要文件时，它也会删除相关的身份验证凭证。

要删除活动配置文件以外的配置文件，执行命令:

             
              zcli概要文件:删除｛子域名}

取代{子域名}配置文件的子域。

环境变量

还可以使用Zendesk使用环境变量对ZCLI进行身份验证。亚博这允许您在持续集成和持续部署(CI/CD)管道中使用ZCLI。如果您的开发环境不支持ZCLI概要文件，它也很有帮助。

支持的认证方案

ZCLI支持以下环境变量和相关的身份验证方案。

身份验证方案	所需的环境变量
OAuth 2.0访问令牌	`亚博ZENDESK_SUBDOMAIN`,`亚博ZENDESK_OAUTH_TOKEN`
API的令牌	`亚博ZENDESK_SUBDOMAIN`,`亚博ZENDESK_EMAIL`,`亚博ZENDESK_API_TOKEN`
基本身份验证	`亚博ZENDESK_SUBDOMAIN`,`亚博ZENDESK_EMAIL`,`亚博ZENDESK_PASSWORD`

重要的是:如果使用API令牌身份验证，则不要将“/token”附加到亚博ZENDESK_EMAIL价值。ZCLI为您追加了这个后缀。

出于安全原因，不建议使用基本身份验证。取决于您的设置亚博ZENDESK_PASSWORD变量可能会以明文形式存储您的Zendesk密码。亚博

使用环境变量验证ZCLI

使用环境变量对ZCLI进行身份验证的步骤因您首选的身份验证方案、操作系统和环境而异。

使用环境变量对ZCLI进行身份验证

设置亚博ZENDESK_SUBDOMAIN变量到您的Zendesk帐户的子域亚博。

macOS

               
                echo 'export 亚博ZENDESK_SUBDOMAIN="{subdomain}"' >> ~/.zshrc .

窗户

               
                setx 亚博ZENDESK_SUBDOMAIN "{子域}"

Linux

               
                echo 'export 亚博ZENDESK_SUBDOMAIN="{subdomain}" " >> ~/.bashrc .

设置首选身份验证方案所需的其他环境变量。

例如，要使用API令牌身份验证，请设置亚博ZENDESK_EMAIL变量为您的电子邮件地址和亚博ZENDESK_API_TOKEN变量到您的Zendesk API令亚博牌。

macOS

               
                echo 'export 亚博ZENDESK_EMAIL="{email}"' >> ~/.zshrc .echo 'export 亚博ZENDESK_API_TOKEN="{api_token}"' >> ~/.zshrc .

窗户

               
                setx 亚博ZENDESK_EMAIL "{email}"setx 亚博ZENDESK_API_TOKEN "{api_token}"

Linux

               
                echo 'export 亚博ZENDESK_EMAIL="{email}"' >> ~/.bashrc .echo 'export 亚博ZENDESK_API_TOKEN="{api_token}"' >> ~/.bashrc .

重新加载终端的外壳。

macOS

               
                源~ / . zshrc

窗户

关闭并重新打开终端。

Linux

               
                源~ / . bashrc

作为可选步骤，打印每个环境变量的值以确保它已设置。

macOS和Linux

运行printenv {var_key}．取代{var_key}使用环境变量的键。例子:

               
                printenv 亚博ZENDESK_SUBDOMAIN

窗户

运行% {var_key} %回响．取代{var_key}使用环境变量的键。例子:

               
                回声% ZE亚博NDESK_SUBDOMAIN %

优先顺序

一次只能使用一种身份验证方法或方案对ZCLI进行身份验证。如果同时使用ZCLI环境变量和ZCLI概要文件，则ZCLI仅使用环境变量进行身份验证。

如果为多个身份验证方案指定环境变量，ZCLI使用以下优先顺序:

OAuth 2.0访问令牌
API的令牌
基本身份验证

例如，如果指定亚博ZENDESK_SUBDOMAIN,亚博ZENDESK_OAUTH_TOKEN,亚博ZENDESK_EMAIL,亚博ZENDESK_API_TOKEN变量，ZCLI将只尝试OAuth身份验证亚博ZENDESK_SUBDOMAIN而且亚博ZENDESK_OAUTH_TOKEN变量。如果亚博ZENDESK_OAUTH_TOKEN变量包含无效的OAuth 2.0访问令牌，认证失败。的API令牌身份验证亚博ZENDESK_EMAIL或亚博ZENDESK_API_TOKEN变量。

为Zendesk应用程序创建启动文件亚博

使用ZCLI为新的Zendesk应用程序创建启动文件。亚博

在你的shell中，导航到你将用于存储应用程序的目录。例如:

               
                cd项目

要创建基本的应用程序启动器文件，运行:

               
                zcli应用:新

或者，使用——脚手架=反应选项，使用亚博Zendesk React应用程序脚手架．

               
                Zcli apps:new——脚手架＝反应

在提示符下输入:
- 应用程序的目录名
- 你的名字
- 你的电邮地址
- 你的网站URL(可选)
- 应用程序的名称
ZCLI在您输入的目录中创建应用程序启动器文件。如果使用基本启动器文件，则该目录包括Zendesk应用程序所需的文件亚博．

在本地测试Zendesk应亚博用程序

您可以使用ZCLI启动本地web服务器，让您在计算机上运行Zendesk应用程序。亚博你不需要先打包、上传或安装应用程序。如果你想在进行更改时测试或预览应用程序，这是非常有用的。

ZCLI服务器不支持Zendesk Apps框架(ZAF)的一些特性。亚博指ZCLI服务器限制．

如果你的应用包含安装设置，指定测试设置值zcli.apps.config.json文件作为可选的第一步。看到定义测试设置．
如果没有指定设置值zcli.apps.config.json，当您启动ZCLI服务器时，ZCLI会提示您输入这些值。
如果您以前使用过ZAT，zcli.apps.config.json取代了settings.yml文件。ZCLI服务器不从settings.yml或默认的从manifest.json．
要启动应用程序的ZCLI服务器，运行:
```
               
                zcli应用:服务器｛app_directory}
               
```
取代{app_directory}与应用程序根目录的相对路径。如果你的shell已经在应用程序的根目录中，忽略这个参数。
如果你的应用程序包含一个没有默认值的安装设置zcli.apps.config.json， ZCLI会交互式地提示您输入值。
过了一会儿，会出现一条状态消息，通知您服务器已经启动。
注意:按“Ctrl+C”停止服务器。
在浏览器中打开一个匿名或私人窗口。我们推荐Chrome或Firefox。Safari不支持ZCLI web服务器。
隐身或私有窗口不会缓存应用程序使用的文件。缓存的文件可能会阻止浏览器显示应用程序的最新更改。

登录到Zendesk并亚博导航到显示应用程序的URL。这个URL根据应用程序的不同而不同应用程序位置．

例如，你可以在Support ticket侧栏中从任何ticket URL查看应用:

               
                https：//｛子域名}．亚博．com/代理/票/｛123}

附加? zcli_apps = true到URL，并重新加载页面。

例如:

               
                https：//｛子域名}．亚博．com/代理/票/｛123}?zcli_apps＝真正的

根据应用程序的位置，您可能需要采取一些额外的步骤来显示应用程序。
例如，要在票务侧栏中显示应用程序，请单击应用程序图标。这将打开应用程序托盘。
如果您的应用程序没有出现在应用程序托盘，单击刷新图标重新加载你的应用程序。

使用自定义端口

默认情况下，ZCLI服务器运行在端口4567上。要在另一个端口上运行服务器，请使用zcli应用:服务器命令的——港口国旗。例子:

             
              Zcli apps:server——port＝4254

要预览应用程序，请添加? zcli_apps ={港口}到Zendes亚博k URL。例子:

             
              https：//｛子域名}．亚博．com/代理/票/123?zcli_apps＝4254

ZCLI服务器限制

ZCLI服务器不支持以下ZAF特性:

安全设置。ZCLI服务器不会呈现安全设置。
应用程序的需求。ZCLI服务器不能创建资源亚博电脑端requirements.json．类似地，您不能访问要求对象使用ZCLI服务器。
事件通知向App发送通知端点。

作为一种变通方法，您可以使用ZCLI来打包、上传和更新应用程序打包并安装一个私有Zendesk应用程序亚博而且更新私有Zendesk应用亚博．

打包并安装一个私有Zendesk应用程序亚博

ZCLI服务器不支持一些ZAF特性。要预览使用这些功能的应用程序，请使用zcli应用程序:创建命令。该命令将应用程序打包并安装为Zendesk实例中的私有应用程序。亚博安装完成后，就可以使用ZCLI更新app并测试更改。

使用命令:

             
              zcli应用程序:创建｛app_directory}

取代{app_directory}与应用程序根目录的相对路径。如果你的shell已经在应用程序的根目录中，忽略这个参数。

命令:

对应用程序的文件运行验证测试。如果测试检测到问题，该命令将停止并返回错误消息。
将应用程序的文件打包成ZIP文件。ZCLI将ZIP文件保存在tmp文件夹在应用程序的根目录。
将ZIP文件作为私有应用程序上传并安装到Zendesk实例。亚博如果您正在使用概要文件，则这是活动概要文件的实例。如果成功，ZCLI将删除ZIP文件tmp文件夹中。
创建一个zcli.apps.config.json文件在本地应用程序目录。该文件包含应用程序id。这个id在Zendesk实例中是唯一的。亚博如果您正在使用概要文件，则这是活动概要文件的实例。

更新私有Zendesk应用亚博

您可以使用zcli应用:更新命令更新私有应用zcli.apps.config.json文件在应用程序的根目录。该文件必须包含有效的app_id财产。

如果它不存在，则创建一个zcli.apps.config.json文件在应用程序的根目录。
如果你以前用过zcli应用程序:创建，该命令将创建一个zcli.apps.config.json包含app_id．跳到步骤4。
为了得到app_id值，以管理员身份登录Zendesk产品。亚博然后在同一浏览器中打开产品的相应页面:
- 支持:https://{子域名}.zendes亚博k.com/api/support/apps/installations.json
- 聊天:https://{子域名}.zendes亚博k.com/api/chat/apps/installations.json
- 销售:https://{子域名}.zendes亚博k.com/api/sell/apps/installations.json
取代{子域名}你的Zendesk子亚博域。找到app_id为你的应用程序的响应。

在zcli.apps.config.json，添加app_id作为根级JSON对象的属性。例子:

               
                ｛“app_id”：1234}

运行:
```
               
                zcli应用:更新｛app_directory}
               
```
取代{app_directory}与应用程序根目录的相对路径。如果你的shell已经在应用程序的根目录中，忽略这个参数。
运行命令后，刷新应用程序以预览更改。

打包一个Zendesk应亚博用程序进行手动上传

当你的应用程序完成后，你可以把它打包成一个ZIP文件。然后，您可以将ZIP文件作为公共应用程序提交到Zendesk市场。您也可以手动将亚博ZIP文件作为私有应用程序上传到Zendesk实例。

提示:Zend亚博esk市场对公共应用程序有额外的要求。指创造品牌应用资产而且创建内容．

要打包应用程序，运行:
```
               
                zcli应用:包｛app_directory}
               
```
取代{app_directory}与应用程序根目录的相对路径。如果你的shell已经在应用程序的根目录中，忽略这个参数。
命令:
- 对应用程序的文件运行验证测试。如果测试检测到问题，该命令将停止并返回错误消息。
- 将应用程序的文件打包成ZIP文件。ZCLI将ZIP文件保存在tmp文件夹在应用程序的根目录。
要将ZIP文件作为公共应用程序提交到Zendesk市场，请参阅亚博提交应用．
要将ZIP文件作为私有应用程序上传和安装，请参见上传和安装私有应用程序．

限制

ZCLI不支持Zendesk Guide主题的预览。亚博要预览指南主题，请使用ZAT主题预览命令。请参阅ZAT命令文档．
的事件通知向App发送通知端点。作为一种变通方法，您可以使用ZCLI将应用程序安装为私有应用程序。看到打包并安装一个私有Zendesk应用程序亚博．或者，您也可以使用ZAT本地web服务器并设置Send Notification to App request'sapp_id参数0．

开始

应用开发者指南

创建应用

设计应用

亚博Zendesk Apps Tools (ZAT)

使用ZCLI

在开始之前

安装和更新ZCLI

命令

App配置文件

身份验证

配置文件

更新概要文件

转换配置文件

删除配置文件

环境变量

支持的认证方案

使用环境变量验证ZCLI

优先顺序

为Zendesk应用程序创建启动文件亚博

在本地测试Zendesk应亚博用程序

使用自定义端口

ZCLI服务器限制

打包并安装一个私有Zendesk应用程序亚博

更新私有Zendesk应用亚博

打包一个Zendesk应亚博用程序进行手动上传

限制