华为云用户手册

常用概念 以电力场景为例，说明如何在IoTDB中创建一个正确的数据模型。 图1 电力场景属性层级组织结构 如图1所示，即“电力集团层-电厂层-设备层-传感器层”。其中ROOT为根节点，传感器层的每一个节点为叶子节点。IoTDB的语法规定，ROOT节点到叶子节点的路径以“.”连接，以此完整路径命名IoTDB中的一个时间序列。例如，图1最左侧路径对应的时间序列名称为“ROOT.ln.wf01.wt01.status”。

数据规划 在kafka中生成模拟数据（需要有Kafka权限用户）。 确保集群安装完成，包括安装HDFS、Yarn、Spark2x和Kafka服务。 将Kafka的Broker配置参数“allow.everyone.if.no.acl.found”的值修改为“true”。 创建Topic。 {zkQuorum}表示ZooKeeper集群信息，格式为IP:port。 $KAFKA_HOME/bin/kafka-topics.sh --create --zookeeper {zkQuorum}/kafka --replication-factor 1 --partitions 1 --topic {Topic} 启动Kafka的Producer，向Kafka发送数据。 {ClassPath}表示工程jar包的存放路径，详细路径由用户指定，可参考在Linux环境中调测Spark应用章节中导出jar包的操作步骤。 java -cp $SPARK_HOME/conf:$SPARK_HOME/jars/*:$SPARK_HOME/jars/streamingClient010/*:{ClassPath} com.huawei.bigdata.spark.examples.KafkaProducer {brokerlist} {topic} {number of events produce every 0.02s} 示例： java -cp /opt/client/Spark2x/spark/conf:/opt/StructuredStreamingState-1.0.jar:/opt/client/Spark2x/spark/jars/*:/opt/client/Spark2x/spark/jars/streamingClient010/* com.huawei.bigdata.spark.examples.KafkaProducer xxx.xxx.xxx.xxx:21005,xxx.xxx.xxx.xxx:21005,xxx.xxx.xxx.xxx:21005 mytopic 10

查看Windows调测结果 Doris应用程序运行完成后，可通过如下方式查看运行情况。 通过IntelliJ IDEA运行结果查看应用程序运行情况。 通过Doris日志获取应用程序运行情况。 各样例程序运行结果如下： “doris-jdbc-example”样例运行成功后，显示信息如下： 2023-08-17 23:13:13,473 | INFO | main | Start execute doris example. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:41) 2023-08-17 23:13:13,885 | INFO | main | Start create database. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:44) 2023-08-17 23:13:13,949 | INFO | main | Database created successfully. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:46) 2023-08-17 23:13:13,950 | INFO | main | Start create table. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:49) 2023-08-17 23:13:14,132 | INFO | main | Table created successfully. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:51) 2023-08-17 23:13:14,133 | INFO | main | Start to insert data into the table. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:54) 2023-08-17 23:13:14,733 | INFO | main | Inserting data to the table succeeded. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:56) 2023-08-17 23:13:14,733 | INFO | main | Start to query table data. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:59) 2023-08-17 23:13:15,079 | INFO | main | Start to print query result. | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:121) 2023-08-17 23:13:15,079 | INFO | main | c1 c2 c3 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:126) 2023-08-17 23:13:15,079 | INFO | main | 0 0 0 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 1 10 100 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 2 20 200 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 3 30 300 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 4 40 400 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 5 50 500 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 6 60 600 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,080 | INFO | main | 7 70 700 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,081 | INFO | main | 8 80 800 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,081 | INFO | main | 9 90 900 | com.huawei.bigdata.doris.example.JDBCExample.query(JDBCExample.java:134) 2023-08-17 23:13:15,081 | INFO | main | Querying table data succeeded. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:61) 2023-08-17 23:13:15,081 | INFO | main | Start to delete the table. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:64) 2023-08-17 23:13:15,114 | INFO | main | Table deleted successfully. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:66) 2023-08-17 23:13:15,124 | INFO | main | Doris example execution successfully. | com.huawei.bigdata.doris.example.JDBCExample.main(JDBCExample.java:71) Process finished with exit code 0 Doris对接SpringBoot运行结果 在浏览器中访问链接“http://样例运行节点IP地址:8080/doris/example/executesql”，IDEA正常打印日志，请求返回如下图所示： 图7 返回样例运行信息

前提条件 已按照准备本地应用开发环境章节准备好开发用户，例如developuser，并下载用户的认证凭据文件到本地。 用户需要具备Oozie的普通用户权限，HDFS访问权限，Hive表读写权限，HBase读写权限以及Yarn的队列提交权限。 已在Linux环境中安装了完整的集群客户端。 获取Oozie服务器URL（任意节点），这个URL将是客户端提交流程任务的目标地址。 URL格式为：https://Oozie节点业务IP:21003/oozie。端口为“OOZIE_HTTPS_PORT”参数对应值，默认为21003。 例如，“https://10.10.10.176:21003/oozie”。

获取样例工程 通过开源镜像站获取样例工程。 下载样例工程的Maven工程源码和配置文件，并在本地配置好相关开发工具，可参考通过开源镜像站获取样例工程。 根据集群版本选择对应的分支，下载并获取 MRS 相关样例工程。 例如本章节场景对应示例为“hbase-example”样例，获取地址：https://github.com/huaweicloud/huaweicloud-mrs-example/tree/mrs-3.1.0/src/hbase-examples/hbase-example。 本地使用IDEA工具导入样例工程，等待Maven工程下载相关依赖包，具体操作可参考配置并导入样例工程。 图2 HBase样例工程示例 本地配置好Maven及SDK相关参数后，样例工程会自动加载相关依赖包。 将准备应用开发配置文件中获取的集群配置文件及用户认证文件放置在样例工程的“../src/main/resources/conf”目录下。 在“com.huawei.bigdata.hbase.examples”包的“TestMain”类中修改“userName”为实际用户名，例如“developuser”。 private static void login() throws IOException { if (User.isHBaseSecurityEnabled(conf)) { userName = "developuser"; //In Windows environment String userdir = TestMain.class.getClassLoader().getResource("conf").getPath() + File.separator; //In Linux environment //String userdir = System.getProperty("user.dir") + File.separator + "conf" + File.separator; LoginUtil.setJaasConf(ZOOKEEPER_DEFAULT_ LOG IN_CONTEXT_NAME, userName, userKeytabFile); LoginUtil.login(userName, userKeytabFile, krb5File, conf); } } 本样例工程中，假定用户开发一个应用程序，用于管理企业中的使用A业务的用户信息，A业务操作流程如下： 序号 步骤 1 根据已有信息创建表。 2 导入用户数据。 3 增加“教育信息”列族，在用户信息中新增用户的学历、职称等信息。 4 根据用户编号查询用户姓名和地址。 5 根据用户姓名进行查询。 6 为提升查询性能，创建二级索引或者删除二级索引。 7 用户销户，删除用户信息表中该用户的数据。 8 A业务结束后，删除用户信息表。 例如以下创建用户信息表代码片段在com.huawei.bigdata.hbase.examples包的“HBaseSample”类的testCreateTable方法中，其他各功能代码片段详情说明可参考HBase数据读写示例程序。 public void testCreateTable() { LOG.info("Entering testCreateTable."); TableDescriptorBuilder htd = TableDescriptorBuilder.newBuilder(tableName); //创建表描述符 ColumnFamilyDescriptorBuilder hcd = ColumnFamilyDescriptorBuilder.newBuilder(Bytes.toBytes("info")); //创建列族描述符 hcd.setDataBlockEncoding(DataBlockEncoding.FAST_DIFF); //设置编码算法，HBase提供了DIFF，FAST_DIFF，PREFIX三种编码算法 hcd.setCompressionType(Compression.Algorithm.SNAPPY); htd.setColumnFamily(hcd.build()); //添加列族描述符到表描述符中 Admin admin = null; try { admin = conn.getAdmin(); //获取Admin对象，Admin提供了建表、创建列族、检查表是否存在、修改表结构和列族结构以及删除表等功能。 if (!admin.tableExists(tableName)) { LOG.info("Creating table..."); admin.createTable(htd.build());//调用Admin的建表方法。 LOG.info(admin.getClusterMetrics().toString()); LOG.info(admin.listNamespaceDescriptors().toString()); LOG.info("Table created successfully."); } else { LOG.warn("table already exists"); } } catch (IOException e) { LOG.error("Create table failed " ,e); } finally { if (admin != null) { try { admin.close(); } catch (IOException e) { LOG.error("Failed to close admin " ,e); } } } LOG.info("Exiting testCreateTable."); }

回答 导致这个问题的主要原因是，yarn-client和yarn-cluster模式在提交任务时setAppName的执行顺序不同导致，yarn-client中setAppName是在向yarn注册Application之前读取，yarn-cluster模式则是在向yarn注册Application之后读取，这就导致yarn-cluster模式设置的应用名不生效。 解决措施： 在spark-submit脚本提交任务时用--name设置应用名和sparkconf.setAppName(appname)里面的应用名一样。 比如代码里设置的应用名为Spark Pi，用yarn-cluster模式提交应用时可以这样设置，在--name后面添加应用名，执行的命令如下： ./spark-submit --class org.apache.spark.examples.SparkPi --master yarn --deploy-mode cluster --name SparkPi jars/original-spark-examples*.jar 10

代码样例 代码示例中请根据实际情况，修改“OOZIE_URL_DEFAULT”为实际的任意Oozie的主机名，例如“https://10-1-131-131:21003/oozie/”。 public void test(String jobFilePath) { try { runJob(jobFilePath); } catch (Exception exception) { exception.printStackTrace(); } } private void runJob(String jobFilePath) throws OozieClientException, InterruptedException { Properties conf = getJobProperties(jobFilePath); String user = PropertiesCache.getInstance().getProperty("submit_user"); conf.setProperty("user.name", user); // submit and start the workflow job String jobId = oozieClient.run(conf); logger.info("Workflow job submitted: {}" , jobId); // wait until the workflow job finishes printing the status every 10 seconds while (oozieClient.getJobInfo(jobId).getStatus() == WorkflowJob.Status.RUNNING) { logger.info("Workflow job running ... {}" , jobId); Thread.sleep(10 * 1000); } // print the final status of the workflow job logger.info("Workflow job completed ... {}" , jobId); logger.info(String.valueOf(oozieClient.getJobInfo(jobId))); } /** * Get job.properties File in filePath * * @param filePath file path * @return job.properties * @since 2020-09-30 */ public Properties getJobProperties(String filePath) { File configFile = new File(filePath); if (!configFile.exists()) { logger.info(filePath , "{} is not exist."); } InputStream inputStream = null; // create a workflow job configuration Properties properties = oozieClient.createConfiguration(); try { inputStream = new FileInputStream(filePath); properties.load(inputStream); } catch (Exception e) { e.printStackTrace(); } finally { if (inputStream != null) { try { inputStream.close(); } catch (IOException ex) { ex.printStackTrace(); } } } return properties; }

查看调试结果 SLF4J: Class path contains multiple SLF4J bindings. SLF4J: Found binding in [jar:file:/D:/mavenlocal/org/apache/logging/log4j/log4j-slf4j-impl/2.6.2/log4j-slf4j-impl-2.6.2.jar!/org/slf4j/impl/StaticLoggerBinder.class] SLF4J: Found binding in [jar:file:/D:/mavenlocal/org/slf4j/slf4j-log4j12/1.7.30/slf4j-log4j12-1.7.30.jar!/org/slf4j/impl/StaticLoggerBinder.class] SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation. SLF4J: Actual binding is of type [org.apache.logging.slf4j.Log4jLoggerFactory] ERROR StatusLogger No log4j2 configuration file found. Using default configuration: logging only errors to the console. ---- Begin executing sql: CREATE TABLE IF NOT EXISTS CHILD (NAME STRING, AGE INT) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' ---- Result ---- Done executing sql: CREATE TABLE IF NOT EXISTS CHILD (NAME STRING, AGE INT) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' ---- ---- Begin executing sql: LOAD DATA INPATH 'hdfs:/data/data' INTO TABLE CHILD ---- Result ---- Done executing sql: LOAD DATA INPATH 'hdfs:/data/data' INTO TABLE CHILD ---- ---- Begin executing sql: SELECT * FROM child ---- NAME AGE Miranda 32 Karlie 23 Candice 27 ---- Done executing sql: SELECT * FROM child ---- ---- Begin executing sql: DROP TABLE child ---- Result ---- Done executing sql: DROP TABLE child ---- Process finished with exit code 0

编包并运行程序 获取样例代码。 下载样例工程的Maven工程源码和配置文件，请参见获取MRS应用开发样例工程。 将样例代码导入IDEA中。 获取配置文件。 从集群的客户端中获取文件。在“$SPARK_HOME/conf”中下载hive-site.xml与spark-defaults.conf文件到本地。 在HDFS中上传数据。 在Linux中新建文本文件data，将如下数据内容保存到data文件中。 Miranda,32 Karlie,23 Candice,27 在Linux系统HDFS客户端使用命令hadoop fs -mkdir /data（hdfs dfs命令有同样的作用），创建对应目录。 在Linux系统HDFS客户端使用命令hadoop fs -put data /data，上传数据文件。 在样例代码中配置相关参数。 将加载数据的sql语句改为“LOAD DATA INPATH 'hdfs:/data/data' INTO TABLE CHILD”。 在程序运行时添加运行参数，分别为hive-site.xml与spark-defaults.conf文件的路径。 运行程序。

提交PySpark作业 在提交 PySpark 作业时，添加以下参数。 指定压缩包： --archives R_PATH/pyspark_conda_env.tar.gz#environment # R_PATH为压缩包的hdfs或obs路径 配置Python环境： --archives R_PATH/pyspark_conda_env.tar.gz#environment # R_PATH 为压缩包的hdfs或obs路径 # 在local模式或者yarn-client模式中，需要将上述压缩包上传至提交作业的节点，并解压 --conf spark.pyspark.driver.python=L_PATH/pyspark_conda_env/bin/python # 请勿在Cluster模式中设置此参数，L_PATH为本地解压目录 --conf spark.pyspark.python=./environment/bin/python 对于pyspark shell交互式作业： pyspark --archives R_PATH/pyspark_conda_env.tar.gz#environment --conf spark.pyspark.driver.python=L_PATH/pyspark_conda_env/bin/python # L_PATH为pyspark_conda_env.tar.gz压缩包在本节点的解压目录 --conf spark.pyspark.python=./environment/bin/python

创建并打包Conda环境 创建环境： conda create -y -n pyspark_conda_env -c conda-forge conda-pack numpy python=3.9 激活环境： conda activate pyspark_conda_env 安装额外库: 如果需要安装额外的库，可以在激活环境后使用conda install命令。 打包环境: conda pack -f -o pyspark_conda_env.tar.gz 上传压缩包 将生成的pyspark_conda_env.tar.gz压缩包上传至您的集群的分布式文件系统（如HDFS）或 对象存储服务 （如OBS）。

自定义UDTF使用指导 在Spark 3.3.1中，PySpark目前没有直接提供类似Scala那样的UDTF（用户自定义表生成函数）的API。如果你需要实现UDTF效果（即一行数据转换成多行数据），通常可以使用如下替代方案： 利用UDF返回列表，再使用DataFrame的explode函数将数组拆分成多行。 使用RDD转换中的flatMap来实现一行生成多行数据的效果。 以一行数据转换成多行数据场景为例： 利用UDF返回Array，再使用explode拆分。 用Python函数编写一个UDF，该函数将输入数据（或一行中的某个字段）转化为列表（或数组）。然后使用DataFrame内置的explode函数将数组拆分成多行，从而达到UDTF的效果。 示例： from pyspark.sql import SparkSession from pyspark.sql.functions import udf, explode from pyspark.sql.types import ArrayType, StringType sparkSession = SparkSession.builder.appName("SimulateUDTF").getOrCreate() data = [("a,b,c",), ("d,e",)] df = spark.createDataFrame(data, ["csv_col"]) def split_string(s): if s: return s.split(",") return [] split_udf = udf(split_string, ArrayType(StringType())) df_with_array = df.withColumn("split_col", split_udf("csv_col")) df_exploded = df_with_array.withColumn("word", explode("split_col")) df_exploded.show() sparkSession.stop() 运行结果： +-------+---------+----+ |csv_col|split_col|word| +-------+---------+----+ | a,b,c|[a, b, c]| a| | a,b,c|[a, b, c]| b| | a,b,c|[a, b, c]| c| | d,e| [d, e]| d| | d,e| [d, e]| e| +-------+---------+----+ 利用RDD的flatMap实现。 对于更灵活的情况，您可以直接使用DataFrame的RDD接口，通过flatMap操作来实现转换。 样例（以将输入行拆分为多行为例）： from pyspark.sql import SparkSession sparkSession = SparkSession.builder.appName("SimulateUDTFWithFlatMap").getOrCreate() data = [("a,b,c",), ("d,e",)] df = spark.createDataFrame(data, ["csv_col"]) rdd = df.rdd.flatMap(lambda row: [(row.csv_col, token) for token in row.csv_col.split(",")]) new_df = rdd.toDF(["csv_col", "word"]) new_df.show() sparkSession.stop() 运行结果： +-------+----+ |csv_col|word| +-------+----+ | a,b,c| a| | a,b,c| b| | a,b,c| c| | d,e| d| | d,e| e| +-------+----+

自定义UDF使用指导 可通过pyspark.sql.functions.udf函数创建自定义udf，pyspark.sql.functions.udf介绍如下： pyspark.sql.functions.udf(f: Union[Callable[[…], Any], DataTypeOrString, None] = None, returnType: DataTypeOrString = StringType()) → Union[UserDefinedFunctionLike, Callable[[Callable[[…], Any]], UserDefinedFunctionLike]] 表1 参数说明 参数 说明 f python函数。 returnType 用户定义函数的返回类型。该值可以是pyspark.sql.types.DataType对象，也可以是ddl格式的类型字符串。 用户定义函数默认被认为是确定性的。由于优化，可以消除重复调用，甚至可能调用该函数比查询中出现的次数更多。如果你的函数不是确定性的，可以调用用户定义函数的asNondeterministic。例如： from pyspark.sql.types import IntegerType import random random_udf = udf(lambda: int(random.random() * 100), IntegerType()).asNondeterministic() 用户定义函数不支持条件表达式或布尔表达式中的短路，最终只能在内部执行。如果函数在特殊行上失败，则解决方法是将条件合并到函数中。 用户定义函数在调用方不接受关键字参数。 示例： from pyspark.sql import SparkSession from pyspark.sql.functions import udf from pyspark.sql.types import IntegerType sparkSession = SparkSession.builder.getOrCreate() slen = udf(lambda s: len(s), IntegerType()) @udf def to_upper(s): if s is not None: return s.upper() @udf(returnType=IntegerType()) def add_one(x): if x is not None: return x + 1 df = sparkSession.createDataFrame([(1, "John Doe", 21)], ("id", "name", "age")) df.select(slen("name").alias("slen(name)"), to_upper("name"), add_one("age")).show() sparkSession.stop() 运行结果： +----------+--------------+------------+ |slen(name)|to_upper(name)|add_one(age)| +----------+--------------+------------+ | 8| JOHN DOE| 22| +----------+--------------+------------+

请求示例 POST https://{endpoint}/v4/projects/526cefde62004de2b62b5e8dd2c2b3af/issue { "assigned_id" : 4091, "begin_time" : "2018-1-31", "description" : "", "developer_id" : 4091, "end_time" : "2018-07-05", "iteration_id" : 11302238, "name" : "test", "parent_issue_id" : 1679822, "priority_id" : 2, "severity_id" : 10, "status_id" : 1, "tracker_id" : 3 }

响应示例 状态码：200 OK { "actual_work_hours" : 0, "assigned_cc_user" : [ { "id" : 4091, "name" : "user_name_demo", "nick_name" : "nick_name_demo" } ], "assigned_user" : { "id" : 4091, "name" : "user_name_demo", "nick_name" : "nick_name_demo" }, "begin_time" : "2020-09-12", "creator" : { "id" : 4091, "name" : "user_name_demo", "nick_name" : "nick_name_demo" }, "custom_fields" : [ { "name" : "customField16", "value" : "多选框", "new_name" : "custom_field16" } ], "new_custom_fields" : [ { "custom_field" : "custom_field16", "field_name" : "field_name", "value" : "select1,select2" } ], "developer" : { "id" : 4091, "name" : "user_name_demo", "nick_name" : "nick_name_demo" }, "domain" : { "id" : 14, "name" : "性能" }, "done_ratio" : 0, "end_time" : "2020-09-19", "expected_work_hours" : 9, "id" : 4567, "project" : { "project_id" : "526cefde62004de2b62b5e8dd2c2b3af", "project_name" : "testDemo", "project_num_id" : 78953 }, "iteration" : { "id" : 456, "name" : "iteration_1" }, "module" : { "id" : 456, "name" : "Project" }, "parent_issue" : { "id" : 123, "name" : "paren_issue_demo" }, "priority" : { "id" : 1, "name" : "低" }, "severity" : { "id" : 12, "name" : "一般" }, "status" : { "id" : 1, "name" : "新建" }, "tracker" : { "id" : 7, "name" : "story" } }

响应参数 状态码：200 表5 响应Body参数 参数 参数类型 描述 actual_work_hours Double 参数解释： 实际工时。 取值范围： 最小长度：0。 assigned_cc_user Array of IssueUser objects 参数解释： 抄送人。 assigned_user IssueUser object 参数解释： 处理人 begin_time String 参数解释： 开始时间，年-月-日。 取值范围： 不涉及。 creator IssueUser object 参数解释： 创建者。 custom_fields Array of CustomField objects 参数解释： 自定义属性值,不建议使用，建议参考new_custom_fields字段。 developer IssueUser object 参数解释： 开发人员。 domain domain object 参数解释： id 领域, 14 '性能', 15 '功能', 16 '可靠性', 17 '网络安全', 18 '可维护性', 19 '其他DFX', 20 '可用性'。 done_ratio Integer 参数解释： 工作项进度值。 取值范围： 最小值0，最大值100。 end_time String 参数解释： 结束时间，年-月-日。 取值范围： 不涉及。 expected_work_hours Double 参数解释： 预计工时。 取值范围： 不涉及。 id Integer 参数解释： 工作项id。 取值范围： 不涉及。 iteration iteration object 参数解释： 迭代。 module module object 参数解释： 模块。 new_custom_fields Array of NewCustomField objects 参数解释： 自定义属性值。 parent_issue parent_issue object 参数解释： 父工作项。 priority priority object 参数解释： 工作项优先级。 1（低） 2（中） 3（高） project IssueProjectResponseV4 object 参数解释： 项目信息。 severity severity object 参数解释： 工作项重要程度。 status status object 参数解释： 工作项状态。 1（新建） 2（进行中） 3（已解决） 4（测试中） 5（已关闭） 6（已拒绝） tracker tracker object 参数解释： 工作项类型。 2（任务/Task） 3（缺陷/Bug） 5（Epic） 6（Feature） 7（Story） 表6 IssueUser 参数 参数类型 描述 id Integer 参数解释： 用户id 取值范围： 不涉及 name String 参数解释： 带租户名的用户名(租户名_用户名) 取值范围： 不涉及 nick_name String 参数解释： 昵称 取值范围： 不涉及 user_id String 参数解释： 用户uuid 取值范围： 不涉及 user_num_id Integer 参数解释： 用户数字id 取值范围： 不涉及 first_name String 参数解释： 用户名 取值范围： 不涉及 表7 CustomField 参数 参数类型 描述 name String 参数解释： 自定义属性名 取值范围： 不涉及 new_name String 参数解释： 自定义属性名 取值范围： 不涉及 value String 参数解释： 自定义属性对应的值 取值范围： 不涉及 表8 domain 参数 参数类型 描述 id Integer 参数解释： 领域id。 取值范围： 不涉及。 name String 参数解释： 领域。 取值范围： 不涉及。 表9 iteration 参数 参数类型 描述 id Integer 参数解释： 迭代id。 取值范围： 不涉及。 name String 参数解释： 迭代名。 取值范围： 不涉及。 表10 module 参数 参数类型 描述 id Integer 参数解释： 模块id。 取值范围： 不涉及。 name String 参数解释： 模块。 取值范围： 不涉及。 表11 NewCustomField 参数 参数类型 描述 custom_field String 参数解释： 自定义字段，可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的custom_field值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及 field_name String 参数解释： 自定义属性对应的值，多个值以英文逗号区分开, 可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的name值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及 value String 参数解释： 自定义属性对应的值，多个值以英文逗号区分开, 可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的options值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及 表12 parent_issue 参数 参数类型 描述 id Integer 参数解释： 父工作项id。 取值范围： 不涉及。 name String 参数解释： 父工作项。 取值范围： 不涉及。 表13 priority 参数 参数类型 描述 id Integer 参数解释： 优先级id。 取值范围： 不涉及。 name String 参数解释： 优先级。 取值范围： 不涉及。 表14 IssueProjectResponseV4 参数 参数类型 描述 project_id String 参数解释： 项目id 取值范围： 不涉及 project_name String 参数解释： 项目名称 取值范围： 不涉及 project_num_id Integer 参数解释： 项目数字id 取值范围： 最小值：0 表15 severity 参数 参数类型 描述 id Integer 参数解释： 重要程度id。 取值范围： 不涉及。 name String 参数解释： 重要程度。 取值范围： 不涉及。 表16 status 参数 参数类型 描述 id Integer 参数解释： 状态id。 取值范围： 不涉及。 name String 参数解释： 状态名称。 取值范围： 不涉及。 表17 tracker 参数 参数类型 描述 id Integer 参数解释： 类型id。 取值范围： 不涉及。 name String 参数解释： 类型名称。 取值范围： 不涉及。 状态码：400 表18 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：401 表19 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 参数解释： 用户Token。 通过调用 IAM 服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 约束限制： 必传。 取值范围： 最小长度：10，最大长度：32768。 默认取值： 不涉及。 表3 请求Body参数 参数 是否必选 参数类型 描述 actual_work_hours 否 Double 参数解释： 实际工时，实际工时由详细工时自动累加和子工作项自动卷积计算。 约束限制： 不涉及。 取值范围： 最小长度：0 默认取值： 不涉及。 assigned_id 否 Integer 参数解释： 处理人数字id，可通过[获取指定项目的成员用户列表]获取指定项目的成员用户列表，确认特定项目成员的用户数字id。 约束限制： 正则表达式，\d+。 取值范围： 最小长度：0 默认取值： 不涉及。 begin_time 否 String 参数解释： 开始时间，年-月-日 约束限制： 正则表达式，[1-9]\d{3}-(0?[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])。 取值范围： 匹配格式为 YYYY-MM-DD 的日期字符串，MM 是两位数的月份限制取值01-12，DD是两位数的日期限制取值01-31。 默认取值： 不涉及。 description 否 String 参数解释： 工作项描述。 约束限制： 可以为空。 取值范围： 最小长度 0。 默认取值： 不涉及。 developer_id 否 Integer 参数解释： 开发人员数字id，可通过[获取指定项目的成员用户列表]获取指定项目的成员用户列表，确认特定项目成员的用户数字id。 约束限制： 正则表达式，\d+。 取值范围： 最小值 0。 默认取值： 不涉及。 domain_id 否 Integer 参数解释： 领域id 14（性能） 15（功能） 16（可靠性） 17（网络安全） 18（可维护性） 19（其他DFX） 20（可用性） 约束限制： 正则表达式，\d+。 取值范围： 最小值 14 最大值 20。 默认取值： 不涉及。 done_ratio 否 Integer 参数解释： 工作项完成度。 约束限制： 输入数字0代表完成度为0%的工作项，输入100代表完成度为100%的工作项。 取值范围： 最小值 0 最大值 100。 默认取值： 不涉及。 end_time 否 String 参数解释： 结束时间，年-月-日。 约束限制： 正则表达式，[1-9]\d{3}-(0?[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])。 取值范围： 匹配格式为 YYYY-MM-DD 的日期字符串，MM 是两位数的月份限制取值01-12，DD是两位数的日期限制取值01-31。 默认取值： 不涉及。 expected_work_hours 否 Double 参数解释： 预计工时。 约束限制： 可以为空。 取值范围： 最小长度 0。 默认取值： 不涉及。 iteration_id 否 Integer 参数解释： 迭代id，可通过[获取指定项目的迭代列表]获取指定项目的迭代列表。 约束限制： 正则表达式，\d+。 取值范围： 最小长度 0。 默认取值： 不涉及。 module_id 否 Integer 参数解释： 模块id, 设置-工作项设置-模块设置内用户可新建模块。 约束限制： 正则表达式，\d+。 取值范围： 最小长度 0。 默认取值： 不涉及。 name 是 String 参数解释： 标题。 约束限制： 可以为空。 取值范围： 最小长度 0。 默认取值： 不涉及。 new_custom_fields 否 Array of NewCustomField objects 参数解释： 用户自定义字段。 约束限制： 不涉及。 parent_issue_id 否 Integer 参数解释： 父工作项的id。 约束限制： 创建子工作项时必填，父工作项的类型tracker_id不能为2 Task, 3 Bug。 取值范围： 最小长度 0。 默认取值： 不涉及。 priority_id 是 Integer 参数解释： 优先级。 约束限制： 正则表达式，\d+。 取值范围： 1 低, 2 中, 3 高。 默认取值： 不涉及。 severity_id 否 Integer 参数解释： 重要程度。 约束限制： 正则表达式，\d+。 取值范围： 10 关键, 11 重要, 12 一般, 13 提示。 默认取值： 不涉及。 status_id 否 Integer 参数解释： 状态id。 约束限制： 正则表达式，\d+。 取值范围： 1（新建） 2（进行中） 3（已解决） 4（测试中） 5（已关闭） 6（已拒绝） 默认取值： 不涉及。 tracker_id 是 Integer 参数解释： 工作项类型。 约束限制： Epic只能为 Feature的父工作项类型; Feature只能为Story的父工作项类型; Story只能为任务/Task,3缺陷/Bug的父。 取值范围： 2（任务/Task） 3（缺陷/Bug） 5（Epic） 6（Feature） 7（Story） 默认取值： 不涉及。 表4 NewCustomField 参数 是否必选 参数类型 描述 custom_field 否 String 参数解释： 自定义字段，可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的custom_field值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及 field_name 否 String 参数解释： 自定义属性对应的值，多个值以英文逗号区分开, 可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的name值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及 value 否 String 参数解释： 自定义属性对应的值，多个值以英文逗号区分开, 可以通过[查询Scrum工作项自定义字段]接口查询Scrum工作项自定义字段中返回的options值获取 约束限制： 可以为空 取值范围： 不涉及 默认取值： 不涉及

URI POST /v4/projects/{project_id}/issue 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数解释： 项目的32位uuid，项目唯一标识，通过[查询项目列表]接口获取，响应消息体中的project_id字段的值就是项目ID。 约束限制： 正则表达式，[A-Za-z0-9]{32}。 取值范围： 不涉及 默认取值： 不涉及。

响应示例 状态码：200 响应Body参数 { "projects" : [ { "project_num_id" : 3183801, "project_id" : "41bd3eab86544863b8fc92ffcd35e3c8", "project_name" : "demo_project", "description" : "demo", "created_time" : 1576114296000, "updated_time" : 1576114296000, "project_type" : "xboard", "creator" : { "user_num_id" : 4097, "user_id" : "c4bd39f0573a436589714bedbcca8536", "user_name" : "modile_user", "domain_id" : "2489d8cbba804db8bcd35384685ff3ac", "domain_name" : "modile_user", "nick_name" : "Tom.M.Riddle" } } ], "total" : 10 }

响应参数 状态码：200 表2 响应Body参数 参数 参数类型 描述 projects Array of projects objects 参数解释： 项目信息列表。 total Integer 参数解释： 项目总数。 取值范围： 最小值：0，最大值：10000。 表3 projects 参数 参数类型 描述 project_num_id Integer 参数解释： 项目numId（删除项目需要传，有的用户存的num_id）。 取值范围： 不涉及。 project_id String 参数解释： 项目uuid。 取值范围： 不涉及。 project_name String 参数解释： 项目名称。 取值范围： 不涉及。 description String 参数解释： 项目描述。 取值范围： 不涉及。 created_time Long 参数解释： 项目创建时间。 取值范围： 不涉及。 updated_time Long 参数解释： 项目更新时间。 取值范围： 不涉及。 project_type String 参数解释： 项目类型。 取值范围： scrum，normal，xboard。 creator creator object 参数解释： 创建者信息。 取值范围： 不涉及。 表4 creator 参数 参数类型 描述 user_num_id Integer 参数解释： 创建人numId。 取值范围： 不涉及。 user_id String 参数解释： 创建人id。 取值范围： 不涉及。 user_name String 参数解释： 创建人姓名。 取值范围： 不涉及。 domain_id String 参数解释： 创建人租户id。 取值范围： 不涉及。 domain_name String 参数解释： 创建人租户名称。 取值范围： 不涉及。 nick_name String 参数解释： 创建人租户昵称。 取值范围： 不涉及。 状态码：400 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：401 表6 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：403 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

URI GET /v4/projects 表1 Query参数 参数 是否必选 参数类型 描述 offset 是 Integer 参数解释： 分页索引，偏移量，offset是limit的整数倍数。 约束限制： 从0开始。 取值范围： 最小值：0，最大值：10000。 默认取值： 缺省值：0 limit 是 Integer 参数解释： 条数，每页显示查询的数量。 约束限制： 不涉及。 取值范围： 最小值：1，最大值：1000。 默认取值： 10 search 否 String 参数解释： 模糊查询项目名称或描述。 约束限制： 不支持通配符等高级查询。 取值范围： 不涉及。 默认取值： 不涉及。 project_type 否 String 参数解释： 项目类型。 约束限制： 正则表达式："scrum|normal|xboard"。 取值范围： scrum，normal，xboard 默认取值： 不涉及。 sort 否 String 参数解释： 排序条件。 约束限制： 正则表达式："((name|author_name|created_on|memcount)(:|%3A|%253A)(asc|desc|ASC|DESC)(,)?){0,4}"。 取值范围： ((name|author_name|created_on|memcount)(:|%3A|%253A)(asc|desc|ASC|DESC)(,)?){0,4}。 默认取值： 默认创建时间降序。 archive 否 String 参数解释： 是否归档。 约束限制： 正则表达式："false|true"。 取值范围： true（未归档，在使用的） false（已经归档，不能使用） 默认取值： 不涉及。 query_type 否 String 参数解释： 默认返回当前用户参与的项目列表。 约束限制： 正则表达式："absent|domain_projects"。 取值范围： domain_projects（租户下的所有项目列表）， absent（当前用户未参与的租户项目列表）。 默认取值： 不涉及。

响应参数 状态码：200 表2 响应Body参数 参数 参数类型 描述 created_time Long 参数解释： 创建时间，Unix时间戳，单位：毫秒 取值范围： 不涉及 domain_id String 参数解释： 租户id 约束限制： 正则表达式，[a-zA-Z0-9]{32}。 取值范围： 不涉及 domain_name String 参数解释： 租户名 取值范围： 不涉及 gender String 参数解释： 性别，枚举： male (男性） female (女性） 取值范围： male，female nick_name String 参数解释： 用户昵称 取值范围： 不涉及 updated_time Long 参数解释： 更新时间，Unix时间戳，单位：毫秒 取值范围： 不涉及 user_id String 参数解释： 用户id 约束限制： 正则表达式，[a-zA-Z0-9]{32}。 取值范围： 不涉及 user_name String 参数解释： 用户名 取值范围： 不涉及 user_num_id Integer 参数解释： 用户数字id 取值范围： 不涉及 user_type String 参数解释： 用户类型，枚举： User （云用户） Federation （联邦账号） 取值范围： User，Federation 状态码：400 表3 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：401 表4 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

响应示例 状态码：200 OK { "domain_id" : "4e919d73499648e3b0292cd3cbef806a", "domain_name" : "demo_user_name", "user_num_id" : "4060", "user_id" : "a360371833bf4c558f796fd707b44daf", "user_name" : "demo_user_name", "nick_name" : "我的名字要非常非常长才能测出问题", "created_time" : "1562318865000", "updated_time" : "1598074854000", "gender" : "male", "user_type" : "User" }

响应参数 状态码：200 表3 响应Body参数 参数 参数类型 描述 total Integer 参数解释： 查询的总记录数 取值范围： 不涉及 wikis Array of AttachWikiDetail objects 参数解释： 关联的wiki列表 取值范围： 不涉及 表4 AttachWikiDetail 参数 参数类型 描述 created_date String 参数解释： 创建时间，样例：YYYY-MM-DD HH:MM:SS 取值范围： 不涉及 issue_id Integer 参数解释： 工作项ID 取值范围： 0至9999999999 project SimpleProject object 参数解释： 项目信息 取值范围： 不涉及 region String 参数解释： region值 取值范围： 不涉及 wiki_author SimpleUser object 参数解释： 用户信息 取值范围： 不涉及 wiki_id String 参数解释： wiki ID 取值范围： 不涉及 wiki_title String 参数解释： Wiki标题 取值范围： 不涉及 表5 SimpleProject 参数 参数类型 描述 project_id String 参数解释： 项目的32位uuid，项目唯一标识，通过[查询项目列表]接口获取，响应消息体中的project_id字段的值就是项目ID 约束限制： 正则表达式，[A-Za-z0-9]{32}。 默认取值： 不涉及 project_name String 参数解释： 项目名称 取值范围： 不涉及 表6 SimpleUser 参数 参数类型 描述 nick_name String 参数解释： 用户昵称，可通过[获取指定项目的成员用户列表]接口获取指定项目的成员用户列表中nick_name字段 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 user_id String 参数解释： 用户uuid，可通过[获取指定项目的成员用户列表]接口获取指定项目的成员用户列表中user_id字段 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 user_name String 参数解释： 账号名，可通过[获取指定项目的成员用户列表]接口获取指定项目的成员用户列表中user_name字段 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 user_num_id Integer 参数解释： 用户数字id，可通过[获取指定项目的成员用户列表]接口获取指定项目的成员用户列表中user_num_id字段 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 状态码：400 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：401 表8 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述

响应示例 状态码：200 { "wikis" : [ { "issue_id" : 1234, "wiki_title" : "wikidemo", "wiki_author" : { "user_num_id" : 4091, "user_id" : "a360371833bf4c558f796fd707b44daf", "user_name" : "demo_user_name_xiongzhitest001", "nick_name" : "demo" }, "project" : { "project_name" : "demo", "project_id" : "58d9050550c847c89885c1797a718b0c" }, "created_date" : "2021-11-18 19:47:34", "wiki_id" : "1839097", "region" : "region01" } ], "total" : "success" }

URI GET /v4/projects/{project_id}/issues/{issue_id}/associated-wikis 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数解释： 项目的32位uuid，项目唯一标识，通过[查询项目列表]接口获取，响应消息体中的project_id字段的值就是项目ID。 约束限制： 正则表达式，[A-Za-z0-9]{32}。 取值范围： 不涉及 默认取值： 不涉及。 issue_id 是 Integer 参数解释： 工作项id，可通过[高级查询工作项]接口获取，响应消息体中的id字段的值就是工作项id。 约束限制： 正则表达式，[0-9]{1,10}。 取值范围： 最小长度：1，最大长度：10 默认取值： 不涉及 表2 Query参数 参数 是否必选 参数类型 描述 limit 是 Integer 参数解释： 条数，每页显示查询的数量。 约束限制： 不涉及。 取值范围： 最小值：1，最大值：1000。 默认取值： 10 offset 是 Integer 参数解释： 分页索引，偏移量，offset是limit的整数倍数。 约束限制： 从0开始。 取值范围： 最小值：0，最大值：10000。 默认取值： 缺省值：0

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 参数解释： 用户Token。 通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 约束限制： 必传。 取值范围： 最小长度：10，最大长度：32768。 默认取值： 不涉及。 表2 请求Body参数 参数 是否必选 参数类型 描述 nick_name 是 String 参数解释： 用户昵称，可通过[获取指定项目的成员用户列表]接口获取指定项目的成员用户列表中nick_name字段 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及

请求示例 Post https://{endpoint}/v1/eace9c0a00574de6878ab580daa9a317/completion-rate/query { "date_range" : "1598457600000,1598544000000", "dividend" : { "custom_field16" : "自定义字段值", "on_time" : "ontime" }, "divisor" : { "custom_field16" : "自定义字段值", "on_time" : "ontime" }, "metric_type" : "on-time_completion_rate", "sprint_id" : "8883443" }

响应示例 状态码：200 OK { "dividend_value" : 15, "divisor_value" : 20, "metric_name" : "completion_rate|bug_density|bugs_per_developer", "metric_value" : 0.8945, "project_id" : "eace9c0a00574de6878ab580daa9a317", "project_name" : "我的项目" }

响应参数 状态码：200 表6 响应Body参数 参数 参数类型 描述 dividend_value String 参数解释： 指标分子数值。 取值范围： 不涉及。 divisor_value String 参数解释： 指标分母数值。 取值范围： 不涉及。 metric_name String 参数解释： 指标名称。 取值范围： 不涉及。 metric_value String 参数解释： 指标数值。 取值范围： 不涉及。 project_id String 参数解释： 项目ID。 取值范围： 不涉及。 project_name String 参数解释： 项目名称。 取值范围： 不涉及。 状态码：400 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述 状态码：401 表8 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误描述