借助 uCommand 执行复杂任务

uCommand 是一款 CLI 工具，可提供诸多与 IBM UrbanCode Deploy 一同使用的易用功能。您可以从 UrbanCode Developer Center 的插件部分下载 uCommand。

在使用 UrbanCode Deploy 时，您的大部分互动都通过 Web 界面来完成。若要将 UrbanCode 集成到更广泛的管架结构，即所有组件都互联化且自动化，您需要一种通过 CLI 执行动作的可靠方法。

UrbanCode Deploy 与正式版的 CLI 工具 (udclient) 配套推出。但是，udclient 缺乏一些重要功能，如 UrbanCode 配置的备份、恢复和升级，以及等待完成的应用流程请求功能等。

uCommand 的设计目的在于填补这些空白。该工具能够为预定义函数提供简单的动作，还可以为大多数 UrbanCode Deploy API 实现 PHP 实施。它的设置和使用非常方便。uCommand 需要 Web URL 用户名以及 UrbanCode 服务器的授权令牌。通过设置向导，可以帮助您在首次使用时对该工具进行配置，包括安全连接服务器所需的授权令牌。

功能

uCommand 的一些优势包括：

• 易用性
• 可供开发者使用
• 提供常用动作的执行
• 易于实现 UrbanCode Deploy 任务的自动化

由于该工具基于 UrbanCode Deploy udclient 和 REST API 而构建，因此您无需运行多个命令，便可执行特定的动作。

举例来说，若要使用 udclient 和 REST API 手动备份 UrbanCode Deploy 配置，您需要：

1. 找出构成每个应用的所有组件、流程和资源。
2. 在备份应用本身之前，备份每个单独项目。

借助 uCommand，这些手动步骤将会全部合并在一起。若要执行完整的备份，您无需了解每个配置元素之间的关系；只需运行单个命令即可：

php ucommand.php backup

借助 uCommand，您将能够：

• 备份服务器配置。
• 将服务器配置恢复到具有相同 IBM UrbanCode Deploy 发行版本的服务器上。
• 在多个 UrbanCode Deploy 服务器之间共享 UrbanCode Deploy 配置。
• 创建包含可部署工件的组件版本。
• 将一系列版本捆绑到可一同部署的快照中。
• 将快照从一个服务器推广到另一服务器。
• 运行部署流程。

本文中使用了一款带有相关组件和流程的简单 UrbanCode Deploy 应用：

• 名称 ：LAMP
• 描述 ：用于部署 LAMP 服务器的应用
• 组件 ：
  • Apache
  • MySQL
  • PHP
• 流程 ：部署

回页首

备份并恢复 UrbanCode Deploy 配置

默认情况下，UrbanCode Deploy 不会提供备份和恢复其整个配置的工具。不过，uCommand 提供了一些简单的动作来运行这些任务：

php ucommand.php --action=backup php ucommand.php --action=restore --dir={{backup_directory}}

回页首

共享配置和工件

uCommand 旨在与一个或多个 UrbanCode Deploy 服务器一同工作。在备份期间导出的文件可在同一 UrbanCode Deploy 服务器中恢复。同时，这些文件也可轻松与其他 UrbanCode Deploy 服务器共享。

借助 uCommand，您可以和其他团队共享数据，从单个组件到整个配置，甚至快照及其从属组件（工件文件）。

此外，您还可以将精确的配置和数据复制到多个服务器中，以执行与源服务器相同的部署。举例如下：

使用 uCommand 共享配置和工件

若要将应用从一个 UrbanCode 源服务器共享到目标服务器：

php ucommand.php   --action=promoteApplication   --application{{application_name}}

若要共享快照，包括其工件：

php ucommand.php   --action=promoteSnapshot   --snapshot={{snapshot_name}}

回页首

运行应用流程

UrbanCode Deploy 主要通过 Web 界面来使用。不过，也有一些特殊情况，即需要自动化部署或在脚本内运行部署，例如：UrbanCode Deploy 需要在一个部署自动化管架中自动运行时，或者从一个未提供用户界面的服务器 CLI 自动运行时。

借助 uCommand，您可以运行带有参数（应用名称、流程名称、属性等）的应用流程。uCommand 还可以提供易于使用的动作，用以请求执行应用流程并等待其完成。完成后，将会返回部署成功或失败：

php ucommand.php   --action=runAndWait   --file={{request_json_file}}

如果请求 JSON 文件包含以下信息：

{     "application":"APPLICATION_NAME",     "applicationProcess":"APPLICATION_PROCESS",     "description":"GENERIC_DESCRIPTION",     "environment":"ENVIRONMENT_TO_DEPLOY",     "onlyChanged":"APPLY_CHANGED_VERSIONS_ONLY",     "post-deploy-message":"MESSAGE_POST_DEPLOYMENT",     "snapshot":"SNAPSHOT_NAME" }

您可以使用 uCommand 作为一个 CLI 工具，从您的连续集成/连续交付 (CI/CD) 管架中运行部署。

回页首

设置 uCommand

uCommand 使用写入到 PHP 中的包装脚本，用以合并 udclient 和 REST API，以便用户能够执行日常动作。该工具首先会生成 API 请求，将登录信息（Web URL、用户名、授权令牌）与待执行的动作和相关参数合并到一起。之后，生成的请求会通过 PHP 执行函数在 CLI 中执行。

uCommand 不仅能够为可用的 UrbanCode API 提供 PHP 层，还能够对其进行合并，以构建更复杂的函数。这意味着，对于某些动作而言，会依次调用多个 API，结果也会合并到一起。

ucommand.php

ucommand.php 是一个可执行的 PHP 脚本，用于触发工具中可用的多个动作，以在 UrbanCode Deploy 中检索或创建数据。

该脚本负责：

• 对象实例
• 配置设置
• 参数确认
• 执行动作
• 帮助

有关 uCommand 可以执行的可用动作列表，请参见Actions（动作）一节。

回页首

配置 uCommand

uCommand 带有一系列默认设置，不过要确保工具的正常执行，需要设置一些服务器特定的值。配置文件位于工具的 config 子目录下。

设置向导

设置脚本旨在帮助您进行 uCommand 配置。 从 uCommand 主目录中运行设置脚本：

cd {{ucommand_directory}} php ucommand.php --action=setup

此时，会引导您进行一系列配置步骤，包括请求安全连接到 UrbanCode Deploy 服务器的授权令牌等。设置还会检查是否满足正确运行 uCommand 所需的所有先决条件。

设置脚本会在 config/servers/ 文件夹中生成服务器配置文件。该文件以您提供的别名命名：

别名：'{{my_server}}' file:'{{my_server}}.server.php'

可以保存多个服务器配置，然后从中选择要使用的配置。

若要选择用于 uCommand的服务器配置：

php ucommand.php   --action=config   --alias={{alias_name}}

回页首

运行 uCommand

若要确保正常运行 uCommand，需要：

• PHP 5.4+
• Java 1.6.0+
• 整个 uCommand 文件夹的读写和执行权限
• 有效的配置

若要执行任何动作，在设置完成后运行该命令：

cd {{UCOMMAND_DIRECTORY}} php ucommand.php   --action={{ACTION}}   --{{argument_2}}={{VALUE_2}}   ...

动作的结果是 CLI 或文件中的输出。具体视配置文件中输出集的类型而定。每个动作还会提供日志信息及反馈。该信息包含操作成功或失败的通知。

回页首

动作

有很多动作可用于 uCommand。若要请求一个动作：

php ucommand.php   --action={{ACTION}}   --{{argument_1}}={{VALUE_1}}   --{{argument_2}}={{VALUE_2}}   ...

注：参数指定的次序与动作能否正确执行无关。

对于每个支持的动作，uCommand 均提供有在线帮助及工具使用详情。若要获取特定动作的帮助：

php ucommand.php   --action={{ACTION}}   --help

应用流程动作

作为一个参数传送应用流程请求 ID 后，便会返回流程的状态。

• 0 - 成功完成
• 2 - 已初始化
• 3 - 正在执行
• 4 - 待决中
• 5 – 已取消
• 100 - 代理不在线
• 255 - 执行失败

应用流程请求 ID 可以从 Web 浏览器中输入以下 UrbanCode Deploy URL 获取。

{{SERVER_URL}}/#applicationProcessRequest/82d6119e-b9fd-4396-9cee-7cc484be4d77

或者，ID 可以从 uCommand 动作 run 的 CLI 输出中获取。

运行应用流程，该流程在 JSON 文件中定义如下：

{  "application":{{APPLICATION_NAME}},     "applicationProcess":{{APPLICATION_PROCESS}},     "description":{{GENERIC_DESCRIPTION}},     "environment":{{ENVIRONMENT_TO_DEPLOY}},     "onlyChanged":{{APPLY_CHANGED_VERSIONS_ONLY}},     "post-deploy-message":{{MESSAGE_POST_DEPLOYMENT}},     "snapshot":{{SNAPSHOT_NAME}},  "properties" :{     {{PROPERTY}} :{{VALUE}}   } }

如果应用流程请求一个或多个要运行的属性，这些属性将会在 JSON 文件的 properties 值中列出并定义。

合并动作 run 和 requestStatus 。传送 JSON 文件后，便会请求应用流程（由 run 动作定义），并等待完成。

runAndWait 动作用于在控制台中打印应用流程请求的每个状态变化（例如，从 Pending（待决中） 到 EXECUTING（正在执行） 到 CLOSED（已关闭） ）。 runAndWait 动作会在流程完成时退出（退出代码 0、5、255）或在代理不在线时退出（退出代码 100）。

等待应用流程完成，然后退出，同时返回流程结果。有关退出代码列表，请参见 requestStatus 表格 。

UrbanCode 配置动作

备份不需要任何特殊配置。导出的 JSON 文件保存在 ucd.config.php 配置文件中所定义的输出文件夹中。该输出文件夹的结构为：

OUTPUT_FOLDER

• 应用
  • APPLICATION _NAME
    • 组件
    • APPLICATION_NAME.json
• 蓝图
• 组件
• 组件模板
• 流程
• 资源
• 资源模板
• 设置

配置完成 clean.config.php 文件后（请参见附录查看示例）， cleanAll 会采用该文件中定义的规则，并验证哪些 UrbanCode Deploy 配置元素与规则匹配。

尤其是， cleanAll 会验证 UrbanCode Deploy 配置元素的名称是否包含在 config 文件的 include 一节所定义的特定模式。如果元素名称与模式匹配，则将会被移除。

exclude 规则优先于 include 规则。举例来说，如果某个元素同时与 include 和 exclude 规则匹配， 该元素将不会从服务器中移除。

例如，配置（提取）：

$config['include']['component'] = ".DEV"; $config['exclude']['component'] = ".TEST"; $config['include']['application'] = ".APP";

如果未对特定配置元素定义规则，则需同时为 include 和 exclude 参数定义默认规则：

$config['include']['default'] $config['exclude']['default']

position 参数用于定义给定模式为确保匹配性而应放置的位置。

位置值包括：

• start ：模式位于名称的开头
• end ：模式位于名称的结尾
• empty ：模式位于名称的任何位置

配置（提取）的示例包括：

$config['include']['component'] = ".DEV"; $config['exclude']['component'] = ".TEST"; $config['include']['position'] = "end"; $config['exclude']['position'] = "";

若要分叉应用，将完整的应用复制到相同的 UrbanCode Deploy 服务器即可。在应用名称和组件名称的结尾添加新后缀。

当由于开发方面的原因，必须为 UrbanCode Deploy 开发新功能，而又不能破坏运行配置集时，该功能非常有用。

动作 forkApplication 用于获取定义应用及其相关组件和通用流程的应用名称和旧后缀，然后创建完整拷贝。旧后缀会替换为新后缀。

举例来说，使用以下应用：

• 应用名称：LAMP_v1
• 组件：
  • Apache_v1
  • MySQL_v1
  • PHP_v1
• 通用流程：Deploy_v1

运行命令：

php ucommand.php   --action=forkApplication   --application=LAMP_v1   --old="_v1"   --new="_v2"

创建结果：

• 应用名称 ：LAMP_v2
• 组件 ：
  • Apache_v2
  • MySQL_v2
  • PHP_v2
• 通用流程 ：Deploy_v2

restore 动作用于重新创建已从第一个 UrbanCode Deploy 服务器导出到第二个服务器的 UrbanCode Deploy 配置，以在 backup 动作中定义的结构化文件夹为参数。

建议针对一个干净且空的 UrbanCode Deploy 服务器运行 restore 动作；否则，可能不会出现预期结果。

使用 promoteConfig 或 promoteApplication 动作，可将配置导入到一个非空的 UrbanCode Deploy 服务器中。

应用 JOSN 文件应为通过备份动作提供的文件。 该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。

不建议针对包含有您尝试导入的应用的 UrbanCode Deploy 服务器运行 restore 动作；对于此类服务器，应使用 promoteApplication 动作。

组件 JOSN 文件应为通过 backup 动作提供的文件。该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。

不建议针对包含有您尝试导入的应用的 UrbanCode Deploy 服务器运行 restore 动作；对于此类服务器，应使用 promoteConfig 或 promoteApplication 动作。

组件模板 JOSN 文件应为通过 backup 动作提供的文件，该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。

应用 JOSN 文件应为通过 backup 动作提供的文件，该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。升级包括环境在内，但不包括资源模板和蓝图。

组件 JOSN 文件应为通过 backup 动作提供的文件，该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。

组件模板 JOSN 文件应为通过 backup 动作提供的文件，该文件与通过 UrbanCode Deploy Web UI 上的导出按钮生成的文件相同。

环境动作

环境 JSON 文件应采用环境创建模板中所定义的结构。

如果出现下述情况， createEnvironment 动作将会失败：

• 应用不存在
• 环境名称已存在
• 蓝图不存在
• 基本资源不存在

在作为一个参数传送环境 ID 时，uCommand 会将环境属性导出到 JSON 文件中。如果环境名称已传送，则还需要应用名称。如果多个组件使用相同的值，属性将会合并到一个文件中。如果某个属性设置为 secure（安全） ，该值将作为四个星号 ( **** ) 导出，以免泄露密码。例如：

{ "propertyName":"PROPERTY_NAME", "value":"PROPERTY_VALUE", "secure":false, "components":[ "COMPONENT_1", "COMPONENT_2", "COMPONENT_3" ] }, { "propertyName":"PROPERTY_NAME", "value":"****", "secure":true, "components":[ "COMPONENT_1" ] },

在作为一个参数传送环境 ID 时，uCommand 会将环境属性导入到 JSON 文件中。如果环境名称已传送，则还需要应用名称。该 JSON 文件应采用 exportEnvironmentProperties 动作中所定义的结构。可以设置任何属性值，每个组件对应一个值，或者一批组件对应一个值。

如果某个安全属性值设置为 ****（掩蔽的安全值），uCommand 将无法导入并忽略该动作，同时提示用户。 若要导入安全属性值，用户需要手动将其置于 JSON 文件中。

警告：通过手动置入 JSON 文件的任何安全属性值（如密码），都将以纯文本的形式显示。导入完成后，UrbanCode Deploy 将会对其进行加密，以便在 Web UI 中隐藏。我们建议在导入后清除 JSON 文件，以免出现数据泄漏。

推广动作

推广动作需要一个有效的 promote.config.php 文件：

php ucommand.php   --action=config   --origin={{ORIGIN_ALIAS}}   --destination={{DESTINATION_ALIAS}}

使用设置 uCommand一节中定义的别名。

两个别名都需要有效的配置，且应在 /config/servers 文件夹中提供。

当应用名称作为参数传送时，uCommand 会验证是否可以从源服务器提供该应用，并导出应用，然后将其导入到目标服务器。

如果该应用在目标 UrbanCode Deploy 服务器中缺失，将会创建该应用；否则，将会升级现有应用。

promoteApplication 动作用于导入或升级与应用相关的所有组件、组件模板、流程、资源模板及蓝图。环境将不会被导入。

promoteConfig 动作用于从源服务器下载整个 UrbanCode Deploy 的配置（如同 backup 动作一样）。然后，该配置会导入到目标服务器。 其中包括以下项目的推广：

• 应用
• 组件
• 资源模板
• 流程
• 环境（除非 clean 参数已设置）

缺失的元素也将会被创建。现有元素将会被升级。

当某个资源模板名称或 ID 作为参数传送时，uCommand 会从源服务器导出资源模板，并将其导入到目标服务器。

如果该资源模板在目标服务器中不存在，将会创建该资源模板；否则，会对其进行升级，以与源服务器保持相同结构。

如果有两个 UrbanCode Deploy 服务器，且两个可提供同一个应用，uCommand 将会：

• 检查针对 promote.config.php 中所设置别名的服务器配置文件中所定义的应用是否在两个服务器中均存在
• 检查目标服务器是否可以提供全部的所需组件
• 检查目标服务器是否无法提供快照
• 从源服务器中导出快照，包括工件
• 在目标服务器中创建快照中所列的组件版本
• 上传与组件版本相关的所有工件
• 在目标服务器中创建快照

如果在目标服务器中已存在所有组件版本，将不会创建快照，除非您设置了参数 force 。

快照和版本操作动作

createSnapshot 动作用于基于作为参数传送的 JSON 文件中定义的描述创建快照。有关所需 JSON 文件的示例，请参见附录。

如果 JSON 文件中所列的组件版本在 UrbanCode Deploy 服务器中缺失，快照创建将会失败。

createVersion 动作用于在给定组件名称和版本名称的情况下创建组件版本。如果版本已经存在，该动作会失败。

注：本 API 不会向版本添加文件（工件）。

合并动作 createVersion 与动作 addVersionFiles 。当某个组件名称、版本和基本目录作为参数传送时，将会创建新的组件版本，而所含的工件将附加到基本目录中。使用 include 和 exclude 选项，可以筛选待上传到该版本的文件。

合并动作 createSnapshot 和 createVersion 。在作为一个参数传送时，快照 JSON文件（见附录中的定义）会创建缺失的组件版本，上传工件并创建快照。

注：如果所有的组件版本或快照已存在，创建将会失败。

setSnapshotStatus 动作用于将快照设置为 PASSED 或 FAILED 状态。这表示快照会根据已作为参数传送的状态进行重命名，例如：

php ucommand.php   --action=setSnapshotStatus   --snapshot="TestSnapshot"   --status="PASSED"

重命名为 TestSnapshot_PASSED 的快照中的结果。

如果快照已经设置， setSnapshotStatus 动作将会接受该快照名称，带或不带状态均可，例如：

php ucommand.php   --action=setSnapshotStatus   --snapshot="TestSnapshot_FAILED"   --status="PASSED"

以及：

php ucommand.php   --action=setSnapshotStatus   --snapshot="TestSnapshot"   --status="PASSED"

均是快照 TestSnapshot_PASSED 成功的结果。

其他动作

本节列出了不属于上文所讨论的任一目录的动作。

若要创建团队，依次单击 UrbanCode Deploy 设置页面上的 Security > Teams 。

使用 addTeamToComponent 可以关联团队到组件。如果未指定名称或 ID，将会添加所有的可用组件。

使用 addTeamToResource 可以关联团队到特定资源。如果某个资源名称/ID 未设置，团队将会关联到 UrbanCode Deploy 中的所有可用资源。

addTeamToAll 适用于以下元素：

• 代理
• 代理池
• 应用
• 云连接
• 组件
• 组件模板
• 环境
• 流程
• 资源
• 资源模板

借助 config 文件，可以设置默认动作（别名）以及推广动作（目标名称和源名称）在 uCommand 中的每个别名。您也可以同时设置一个或多个别名。但需要设置有效的别名。

回页首

结论

在本文中，您已经学习了如何检索、配置以及作为一个命令行工具使用 uCommand 在 UrbanCode Deploy 中执行动作。借助所提供的的详细 API，您也了解了如何使用 UrbanCode Deploy 服务器执行基本任务并应对复杂的任务集。通过这些知识，您既可以从命令行终端操作，也可以从 Web UI 操作。 uCommand 能够使您通过一个命令灵活执行复杂任务。 借助 uCommand，您可以轻松地在服务器之间拷贝数据，并快速与其他人员分享现有应用。

回页首

附录

查找示例、模板和升级值。

ucd.config.php 示例

点击查看代码清单

<?php // Urban Code Deploy settings $config['alias'] = 'template';  // Path where Urban Code Deploy client is saved $config['udcpath'] = '';  /* * Path where to save the results* If NOT Set, will be defaulted to:%path_to_current_working_directory%/backups/ $config['output'] = '';  // Path for JAVA HOME $config['java_home'] = '/usr/lib/j2sdk1.6-ibm/';  // Silent mode for outputs $config['silent'] = false;  // Run a scan of exported files and verify that are valid JSON $config['json_check'] = false;  // CURL settings for secure connection $config['insecure'] = true; $config['certificate'] = '';  /* * Implement Component::Process Steps - Impersonation * Impersonation actions configuration is set up in:/udclient/config/ucd.impersonation.config.php */ $config['apply_impersonation'] = false; ?>

template.server.php config 文件示例

<?php $config = array (     'alias' => 'template',     'weburl' => 'https://myucdserver.example.com:8443',     'username' => 'username@email.com',     'authtoken' => 'abcd1234-abcd-1234-abcd-abcd12345678',     'application' => 'MyApplication',     'environment' => 'MyEnvironment'  );

promote.config.php 示例

<?php $config = array(); $config['origin_alias'] = 'ALIAS_NAME'; $config['destination_alias'] = 'ALIAS_NAME';

环境属性文件示例

[   {     "propertyName":"Property_Name",     "value":"Property_Value",     "secure":false,     "components":[       "Component_Name"  ]   },   {     "propertyName":"Property_Name_Multiple_Components",     "value":"Property_Value",     "secure":false,     "components":[       "Component_Name_1",       "Component_Name_2"     ]   },   {     "propertyName":"Property_Name_Secure",     "value":"****",     "secure":true,     "components":[       "Component_Name_1",       "Component_Name_2"     ]   }]

快照创建示例

作为阵列的 $snapshot 所需内容：

$snapshot [ 'snapshot' ] [ 'name' ] = SNAPSHOT_NAME $snapshot [ 'application' ] = APPLICATION_NAME $snapshot [ 'snapshot' ] [ 'description' ] = SNAPSHOT_DESCRITPTION $snapshot [ 'components' ] = array ( COMPONENT => VERSION ) $snapshot [ 'artifacts' ] = array (  COMPONENT => array ( 'base' = BASE_DIRECTORY, 'include' = array ( INCLUDED_FILES_AND_DIRECTORIES ), 'exclude' = array ( EXCLUDED_FILES_AND_DIRECTORIES ) ) )

作为 JSON 文件的 $snapshot 所需内容：

{  "snapshot" :{  "name" :SNAPSHOT_NAME ,  "description" :SNAPSHOT_DESCRIPTION },   "application" :APPLICATION_NAME ,  "components" :{  COMPONENT :VERSION ,  COMPONENT :VERSION , }, "artifacts" :[ { COMPONENT :{ 'base' :BASE_DIRECTORY, 'include' :{ INCLUDED_FILES_AND_DIRECTORIES }, 'exclude' :{ EXCLUDED_FILES_AND_DIRECTORIES } } ]  }

clean.config.php 示例

/* Include in clean */ $config['clean']['include']['rule'] =  array( 'default' => '.DEV', 'application' => '', 'component' => '', 'applicationProcess' => '', 'componentProcess' => '', 'genericProcess' => '', 'postProcessScript' => '' ); $config['clean']['include']['position'] = '';  /* Exclude from clean */ $config['clean']['exclude']['rule'] =  array( 'default' => '.DEV', 'application' => '', 'component' => '', 'applicationProcess' => '', 'componentProcess' => '', 'genericProcess' => '', 'postProcessScript' => '' ); $config['clean']['exclude']['position'] = '';

环境创建模板

{     "application":"Your_Application_Name",     "baseResource":"Path_For_Base_Resource",     "blueprint":"Your_Application_Blueprint_Name",     "name":"Your_Environment_Name"  }

升级值