华为云用户手册

方案架构 图1 丰图城市数字孪生平台方案架构 数据层提供CIM、BIM、矢量等时空基础数据、政务数据（地址相关）存储，其中政务数据地址标准化融合落图后以专题形式存储； 数据处理层提供二三维数据接入、格式与坐标转换、轻量化。政务数据接入、更新，地址标准化及与二三维地图语义化融合； 服务层以API/SDK形式对外提供二、三维、BIM地图底图服务、政务专题查询、空间查询、三维可视化及时空大数据分析，支持大中小屏可视化。全息时空门户提供运营、运维管理及CIM平台功能演示； 丰图城市数字孪生平台通常部署在客户侧政务云平台，部署环境设计如下图所示： 图2 丰图城市数字孪生平台部署架构 架构描述： 整个CIM平台依赖华为云H CS 底座，包括ECS、Redis、MySQL、OBS等，由运维人员分配资源； 数据层包括数据存储服务和大数据处理平台，数据通过ETL工具、数据调度工具等大数据处理平台组件处理后进行存储； 平台对外以SDK/API的方式提供引擎服务能力和数据服务能力； Portal和运管平台提供资源管控、系统运维能力； 平台内服务之间调用通过负载均衡服务调用保障系统高可用；

方案优势 高逼真、大规模、高性能实景三维重建 实景三维建模能力是在华为黎曼实验室的3D实景地图技术积累及Function Graph自适应调度能力基础上构建的：厘米级精细化还原建筑细节，高精度还原室内实景；同时大幅度提升经典建模流程效率，最高可支持60w+影像一次性整体处理。 提供PB级数据存储、极速地址数据查询服务 丰图利用自身实践的时空大数据工程经验，基于华为云提供城市数字孪生平台底座能力，构建时空大数据平台产品，形成具有成熟的工业级时空数据生产、治理、分析服务体系。 独特数据资源及时空融合技术使数据更鲜活 为保障时空数据的鲜活性与准确性，丰图借助顺丰强大的线下资源和自动化的数据提取和更新技术，建立政府和企业协同的双循环的数据更新体系，降低数据更新成本提高更新效率。

算子服务 服务分布： 表1 服务分布 服务名 服务器 安装目录 端口 data-wrangling 10.190.x.x 10.190.x.x /app/dt/data-wrangling 8085 安装算子服务 修改配置文件application-dev.yml 修改stdms.callback.url中的ip和端口，配置为CIM数据汇聚管理平台的ip和端口 当使用minio存储日志时，配置log.server.enable为true，并配置日志服务（data-log-manage）的ip和端口； 当使用本地文件存储日志时，配置log.server.enable为false 当采用local模式运行时，data-wrangling-worker.cluster-mode配置为local；当采用集群模式运行时，data-wrangling-worker.cluster-mode配置为yarn，此时，需要将hadoop集群的core-site.xml、yarn-site.xml、hdfs-site.xml、mapred-site.xml等四个文件拷入config文件夹，同时，如果data-wrangling服务部署机器不在hadoop集群内的话，需要在部署机器上的/etc/hosts中配置集群服务器的ip和hostname ```yml# 服务端口server: port: 8085# spark任务提交模式data-wrangling-worker: cluster-mode: local# 任务执行完成，回调CIM数据汇聚管理平台接口stdms: callback: url: http://192.168.32.89:9090/stdms/feed-back/ch-task-status?objectId=%s&status=%d# 是否将日志发送到日志服务并存储到miniolog: service: enable: true url: http://127.0.0.1:8089/save``` 启动、停止 启动： 进入bin路径，执行 ```shell./start.sh``` 停止： Kill -9 进程号 服务验证 服务启动验证与版本信息查询 将以下地址中的ip和端口修改为实际部署ip和端口，请求接口，查看版本信息 请求地址：http://localhost:8085/about 请求方式：GET 服务功能验证 任务提交验证：将以下地址中的ip和端口修改为实际部署ip和端口，配置正确的数据库连接信息，在数据库中创建user表，并填入任意测试数据，如下述案例表示查询本地mysql的demo库中的user表，并将user表中的数据同步到user1表。 请求地址：http://localhost:8085/data-wrangling 请求方式：POST 请求参数体： ```json{ "taskId": "7fdbcc680a4f4e929bc72d89856b00d3", "taskName": "lz-test", "nodes": [ …… ], "lines": [ { "from": "1", "to": "2" } ]}``` 返回结果示例： ```json{ "success": true, "message": "提交spark任务成功", "content": { "taskId": "7fdbcc680a4f4e929bc72d89856b00d3", "taskName": "lz-test", "createTime": "2022-08-16 17:12:14", "level": "INFO", "applicationId": "local-1660641128001" }}``` 父主题： CIM数据汇聚管理软件部署

服务部署 安装包准备 使用 Auto_Deploy 中的apache-tomcat-9.0.58.tar.gz包。 将uniform-auth.war和cas.war 放到 webapps 目录下。 将 application-config.yml 和 cas.properties 放到 config 目录下，config 和 webapps 同级目录，也和 conf 同级目录。 将 uniform_auth.sql 导入到 mysql。 配置数据库、服务 IP 和端口 cas 表名和字段需修改成 uniform_auth.sql 中 sys_user 表名和字段。 #修改数据库： url: jdbc:mysql://192.168.32.3:3306/uniform_auth?autoReconnect=true&useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true username: root password: Fengtu12#$# cas相关cas: # 是否启用cas，如果不启用则不做权限验证拦截，创建默认session，使用CasGuestUser作为默认session用户（应对开放型系统的`偷懒`方案，不建议使用） enable: true host: # CAS服务器内网地址，用于服务端对服务端调用，例如验证ticket等（在办公环境可能和 client2-server相同） server-2-server: http://192.168.32.61:8001/cas # CAS对用户访问地址，用于配置用户在客户端跳转的登录登出目的地址 client-2-server: https://10.190.x.x/caslogged.url 支持自定义跳转页面。访问 /cas/login，会跳转到 logged.url 页面。访问 /cas/login?service=xx，会跳转到 xx 页面。 页面访问 https://10.190.x.x/uniform-auth 预置账户： admin/sf@xxx（管理员账号） yanshi/xxxx（超管账号） 图1 访问a 父主题： 平台运行维护软件部署

安装Manager 数据管理模块的安装需要先解压安装包，然后运行Web Installer使用图形化界面安装。 准备安装包 # 解压出安装目录tar xvzf TDH-Platform-Transwarp-version.tar.gz# 进入解压后的transwarp目录cd transwarp#执行install二进制文件./install 通过浏览器访问管理节点，进入Web Installer界面 图1 进入Web Installer界面 系统首先需要您阅读Java许可。阅读完毕，单击“同意”进入下一步 图2 下一步 系统将自动检查管理节点的环境配置，主要包括时间、日期、时区及主机名信息并显示在屏幕上，请确认 图3 确认 安装结束后，您会被要求设置Transwarp Manager端口，推荐默认端口“8180” 图4 推荐默认端口 等待安装 图5 等待安装 安装Manager需要一个包含对应版本操作系统的资源库（repo） 图6 repo 如果您选择“使用远程RPM库”，您需要输入已经创建好的资源库的URL： 如果您选择“创建新的RPM库(DVD)”，您需要准备好对应版本操作系统的光盘。 如果您选择“创建新的RPM库(ISO)”，您需要准备好对应版本操作系统的ISO文件。建议您采用ISO镜像方法生成资源库库包。 如果您选择“后台手工配置”，您在该步骤无需进行其他操作。 选择后，系统会清理资源库缓存。 资源库缓存清理完毕后，系统会自动开始安装和配置Transwarp Manager。安装程序会自动安装必需的软件包，全程静默安装，安装配置完成后自动跳转到下一步。 Manager安装完成，可以访问提示的安装地址并使用默认的用户名/密码（admin/******）去登录管理界面继续接下来的配置 图7 安装完成 父主题： 数据底座模块部署

旧输出参数cli-output-rows，cli-output-cols，cli-output-num使用时的注意事项有哪些？ 当命令中使用了“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”时，将会以table格式输出。使用table输出有利于用户对返回值中的关键信息进行提取。使用时各参数的功能如下： --cli-output-cols：table输出时，指定需要打印的字段； --cli-output-rows：table输出时，指定需要打印的层级。例如希望表格化一个json结构体，则参数值填写该json结构体的名称。 --cli-output-num：table输出时，是否打印表格的行号。取值为true或false，默认为true。 了解以上选项的使用方式，可参考旧输出参数cli-output-rows，cli-output-cols，cli-output-num如何使用。 使用如上参数进行table输出时需要注意如下事项： “--cli-output-cols”与“--cli-output-rows”可单独使用，也可组合使用： 单独使用“--cli-output-rows”： 在命令中单独使用“--cli-output-rows”传入调用结果中某json结构体的名称时，各层级之间以“.”分隔，目标json结构体的内容必须为数组类型，KooCLI会将该json结构体的内容以表格化输出。例如执行命令“hcloud configure list --cli-output-rows=profiles”，会以表格输出所有配置项信息。若“--cli-output-rows”中指定的json结构体的内容不是数组类型，会提示如下错误： [CLI_ERROR]table输出错误:缺少cli-output-cols参数 单独使用“--cli-output-cols”： 参数“--cli-output-cols”中可传入调用结果的json结构体根元素的字段，多个字段之间以“,”分隔。例如：执行命令“hcloud configure show --cli-profile=${profileName} --cli-output-cols=accessKeyId”，会以表格化方式输出指定配置项中的accessKeyId信息。单独使用“--cli-output-cols”时只能指定json结构体根元素的字段，否则会提示如下错误： [USE_ERROR]参数cli-output-cols中字段*对应的值为null 组合使用“--cli-output-cols”与“--cli-output-rows”： 当命令中同时使用“--cli-output-rows”和“--cli-output-cols”时，选项“--cli-output-rows”用来指定需要打印的层级，选项“--cli-output-cols”用来指定该层级中需要打印的字段。例如：执行命令“hcloud configure list --cli-output-rows=profiles --cli-output-cols=accessKeyId”，将以table方式输出所有配置项中的accessKeyId信息； “--cli-output-rows”的参数值中可使用“[n]”或“[m:n]”指定其中要打印的数组元素的索引位。指定“[n]”时会打印索引为n的值；指定“[m:n]”时会打印原数据m ~（n-1）索引位置的值。例如执行命令“hcloud configure list --cli-output-rows=profiles[0:2] --cli-output-cols=accessKeyId”，则以table方式输出配置项数组中索引位为0和1的配置项中的accessKeyId信息，组合使用“--cli-output-cols”与“--cli-output-rows”时还需注意如下事项： 若“--cli-output-rows”中传入的数组的索引值是“[m:n]”，当n超出其数组长度时，会根据实际数据打印至其最大索引位。 若“--cli-output-rows”中传入的数组的索引值是“[n]”，当n超出其数组长度时，会提示数组索引越界，如下： [USE_ERROR]参数cli-output-rows中的字段*输入错误:数组索引越界,数组长度为*,输入的索引为* 组合使用“--cli-output-cols”与“--cli-output-rows”时，“--cli-output-rows”中的参数不要求一定是数组类型的参数，能指定到具体的层级即可。 单独使用“--cli-output-num”时，无table输出效果。 在同一命令中，“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”不可与“--cli-json-filter”同时使用，会因无法判断输出格式而导致错误。 父主题： 旧输出参数cli-output-rows，cli-output-cols，cli-output-num如何使用，注意事项有哪些？

新输出参数cli-output，cli-query，cli-output-num在使用时的注意事项有哪些？ 新输出参数的使用方法请参考：指定结果的输出格式。 命令中使用“--cli-query”用于传入JMESPath表达式，对结果执行JMESPath查询，方便提炼原返回结果中的关键信息；“--cli-output”用于指定响应数据的输出格式；“--cli-output-num”用于指定当使用table格式输出时，是否打印行号。 使用如上各参数时，需要注意的是： 支持在命令中单独使用“--cli-output”指定输出格式；单独使用“--cli-query”时默认输出格式为json。 使用“--cli-query”时，其值建议使用双引号引起。避免系统处理命令时的解析错误。 若要使用“--cli-output-num”指定是否打印行号，此时必须指定“--cli-output”的取值为table。 在同一命令中，已使用了“--cli-output”的情况下，若同时指定旧系统参数如“--cli-output-rows”，“--cli-json-filter”等，优先以“--cli-output”的取值作为目标输出格式。 父主题： 输出格式相关

认证方式优先级 KooCLI在命令解析过程中，依照如下优先级使用其认证方式，完成调用API时的认证流程： 无配置方式AKSK认证： 无配置方式AKSK：命令中直接输入访问密钥（永久AK/SK，即cli-access-key和cli-secret-key）或临时安全凭证（临时AK/SK和SecurityToken，即cli-access-key，cli-secret-key和cli-security-token）用于认证； 已添加配置项的情况下，命令中直接指定配置项或使用默认配置项； 委托给云服务（目前仅支持通过 IAM 委托给弹性云服务器，以委托认证的方式在弹性云服务器中使用KooCLI的场景）。 若在解析某认证方式的过程中出现异常，不会尝试使用低于该优先级的方式进行认证。 父主题： 认证相关

KooCLI与输出相关的系统参数有哪些，推荐使用哪些？ KooCLI与输出相关的参数如下： 表1 KooCLI与输出相关的参数 参数分组 参数 参数用途 新输出参数 cli-output，cli-query，cli-output-num cli-output 响应数据的输出格式，取值可以为如下其一： json table tsv cli-query 筛选响应数据的JMESPath路径 cli-output-num table输出时，是否打印行号。取值为：true或者false 旧输出参数 cli-output-rows，cli-output-cols，cli-output-num，cli-json-filter cli-output-rows table输出时，指定需要打印的层级 cli-output-cols table输出时，指定需要打印的字段 cli-output-num table输出时，是否打印行号。取值为：true或者false cli-json-filter json输出时，对json结果执行JMESPath查询 与旧输出参数相比，新输出参数不仅新增了支持除table，json两种输出格式外的tsv输出格式，同时也使输出参数得以统一，方便用户使用。 KooCLI之后关于输出格式相关的功能，将在新输出参数的基础上开发。对旧输出参数将仅维持其已有功能，不再持续升级。故用户在构造命令时，推荐使用新输出参数。 父主题： 输出格式相关

使用cli-jsonInput的场景有哪些？ 云服务的API参数名称中带有“.”，KooCLI可能无法正确解析该参数，此时需通过cli-jsonInput传入该API的参数； 云服务的API在不同位置中有同名的参数时，KooCLI无法正确解析该API的参数，此时需通过cli-jsonInput传入该API的参数； 用户输入的云服务API参数值中包含空格或特殊符号，通过终端调用KooCLI命令时，其参数值可能发生传递错误，此时需通过cli-jsonInput传入该API的参数； 用户输入的云服务API参数值过长，受终端输入字符长度的限制，可能导致命令输入不完整，此时需通过cli-jsonInput传入该API的参数。 父主题： 参数相关

扩展问题及其解决方案 扩展问题 当您使用默认版本信息的方式调用多版本云服务的API时，若您本地缓存的元数据文件被修改，可能会导致KooCLI在执行过程中无法根据缓存文件正确解析到该API的版本信息。在此情形下，会提示如下错误： [USE_ERROR]服务为多版本,请指定API版本号 解决方案 如遇如上情形，您可通过执行“hcloud meta clear”命令清理当前的元数据缓存文件后，重新调用。

概述 KooCLI将调用命令时出现的错误分为五种类型，在错误提示信息的起始位置声明其具体类型：[NETWORK_ERROR]，[CLI_ERROR]，[USE_ERROR]，[OPENAPI_ERROR]和[APIE_ERROR]。各类错误的定位方法如下： [NETWORK_ERROR]：一般是HTTP请求异常，请检查网络连接； [CLI_ERROR]：一般是因KooCLI处理命令过程中本身的异常导致的错误，请联系KooCLI的oncall协助处理； [USE_ERROR]：一般是因命令中参数不正确造成的错误，请根据错误提示做相应修改； [OPENAPI_ERROR]：一般是调用云服务API时发生的错误，请联系相关云服务oncall协助处理； [APIE_ERROR]：一般是调用 API Explorer 获取元数据时发生的错误，请联系API Explorer云服务oncall协助处理。 您也可以根据下表常见问题概览查找所需内容。 表1 常见问题概览 常见问题分类 相关链接 认证相关 如何获取永久AK/SK？ 如何获取账号ID、项目ID？ 如何获取区域？ 如何获取临时AK/SK和securitytoken？ 各认证方式的优先级是什么？ 配置项相关 命令中未指定配置项时默认使用哪个配置项？ 元数据缓存相关 元数据缓存文件存于何处？如何清理？ 日志相关 日志文件存于何处？ 网络连接相关 如何解决网络连接超时问题？ 云服务相关 提示不支持的服务时如何处理？ 云服务API相关 提示不支持的operation时如何处理？ 如何指定云服务的API和版本号？ 云服务API的响应体为空时，如何判断命令是否执行成功？ 区域相关 提示缺少cli-region参数时如何处理？ 提示不支持的cli-region时如何处理？ 参数相关 KooCLI系统参数包括哪些？ 提示不正确的参数时如何处理？ 为什么会有新旧系统参数，如cli-region与region，在使用时的区别是什么推荐使用哪个？ 提示重复的参数时如何处理？ 如何使用cli-jsonInput？注意事项有哪些？ 使用cli-jsonInput的场景有哪些？ 提示不支持的参数位置/类型时如何处理？ 云服务API的body位置参数值如何置空？ 交互式/自动补全相关 使用交互式/自动补全需要注意什么？ 输出格式相关 KooCLI支持的输出格式有哪些？ JMESPath表达式的用法有哪些？ JMESPath支持的内置函数有哪些？ KooCLI与输出相关的系统参数有哪些，推荐使用哪些？ 新输出参数cli-output，cli-query，cli-output-num在使用时的注意事项有哪些？ 旧输出参数cli-output-rows，cli-output-cols，cli-output-num如何使用？ 旧输出参数cli-output-rows，cli-output-cols，cli-output-num使用时的注意事项有哪些？ 旧输出参数cli-json-filter如何使用？ 旧输出参数cli-json-filter使用时的注意事项有哪些？ 其他 无配置方式使用KooCLI需要注意什么？ 命令中服务名、operation、参数的value值是否需要使用双引号引起？ 在线/离线模式分别适用什么场景？ 如何卸载KooCLI？

解决步骤 如遇如上情形，若您未在命令中指定cli-region值，您可在当前命令中添加“--cli-region=${regionValue}”，重新调用； 如您有常用的区域，可使用“hcloud configure set --cli-profile=${profileName} --cli-region=${regionValue}”命令将其配置到目标配置项中。后续使用该配置项调用API时，命令中可以不必输入cli-region；但若目标API不支持该cli-region，则您仍需在命令中通过“--cli-region=${regionValue}”传入支持的cli-region。

问题背景 KooCLI在命令执行过程中会对参数的合法性进行检查，若命令中存在重复参数，视具体场景不同，会提示不同错误，例如： [USE_ERROR]重复的参数:* [USE_ERROR]重复的参数*,如非误输,请以cli-*为key输入其中的KooCLI系统参数 [USE_ERROR]重复的*,如非误输,请将其中的API参数通过'--cli-jsonInput=xx'传入,详情参考... 在KooCLI系统参数列表中，部分参数同时存在两种形式，如“--cli-region”和“--region”。之所以同一系统参数同时支持两种参数名，是因为在KooCLI上开放的云服务中，存在部分API的某参数与系统参数重名的情况。

系统参数 KooCLI系统参数是指其内置参数，各系统参数的描述信息及其使用方式如下表所示： 表1 KooCLI新系统参数 参数 参数描述 使用方式 help 打印帮助信息 命令中直接使用 debug 打印调试信息 命令中直接使用 dryrun 执行校验后打印请求报文,跳过实际运行 命令中直接使用 interactive 进入交互式模式 命令中直接使用 cli-region 区域 配置于配置项后使用 / 命令中直接使用 cli-access-key AK/SK模式时需要的参数Access Key ID 配置于配置项后使用 / 命令中直接使用 cli-secret-key AK/SK模式时需要的参数Secret Access Key 配置于配置项后使用 / 命令中直接使用 cli-domain-id 账号ID 配置于配置项后使用 / 命令中直接使用 cli-project-id 项目ID 配置于配置项后使用 / 命令中直接使用 cli-profile 指定配置项,缺省时使用默认配置项 配置于配置项后使用 / 命令中直接使用 cli-mode 认证模式[AKSK|ecsAgency] 配置于配置项后使用 / 命令中直接使用 cli-jsonInput 通过JSON文件方式传入API参数 命令中直接使用 cli-output 响应数据的输出格式[json|table|tsv] 命令中直接使用 cli-query 筛选响应数据的JMESPath路径 命令中直接使用 cli-output-num table输出时，是否打印表格的行号。取值为true或false，默认为true 命令中直接使用 cli-endpoint 自定义请求 域名 命令中直接使用 cli-connect-timeout 请求连接超时时间(秒)，默认值5秒，参数最小取值为1秒 配置于配置项后使用 / 命令中直接使用 cli-read-timeout I/O超时时间(秒)，默认值10秒，参数最小取值为1秒 配置于配置项后使用 / 命令中直接使用 cli-retry-count 请求连接重试次数，默认取值为0次，参数取值范围为0~5次 配置于配置项后使用 / 命令中直接使用 cli-security-token 用户获取的临时token，必须和临时AK/SK同时使用 配置于配置项后使用 / 命令中直接使用 cli-lang 语言，取值为cn或en 配置于配置项后使用 cli-offline 是否使用离线模式。取值为true或false，默认为false 配置于配置项后使用 cli-skip-secure-verify 是否跳过https请求证书验证(不建议)。取值为true或false，默认为false 配置于配置项后使用 / 命令中直接使用 cli-agree-privacy-statement 是否同意隐私。取值为true或false，默认为false 配置于配置项后使用 cli-warning 是否提示命令执行过程中的Warning信息。取值为true或false，默认为true 配置于配置项后使用 对上表中所列的各参数使用方式解释如下： 仅支持配置于配置项后使用： 指该参数只可以通过“hcloud configure set --key1=value1 --key2=value2 ...”命令配置到配置项后再使用。使用时在命令中通过“--cli-profile=${profileName}”指定配置项名称，KooCLI即会在运行过程中解析并使用该配置项中配置的各项参数值。 若在命令中直接使用该类参数，会提示如下错误： [USE_ERROR]不正确的参数:* 仅支持命令中直接使用： 指该参数只可以通过“--key1=value1 --key2=value2 ...”直接在命令中使用。 若将该类参数配置到配置项中，会提示如下错误： [USE_ERROR]不正确的参数:* 配置于配置项后使用 / 命令中直接使用： 指该类参数既可以通过“hcloud configure set --key1=value1 --key2=value2 ...”命令配置到配置项后再使用，也可以通过“--key1=value1 --key2=value2 ...”直接在命令中使用。对于同一参数，KooCLI会在运行过程中优先使用命令中指定的该参数值。未在命令中指定的参数，则使用当前配置项中其值。 与新系统参数相关的KooCLI旧系统参数参见下表。

命令中服务名、operation、参数的value值是否需要使用双引号引起？ 需要视参数value的具体内容而定。 一般情况下，命令中的服务名、operation、参数的value值可不必使用双引号引起。但若您命令中的服务名、operation、参数的value值中有特殊符号、空格、或需要转义的符号，请您在命令中传入该值时，将其使用双引号引起。 您可通过直接在API Explorer上获取CLI示例，避免在命令中手动输入参数。 父主题： 其他

KooCLI支持的输出格式有哪些？ KooCLI支持三种输出格式：json，table，tsv。默认以json格式输出。您可以使用“--cli-output”参数指定如前所述的任意一种输出格式，您也可以配合使用“--cli-query”选项传入JMESPath表达式，对json结果执行JMESPath查询，以过滤出您需要的信息。输出效果可参考此示例：指定结果的输出格式。构造JMESPath表达式，请参考如何定义JMESPath表达式。 父主题： 输出格式相关

旧输出参数cli-json-filter使用时的注意事项有哪些？ KooCLI支持使用“--cli-json-filter”传入JMESPath表达式，对json结果执行JMESPath查询，提炼其中的关键信息。使用“--cli-json-filter”时需注意： 当命令中使用了“--cli-json-filter”时，将以json格式输出调用结果。 在同一命令中，“--cli-json-filter”不可以与“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”同时使用，会因无法判断输出格式而导致错误。 使用cli-json-filter定义JMESPath表达式时可参考： JMESPath表达式的用法 JMESPath支持的内置函数 父主题： 旧输出参数cli-json-filter如何使用，注意事项有哪些？

解决方案 如果您在命令中通过“--cli-profile”选项指定了配置项，您可先执行“hcloud configure show --cli-profile=${profileName}”命令查看该配置项的具体内容，确认您指定的配置项是否合适； 如您未在命令中指定配置项，KooCLI会使用默认配置项来调用目标API。您可使用命令“hcloud configure show”查询默认配置项的详情信息； 如您需要使用其他配置项，您可通过“hcloud configure list”命令查看您已配置的所有配置项，然后使用“--cli-profile=${profileName}”在原调用API的命令中指定目标配置项的名称，重新调用。

使用交互式/自动补全需要注意什么？ 在bash环境下，使用“hcloud auto-complete on”可开启自动补全，使用自动补全时需注意： 自动补全提示参数时，若提示的参数名中有“[N]”，其含义为索引位，请使用数字代替该字符；若提示的参数名中有“{*}”，其含义为自定义参数名称，请使用任意不含“.”的字符串代替该字符； 若同一机器同一用户的多个目录下有KooCLI，且其中某一目录下的工具开启了自动补全，则该用户其他目录下的KooCLI也可完成自动补全功能。 使用交互模式时需注意： 交互式提示参数时，若提示的参数名中有“[N]”，其含义为索引位，请使用数字代替该字符；若提示的参数名中有“{*}”，其含义为自定义参数名称，请使用任意不带“.”的字符串代替该字符。 父主题： 交互式/自动补全相关

问题背景 通过KooCLI管理和使用您的各类云服务资源，在调用云服务的API时，KooCLI优先使用命令中“--cli-profile”选项指定的配置项。 如您未在命令中指定配置项，会使用默认配置项来调用目标API。 若该配置项的内容与目标API不匹配，或缺少访问目标API时需要的某参数，会提示相关错误，例如： [USE_ERROR]请输入cli-region [USE_ERROR]cli-region的值不支持,当前支持的区域值如下:* [USE_ERROR]缺少必填参数: project_id [USE_ERROR]使用AK/SK模式访问全局服务,缺少必填参数cli-domain-id.请添加该参数,或使用`hcloud configure set`配置cli-domain-id

旧输出参数cli-output-rows，cli-output-cols，cli-output-num如何使用？ 通过KooCLI调用云服务API，默认会返回json格式的调用结果。KooCLI支持使用“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”参数，以table格式输出，方便提炼调用结果中的关键信息，如下： 以默认的json格式输出原调用结果： hcloud ECS NovaListServers --cli-region="cn-north-4" --project_id="0dd8cb****************19b5a84546"{ "servers": [ { "name": "ecs-a6b4", "links": [ { "rel": "self", "href": "https://ecs.cn-north-4.myhuaweicloud.com/v2.1/0dd8cb****************19b5a84546/servers/4f06****-****-****-****-****04dd856a" }, { "rel": "bookmark", "href": "https://ecs.cn-north-4.myhuaweicloud.com/0dd8cb****************19b5a84546/servers/4f06****-****-****-****-****04dd856a" } ], "id": "4f06****-****-****-****-****04dd856a" }, { "name": "hdn-docker", "links": [ { "rel": "self", "href": "https://ecs.cn-north-4.myhuaweicloud.com/v2.1/0dd8cb****************19b5a84546/servers/6731****-****-****-****-****0bc463f0" }, { "rel": "bookmark", "href": "https://ecs.cn-north-4.myhuaweicloud.com/0dd8cb****************19b5a84546/servers/6731****-****-****-****-****0bc463f0" } ], "id": "6731****-****-****-****-****0bc463f0" }, { "name": "ecs-8f88", "links": [ { "rel": "self", "href": "https://ecs.cn-north-4.myhuaweicloud.com/v2.1/0dd8cb****************19b5a84546/servers/06a2****-****-****-****-****c79a1a26" }, { "rel": "bookmark", "href": "https://ecs.cn-north-4.myhuaweicloud.com/0dd8cb****************19b5a84546/servers/06a2****-****-****-****-****c79a1a26" } ], "id": "06a2****-****-****-****-****c79a1a26" } ]} 以table输出调用结果时，“--cli-output-rows”指定json结构体的层级，即表格的数据来源；“--cli-output-cols”指定表格的列名，需要与json结构体中的字段相对应；“--cli-output-num”指定是否打印表格行号，默认值为true，如下图所示: hcloud ECS NovaListServers --cli-region="cn-north-4" --project_id="0dd8cb******************b5a84546" --cli-output-rows="servers" --cli-output-cols="name,id" 使用“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”参数也可以用于系统命令中，如下所示： hcloud configure list --cli-output-rows="profiles[]" hcloud configure list --cli-output-rows="profiles[0]" --cli-output-cols="name,accessKeyId,secretAccessKey,projectId,region" 使用“--cli-output-rows”，“--cli-output-cols”，“--cli-output-num”进行table输出时的其他注意事项如下所示。 父主题： 旧输出参数cli-output-rows，cli-output-cols，cli-output-num如何使用，注意事项有哪些？

问题背景 KooCLI调用云服务API的过程中，会对您输入参数的合法性进行校验，此校验过程可能需要远程获取该云服务和API的详情信息；在参数校验完成后，亦需要远程调用您的目标API。如在调用过程中因网络连接问题导致请求失败，会提示相关错误，例如： [NETWORK_ERROR]连接超时,请检查网络连通性 [USE_ERROR]调用API超时,请先检查配置项或命令中的readTimeout的值 [NETWORK_ERROR]连接超时*次(重试*次)请检查网络连通性

解决步骤 如遇如上情形，请您先检查您的网络连通是否正常； 如您网络连接确认无异常，错误信息中提示您“连接超时”，可能是配置项或命令中的cli-connect-timeout的值过小，您可以通过如下方式修改该值： 若您已在命令中使用“--cli-connect-timeout”选项，请适当增大其值，重新调用； 如您未在命令中使用“--cli-connect-timeout”选项，会在命令执行过程中使用当前配置项中该参数的值。您可以通过在当前命令中添加“--cli-connect-timeout=${connectTimeout}”，临时覆盖配置项中该参数值，重新调用。若您需要修改配置项中该参数的值，请您执行“hcloud configure set --cli-profile=${profileName} --cli-connect-timeout=${connectTimeout}”命令； 如您网络连接确认无异常，错误信息中提示您检查“readTimeout”，可能是配置项或命令中的“cli-read-timeout”的值过小，您可通过如下方式修改该值： 若您已在命令中使用“--cli-read-timeout”选项，请适当增大其值，重新调用； 如您未在命令中使用“--cli-read-timeout”选项，会在命令执行过程中使用当前配置项中该参数的值。您可以在当前命令中添加“--cli-read-timeout=${readTimeout}”，临时覆盖配置项中该参数值，重新调用。若您需要修改配置项中该参数的值，请您执行“hcloud configure set --cli-profile=${profileName} --cli-read-timeout=${readTimeout}”命令。

云服务API的body位置参数值如何置空？ 对于云服务API的body位置的参数，KooCLI支持在任意层级置空： 若当前层级的值实际类型为map，则置空时参数值应为“{}”。 若当前层级的值实际类型为数组，则置空时参数值应为“[]”。 以云服务“ECS”的operation“BatchStopServers”为例，其body位置存在参数“os-stop.servers.[N].id”和“os-stop.type”，如下： hcloud ECS BatchStopServers --cli-region=cn-north-4 --helpKooCLI(Koo Command Line Interface) Version 3.2.8 Copyright(C) 2020-2023 www.huaweicloud.comService: ECSDescription: 根据给定的云服务器ID列表,批量关闭云服务器,一次最多可以关闭1000台。Method: POSTParams: --cli-region required string 当前可调用的区域.若命令中未输入,将使用当前配置项中的cli-region --os-stop.servers.[N].id required string body 云服务器ID。格式为:--os-stop.servers.1.id=value1 ... --project_id required string path 项目ID。若命令中未输入,将根据认证信息获取指定区域的父级项目ID,或使用当前配置项中的cli-project-id --os-stop.type optional string body 关机类型,默认为SOFT:。[SOFT|HARD] - SOFT:普通关机(默认)。 - HARD:强制关机。 不置空： 给参数“os-stop.servers.[N].id”和“os-stop.type”分别传入参数值，使用“--dryrun”查看请求body体内容，如下： hcloud ECS BatchStopServers --cli-region=cn-north-4 --os-stop.servers.1.id="test" --os-stop.type="SOFT" --dryrun--------------------------------- dry-run模式跳过实际运行,当前请求为: ---------------------------------POST https://ecs.cn-north-4.myhuaweicloud.com/v1/0a152ab****************262d035e8/cloudservers/actionContent-Type: application/json;charset=UTF-8X-Project-Id: 0a152ab****************262d035e8X-Sdk-Date: 20221116T121721ZAuthorization: ****{ "os-stop": { "servers": [ { "id": "test" } ], "type": "SOFT" }} 数组类型参数置空： 若将参数“os-stop.servers.[N].id”的数组（即“[N]”及其之后的内容）置空，因“os-stop.servers”指向的值实际类型为数组，故可传入参数“--os-stop.servers="[]"”，使用“--dryrun”查看请求body体内容，如下： hcloud ECS BatchStopServers --cli-region=cn-north-4 --os-stop.servers="[]" --os-stop.type="SOFT" --dryrun--------------------------------- dry-run模式跳过实际运行,当前请求为: ---------------------------------POST https://ecs.cn-north-4.myhuaweicloud.com/v1/0a152ab****************262d035e8/cloudservers/actionX-Project-Id: 0a152ab****************262d035e8X-Sdk-Date: 20221116T122841ZAuthorization: ****Content-Type: application/json;charset=UTF-8{ "os-stop": { "servers": [], "type": "SOFT" }} map类型参数置空： 若将参数“os-stop.servers.[N].id”和“os-stop.type”的共有的父级“os-stop”置空，因其指向的值实际类型为map，故可传入参数“--os-stop="{}"”，使用“--dryrun”查看请求body体内容，如下： hcloud ECS BatchStopServers --cli-region=cn-north-4 --os-stop="{}" --dryrun--------------------------------- dry-run模式跳过实际运行,当前请求为: ---------------------------------POST https://ecs.cn-north-4.myhuaweicloud.com/v1/0a152ab****************262d035e8/cloudservers/actionContent-Type: application/json;charset=UTF-8X-Project-Id: 0a152ab****************262d035e8X-Sdk-Date: 20221117T013616ZAuthorization: ****{ "os-stop": {}} KooCLI执行过程中会校验参数值是否匹配，若将不适合的空值传给参数，会提醒错误信息。例如给实际为map类型的参数“os-stop”赋值数组类型的空值“[]”，则提示如下错误： [USE_ERROR]map类型参数os-stop的值不正确 父主题： 参数相关

注意事项 “--cli-jsonInput”选项传入的JSON文件中目前只支持写入云服务的API参数，不支持写入系统参数。若目标API中存在与新系统参数或旧系统参数重名的参数，被写入jsonInput文件中的默认将被识别为该API的参数； “--cli-jsonInput”选项传入的JSON文件中，KooCLI会根据JSON最外层的Key获取并解析其的参数值，目前支持的Key包括：path、query、body、formData、header、cookie。JSON最外层的其他Key下的内容将会被忽略。若JSON文件里所有最外层的Key都不属于上述支持的Key之一，会提示如下错误： [USE_ERROR]cli-jsonInput文件内容不符合要求,详情请参考... 使用“--cli-jsonInput”选项传入云服务API参数时，同一位置的API参数必须全部写入JSON文件，或全部通过命令直接传入，否则可能会导致参数解析不完整，会提示如下错误： [USE_ERROR]缺少必填参数:* “--cli-jsonInput”选项只支持传入JSON格式的文件，且文件扩展名必须为“.json”，支持传入的最大文件为5MB；使用“--cli-jsonInput”时，会校验JSON文件的格式及文件中参数的类型。若JSON文件的格式有误，会提示： [USE_ERROR]cli-jsonInput参数的文件解析失败,文件中参数有误 若JSON文件中某参数的类型不被支持，会提示： [USE_ERROR]不支持参数*的值的类型 使用“--cli-jsonInput”选项传入云服务API参数时，参数的取值不支持使用custom参数。

问题背景 命令提示符（cmd.exe）等工具对使用时输入的字符串的最大长度有限制。当需要执行的命令的参数过多或参数值过长时，可能会因为其长度限制导致命令输入不完整。因此KooCLI除了支持参数在命令中直接输入之外，也支持使用“--cli-jsonInput=${jsonFileName}”传入JSON文件，向KooCLI传递云服务API参数。KooCLI会在运行时解析并使用该JSON文件中的参数调用目标API。

问题背景 使用KooCLI调用所有云服务的API时，都需要提供合适的cli-region。如果您遇到如下几种情况： 命令中cli-region值输入有误； 命令指定了cli-region值，但目标API不支持该cli-region； 命令中未指定cli-region值，目标API不支持从当前配置项中获取的cli-region。 会提示如下错误： [USE_ERROR]cli-region的值不支持,当前支持的区域值如下:* [USE_ERROR]当前配置项中cli-region的值不支持,当前支持的区域值如下：*

元数据缓存文件存于何处？如何清理？ 通过KooCLI管理和使用您的各类云服务资源时，会远程获取您命令中目标云服务及其API的详情信息。为减少远程调用次数，提高响应速度，KooCLI引入了缓存机制，在运行过程中将云服务及其API的相关信息保存在本地缓存文件中，该文件称为元数据缓存文件。在元数据缓存文件过期前，会使用该文件中的信息对命令中的参数进行校验和组装。 元数据缓存文件的存放位置 在线模式： Windows系统： C:\Users\{您的Windows系统用户名}\.hcloud\metaRepo\ Linux系统: /home/{当前用户名}/.hcloud/metaRepo/ Mac系统： /Users/{当前用户名}/.hcloud/metaRepo/ 离线模式： Windows系统： C:\Users\{您的Windows系统用户名}\.hcloud\metaOrigin\ Linux系统: /home/{当前用户名}/.hcloud/metaOrigin/ Mac系统： /Users/{当前用户名}/.hcloud/metaOrigin/ 如何清理元数据缓存文件 在线模式： 清理缓存文件时执行命令“hcloud meta clear”即可。元数据缓存文件清理后，调用API时会重新获取并写入新文件。 离线模式： 执行命令“hcloud meta clear”，会清理从已下载的离线元数据包中解析出来的元数据缓存文件，离线元数据包仍然保留。之后调用API时，会重新从该离线元数据包中解析并写入新元数据缓存文件。 父主题： 元数据缓存相关

解决步骤 如遇如上情形时，请您参考该提示信息中支持的cli-region列表，确认cli-region值是否误输； 若您确认cli-region值无误，但命令执行时提示如上错误，可能是因为如下原因： 若您已使用在线模式，则目标API不支持该cli-region，请你按照实际情况修改： 命令中指定了cli-region值，请您参考该提示信息中支持的cli-region列表，修改命令中的cli-region值，重新调用； 命令中未指定cli-region值，KooCLI会在运行过程中解析并使用当前配置项中的cli-region值。您可根据错误提示中支持的cli-region列表，在当前命令中添加“--cli-region=${regionValue}”后重新调用。如您要修改配置项中cli-region的值，请您执行“hcloud configure set --cli-profile=${profileName} --cli-region=${regionValue}”命令； 若您已使用离线模式，可能是您当前使用的离线数据包并非最新版本，导致参数校验不通过。您可先执行“hcloud meta download”命令，更新离线数据包后，再重新执行原命令；若仍提示如上错误，则该cli-region值未在KooCLI离线模式中上线，请等待离线数据包更新，或切换至在线模式尝试； 如KooCLI在执行命令的过程中未提示您如上所述的错误信息，但调用API的返回值显示region错误，可能是因您本地缓存cli-region列表的文件被修改，导致参数校验失其准确性。此时请您执行“hcloud meta clear”命令清理本地缓存文件后，重新调用； 如您的错误提示信息是英文，说明您此前已在配置中将KooCLI语言设置为英文，或KooCLI判断您的系统语言为英文。目前英文环境下KooCLI中云服务的各API支持的cli-region与中文环境存在差异。若您要将语言设置为中文，您可以通过执行“hcloud configure set --cli-lang=cn”命令修改语言配置；