华为云用户手册

语法格式 更改操作符的所有者。 ALTER OPERATOR name ( { left_type | NONE } , { right_type | NONE } ) OWNER TO new_owner; 更改操作符的模式。 ALTER OPERATOR name ( { left_type | NONE } , { right_type | NONE } ) SET SCHEMA new_schema;

参数说明 role_name 现有角色名。 取值范围：已存在的用户名。 IN DATABASE database_name 表示修改角色在指定数据库上的参数。 SET configuration_parameter 设置角色的参数。ALTER ROLE中修改的会话参数只针对指定的角色，且在下一次该角色启动的会话中有效。 取值范围： configuration_parameter和value的取值请参见SET。 DEFAULT：表示清除configuration_parameter参数的值，configuration_parameter参数的值将继承本角色新产生的SESSION的默认值。 FROM CURRENT：取当前会话中的值设置为configuration_parameter参数的值。 RESET configuration_parameter/ALL 清除configuration_parameter参数的值。与SET configuration_parameter TO DEFAULT的效果相同。 取值范围：ALL表示清除所有参数的值。 ACCOUNT LOCK | ACCOUNT UNLOCK ACCOUNT LOCK：锁定账户，禁止登录数据库。 ACCOUNT UNLOCK：解锁账户，允许登录数据库。 PGUSER 当前版本不允许修改角色的PGUSER属性 PASSWORD/IDENTIFIED BY 'password' 重置或修改用户密码。除了初始用户外其他管理员或普通用户修改自己的密码需要输入正确的旧密码。只有初始用户、系统管理员（sysadmin）或拥有创建用户（CREATEROLE）权限的用户才可以重置普通用户密码，无需输入旧密码。初始用户可以重置系统管理员的密码，系统管理员不允许重置其他系统管理员的密码。应当使用单引号将用户密码括起来。 EXPIRED 设置密码失效。只有初始用户、系统管理员（sysadmin）或拥有创建用户（CREATEROLE）权限的用户才可以设置用户密码失效，其中系统管理员也可以设置自己或其他系统管理员密码失效。不允许设置初始用户密码失效。 密码失效的用户可以登录数据库但不能执行查询操作，只有修改密码或由管理员重置密码后才可以恢复正常查询操作。 其他参数请参见CREATE ROLE的参数说明。

语法格式 修改角色的权限。 ALTER ROLE role_name [ [ WITH ] option [ ... ] ]; 其中权限项子句option为。 {CREATEDB | NOCREATEDB} | {CREATEROLE | NOCREATEROLE} | {INHERIT | NOINHERIT} | {AUDITADMIN | NOAUDITADMIN} | {SYSADMIN | NOSYSADMIN} | {MONADMIN | NOMONADMIN} | {OPRADMIN | NOOPRADMIN} | {POLADMIN | NOPOLADMIN} | {USEFT | NOUSEFT} | { LOG IN | NOLOGIN} | {REPLICATION | NOREPLICATION} | {INDEPENDENT | NOINDEPENDENT} | {VCADMIN | NOVCADMIN} | {PERSISTENCE | NOPERSISTENCE} | CONNECTION LIMIT connlimit | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' [EXPIRED] | [ ENCRYPTED | UNENCRYPTED ] IDENTIFIED BY 'password' [ REPLACE 'old_password' | EXPIRED ] | [ ENCRYPTED | UNENCRYPTED ] PASSWORD { 'password' | DISABLE | EXPIRED } | [ ENCRYPTED | UNENCRYPTED ] IDENTIFIED BY { 'password' [ REPLACE 'old_password' ] | DISABLE } | VALID BEGIN 'timestamp' | VALID UNTIL 'timestamp' | RESOURCE POOL 'respool' | PERM SPACE 'spacelimit' | PGUSER 修改角色的名称。 ALTER ROLE role_name RENAME TO new_name; 锁定或解锁。 ALTER ROLE role_name ACCOUNT { LOCK | UNLOCK }; 设置角色的配置参数。 ALTER ROLE role_name [ IN DATABASE database_name ] SET configuration_parameter {{ TO | = } { value | DEFAULT } | FROM CURRENT}; 重置角色的配置参数。 ALTER ROLE role_name [ IN DATABASE database_name ] RESET {configuration_parameter|ALL};

参数说明 WITH [ RECURSIVE ] with_query [, ...] 用于声明一个或多个可以在主查询中通过名称引用的子查询，相当于临时表。 如果声明了RECURSIVE，那么允许SELECT子查询通过名称引用它自己。 其中with_query的详细格式为： with_query_name [ ( column_name [, ...] ) ] AS [ [ NOT ] MATERIALIZED ] ( {select | values | insert | update | delete} ) – with_query_name指定子查询生成的结果集名称，在查询中可使用该名称访问子查询的结果集。 – column_name指定子查询结果集中显示的列名。 – 每个子查询可以是SELECT，VALUES，INSERT，UPDATE或DELETE语句。 – 用户可以使用MATERIALIZED / NOT MATERIALIZED对CTE进行修饰。 如果声明为MATERIALIZED，WITH查询将被物化，生成一个子查询结果集的拷贝，在引用处直接查询该拷贝，因此WITH子查询无法和主干SELECT语句进行联合优化（如谓词下推、等价类传递等），对于此类场景可以使用NOT MATERIALIZED进行修饰，如果WITH查询语义上可以作为子查询内联执行，则可以进行上述优化。 如果用户没有显示声明物化属性则遵守以下规则：如果CTE只在所属主干语句中被引用一次，且语义上支持内联执行，则会被改写为子查询内联执行，否则以CTE Scan的方式物化执行。 INSERT ON DUPLICATE KEY UPDATE不支持WITH及WITH RECURSIVE子句。 INSERT语句的输出，只会显示最外层query block插入的tuple数量。比如： with cte as (insert into t1 values(1) retunring * ) insert into t1 select * from cte; 只会显示插入一条tuple，但实际上插入了两条。 plan_hint子句 以/*+ */的形式在INSERT关键字后，用于对INSERT对应的语句块生成的计划进行hint调优，详细用法请参见章节使用Plan Hint进行调优。每条语句中只有第一个/*+ plan_hint */注释块会作为hint生效，里面可以写多条hint。 table_name 要插入数据的目标表名。 取值范围：已存在的表名。 支持使用DATABASE LINK方式对远端表进行操作，使用方式详情请见DATABASE LINK。 partition_clause 指定分区插入操作 PARTITION { ( partition_name ) | FOR ( partition_value [, ...] ) } | SUBPARTITION { ( subpartition_name ) | FOR ( subpartition_value [, ...] ) } 关键字详见SELECT一节介绍 如果value子句的值和指定分区不一致，会抛出异常。 示例详见CREATE TABLE SUBPARTITION column_name 目标表中的字段名： 字段名可以有子字段名或者数组下标修饰。 没有在字段列表中出现的每个字段，将由系统默认值，或者声明时的默认值填充，若都没有则用NULL填充。例如，向一个复合类型中的某些字段插入数据的话，其他字段将是NULL。 目标字段（column_name）可以按顺序排列。如果没有列出任何字段，则默认全部字段，且顺序为表声明时的顺序。 如果value子句和query中只提供了N个字段，则目标字段为前N个字段。 value子句和query提供的值在表中从左到右关联到对应列。 取值范围：已存在的字段名。 expression 赋予对应column的一个有效表达式或值： 如果是INSERT ON DUPLICATE KEY UPDATE语句下，expression可以为VALUES(column_name)或EXCLUDED.column_name用来表示引用冲突行对应的column_name字段的值。需注意，其中VALUES(column_name)不支持嵌套在表达式中（例如VALUES(column_name)+1），但EXCLUDED不受此限制。 向表中字段插入单引号 " ' "时需要使用单引号自身进行转义。 如果插入行的表达式不是正确的数据类型，系统试图进行类型转换，若转换不成功，则插入数据失败，系统返回错误信息。 DEFAULT 对应字段名的缺省值。如果没有缺省值，则为NULL。 query 一个查询语句（SELECT语句），将查询结果作为插入的数据。 RETURNING 返回实际插入的行，RETURNING列表的语法与SELECT的输出列表一致。注意：INSERT ON DUPLICATE KEY UPDATE不支持RETURNING子句。 output_expression INSERT命令在每一行都被插入之后用于计算输出结果的表达式。 取值范围：该表达式可以使用table的任意字段。可以使用*返回被插入行的所有字段。 output_name 字段的输出名称。 取值范围：字符串，符合标识符命名规范。 ON DUPLICATE KEY UPDATE 对于带有唯一约束（UNIQUE INDEX或PRIMARY KEY）的表，如果插入数据违反唯一约束，则对冲突行执行UPDATE子句完成更新，对于不带唯一约束的表，则仅执行插入。UPDATE时，若指定NOTHING则忽略此条插入，可通过"EXCLUDE." 或者 "VALUES()" 来选择源数据相应的列。 支持触发器，触发器执行顺序由实际执行流程决定： 执行insert： 触发 before insert、 after insert触发器。 执行update：触发before insert、before update、after update触发器。 执行update nothing： 触发before insert触发器。 不支持延迟生效（DEFERRABLE）的唯一约束或主键。 如果表中存在多个唯一约束，如果所插入数据违反多个唯一约束，对于检测到冲突的第一行进行更新，其他冲突行不更新（检查顺序与索引维护具有强相关性，一般先创建的索引先进行冲突检查）。 如果插入多行，这些行均与表中同一行数据存在唯一约束冲突，则按照顺序，第一条执行插入或更新，之后依次执行更新。 主键、唯一索引列不允许UPDATE。 不支持列存，不支持外表。 expression不支持使用子查询表达式。

语法格式 ALTER DATA SOURCE src_name [TYPE 'type_str'] [VERSION {'version_str' | NULL}] [OPTIONS ( {[ ADD | SET | DROP ] optname ['optvalue']} [, ...] )]; ALTER DATA SOURCE src_name RENAME TO src_new_name; ALTER DATA SOURCE src_name OWNER TO new_owner;

参数说明 src_name 待修改的Data Source的名称。 取值范围：字符串，需要符合标识符命名规范。 TYPE 将Data Source原来的TYPE修改为指定值。 取值范围：空串或非空字符串。 VERSION 将Data Source原来的VERSION修改为指定值。 取值范围：空串或非空字符串或NULL。 OPTIONS 修改OPTIONS中的字段：增加（ADD）、修改（SET）、删除（DROP），且字段名称optname需唯一，具体要求如下： 增加字段：ADD可以省略，待增加字段不能已经存在了； 修改字段：SET不可省略，待修改字段必须存在； 删除字段：DROP不可省略，待删除字段必须存在，且不能指定optvalue； src_new_name 新的Data Source名称。 取值范围：字符串，需符合标识符命名规范。 new_user 对象的新属主。 取值范围：字符串，有效的用户名。

示例 --创建一个空Data Source对象。 gaussdb=# CREATE DATA SOURCE ds_test1; --修改名称。 gaussdb=# ALTER DATA SOURCE ds_test1 RENAME TO ds_test; --修改属主。 gaussdb=# CREATE USER user_test1 IDENTIFIED BY '********'; gaussdb=# ALTER USER user_test1 WITH SYSADMIN; gaussdb=# ALTER DATA SOURCE ds_test OWNER TO user_test1; --修改TYPE和VERSION。 gaussdb=# ALTER DATA SOURCE ds_test TYPE 'MPPDB_TYPE' VERSION 'XXX'; --添加字段。 gaussdb=# ALTER DATA SOURCE ds_test OPTIONS (add dsn 'gaussdb', username 'test_user'); --修改字段。 gaussdb=# ALTER DATA SOURCE ds_test OPTIONS (set dsn 'unknown'); --删除字段。 gaussdb=# ALTER DATA SOURCE ds_test OPTIONS (drop username); --删除Data Source和user对象。 gaussdb=# DROP DATA SOURCE ds_test; gaussdb=# DROP USER user_test1;

示例 请参见CREATE FUNCTION的示例。 重编译示例： -- 开启依赖功能 set behavior_compat_options ='plpgsql_dependency'; -- 创建存储过程 create or replace procedure test_proc(a int) is proc_var int; begin proc_var := a; end; / -- 用存储过程名重编译存储过程 alter procedure test_proc compile; -- 用存储过程带类型签名重编译存储过程 alter procedure test_proc(int) compile;

数据类型转换 数据库中有些数据类型间允许进行隐式类型转换（例如赋值、函数调用的参数等）、有些数据类型间不允许进行隐式数据类型转换（例如int和复合类型），可尝试使用 GaussDB 提供的类型转换函数，例如CAST进行数据类型强转。 GaussDB数据库 常见的隐式类型转换，请参见表1。 GaussDB支持的DATE的效限范围是：公元前4713年到公元294276年。 表1 隐式类型转换表 原始数据类型 目标数据类型 备注 CHAR VARCHAR2 - CHAR NUMBER 原数据必须由数字组成。 CHAR DATE 原数据不能超出合法日期范围。 CHAR RAW - CHAR CLOB - VARCHAR2 CHAR - VARCHAR2 NUMBER 原数据必须由数字组成。 VARCHAR2 DATE 原数据不能超出合法日期范围。 VARCHAR2 CLOB - NUMBER CHAR - NUMBER VARCHAR2 - DATE CHAR - DATE VARCHAR2 - RAW CHAR - RAW VARCHAR2 - CLOB CHAR - CLOB VARCHAR2 - CLOB NUMBER 原数据必须由数字组成。 INT4 CHAR - INT4 BOOLEAN - BOOLEAN INT4 - 父主题： 存储过程

V$GLOBAL_TRANSACTION V$GLOBAL_TRANSACTION视图显示有关当前活动全局事务的信息。默认只有系统管理员权限才可以访问此系统视图，普通用户需要授权才可以访问。该视图同时存在于PG_CATALOG和SYS schema下。 表1 V$GLOBAL_TRANSACTION字段 名称 类型 描述 formatid numeric 全局事务格式标识符。不支持，置NULL。 globalid raw 全局事务标识符。 branchid raw 全局事务分支标识符。不支持，置NULL。 branches numeric 全局事务分支总数。 refcount numeric 全局事务的同级数（必须与分支相同）。 preparecount numeric 已准备的全局事务分支数。 state character varying(38) 全局事务的分支的状态。 flags numeric 状态的数字表示形式。 coupling character varying(15) 指示分支是自由(`FREE`)、松散耦合(`LOOSELY COUPLED`)、还是紧密耦合(TIGHTLY COUPLED)。不支持，置NULL。 con_id numeric 与数据相关的容器的 ID。不支持，置0。 父主题： 系统视图

示例 --创建模式ot。 gaussdb=# CREATE SCHEMA ot; --创建表ot.t1及其同义词t1。 gaussdb=# CREATE TABLE ot.t1(id int, name varchar2(10)); gaussdb=# CREATE OR REPLACE SYNONYM t1 FOR ot.t1; --使用同义词t1。 gaussdb=# SELECT * FROM t1; gaussdb=# INSERT INTO t1 VALUES (1, 'ada'), (2, 'bob'); gaussdb=# UPDATE t1 SET t1.name = 'cici' WHERE t1.id = 2; --创建同义词v1及其关联视图ot.v_t1。 gaussdb=# CREATE SYNONYM v1 FOR ot.v_t1; gaussdb=# CREATE VIEW ot.v_t1 AS SELECT * FROM ot.t1; --使用同义词v1。 gaussdb=# SELECT * FROM v1; --创建重载函数ot.add及其同义词add。 gaussdb=# CREATE OR REPLACE FUNCTION ot.add(a integer, b integer) RETURNS integer AS $$ SELECT $1 + $2 $$ LANGUAGE sql; gaussdb=# CREATE OR REPLACE FUNCTION ot.add(a decimal(5,2), b decimal(5,2)) RETURNS decimal(5,2) AS $$ SELECT $1 + $2 $$ LANGUAGE sql; gaussdb=# CREATE OR REPLACE SYNONYM add FOR ot.add; --使用同义词add。 gaussdb=# SELECT add(1,2); gaussdb=# SELECT add(1.2,2.3); --创建存储过程ot.register及其同义词register。 gaussdb=# CREATE PROCEDURE ot.register(n_id integer, n_name varchar2(10)) SECURITY INVOKER AS BEGIN INSERT INTO ot.t1 VALUES(n_id, n_name); END; / gaussdb=# CREATE OR REPLACE SYNONYM register FOR ot.register; --使用同义词register，调用存储过程。 gaussdb=# CALL register(3,'mia'); --删除同义词。 gaussdb=# DROP SYNONYM t1; gaussdb=# DROP SYNONYM IF EXISTS v1; gaussdb=# DROP SYNONYM IF EXISTS add; gaussdb=# DROP SYNONYM register; gaussdb=# DROP SCHEMA ot CASCADE;

参数说明 synonym 创建的同义词名字，可以带模式名。 取值范围：字符串，要符合标识符命名规范。 object_name 关联的对象名字，可以带模式名。 取值范围：字符串，要符合标识符命名规范。 object_name可以是不存在的对象名称。 object_name可以是使用DATABASE LINK方式访问远程对象。DATABASE LINK详细使用方式请见DATABASE LINK。 避免对包含口令等敏感信息的函数，如加解密类函数gs_encrypt、gs_decrypt等创建别名并且使用别名调用，防止敏感信息泄露。

注意事项 PQprepare创建一个为PQexecPrepared执行用的预备语句，本特性支持命令的重复执行，不需要每次都进行解析和规划。PQprepare仅在协议3.0及以后的连接中支持，使用协议2.0时，PQprepare将失败。 该函数从查询字符串创建一个名为stmtName的预备语句，该查询字符串必须包含一个SQL命令。stmtName可以是""来创建一个未命名的语句，在这种情况下，任何预先存在的未命名的语句都将被自动替换；否则，如果在当前会话中已经定义了语句名称，则这是一个错误。如果使用了任何参数，那么在查询中将它们称为$1,$2等。nParams是在paramTypes[]数组中预先指定类型的参数的数量。（当nParams为0时，数组指针可以为NULL） paramTypes[]通过OID指定要分配给参数符号的数据类型。如果paramTypes为NULL ，或者数组中的任何特定元素为零，服务器将按照对非类型化字面字符串的相同方式为参数符号分配数据类型。另外，查询可以使用数字高于nParams的参数符号；还将推断这些符号的数据类型。 通过执行SQLPREPARE语句，还可以创建与PQexecPrepared一起使用的预备语句。此外，虽然没有用于删除预备语句的libpq函数，但是SQL DEALLOCATE语句可用于此目的。

ecpg预处理以及编译执行 准备嵌入式SQL-C源程序，以.pgc为后缀名，ecpg负责将其转换成可被编译器编译的C语言程序。 生成的C语言程序被编译器编译为可执行文件，运行该可执行文件实现客户端程序访问数据库。示例可参考常用示例章节。 ecpg预处理以及编译处理过程 预处理：ecpg -I $GAUSSHOME/include -o test.c test.pgc ecpg预处理的参数选项如下： ecpg [OPTION]... 其中OPTION参数选项如下： -o OUTFILE：预处理嵌入式SQL-C程序将结果写入OUTFILE，OUTFILE为C语言文件。 -I DIRECTORY：头文件的搜索路径。 -c：预处理嵌入式SQL-C程序自动生成C语言文件。 --version：查看ecpg当前版本。 编译：gcc -I $GAUSSHOME/include/ecpg -I $GAUSSHOME/include -I $GAUSSHOME/include/postgresql/server/ -L $GAUSSHOME/lib -lecpg -lrt -lpq -lpgtypes -lpthread test_ecpg.c -o test_ecpg 执行：./test ecpg作为编译预处理工具，若在预处理或编译过程中出现找不到头文件或者函数实现的报错信息，可以根据需要指定头文件，或者链接动态库。 ecpg需要gcc、ld等编译预处理工具，建议gcc使用7.3.0版本。 使用ecpg开发应用程序所依赖的其他动态库和头文件，常见的位于$GAUSSHOME/include/libpq, $GAUSSHOME/include。 编译过程中常见的动态库依赖：-lpq、-lpq_ce、-lpthread。若开发过程中需要使用libpq通信库，则需要连接-lpq和-lpq_ce；若开发过程中需要使用多线程连接，则需要连接-lpthread。 父主题： 基于ecpg开发

示例 ——创建数据表 gaussdb=# CREATE TABLE t1 (id int, name varchar); ——插入数据 gaussdb=# INSERT INTO t1 VALUES (1, 'zhangsan'); gaussdb=# INSERT INTO t1 VALUES (2, 'lisi'); gaussdb=# INSERT INTO t1 VALUES (3, 'wangwu'); gaussdb=# INSERT INTO t1 VALUES (4, 'lisa'); gaussdb=# INSERT INTO t1 VALUES (5, 'jack'); ——创建快照 gaussdb=# CREATE SNAPSHOT s1@1.0 comment is 'first version' AS SELECT * FROM t1; ——迭代创建快照 gaussdb=# CREATE SNAPSHOT s1@2.0 FROM @1.0 comment is 'inherits from @1.0' USING (INSERT VALUES(6, 'john'), (7, 'tim'); DELETE WHERE id = 1); ——查看快照内容 gaussdb=#SELECT * FROM DB4AISHOT(s1@1.0); ——快照采样 gaussdb=# SAMPLE SNAPSHOT s1@2.0 stratify by name as nick at ratio .5; ——删除快照 gaussdb=# PURGE SNAPSHOT s1@2.0; gaussdb=# PURGE SNAPSHOT s1nick@2.0; gaussdb=# PURGE SNAPSHOT s1@1.0; ——删除表格 gaussdb=# DROP TABLE t1;

语法格式 创建快照 可以采用“CREATE SNAPSHOT … AS”以及“CREATE SNAPSHOT … FROM”语句创建数据表快照。 CREATE SNAPSHOT AS CREATE SNAPSHOT qualified_name [@ [version]] [COMMENT IS comment_item] AS query; CREATE SNAPSHOT FROM CREATE SNAPSHOT qualified_name [@ [version]] FROM @ version [COMMENT IS comment_item] USING ( { INSERT [INTO SNAPSHOT] insert_item | UPDATE [SNAPSHOT] [AS alias] SET set_item [FROM from_item] [WHERE where_item] | DELETE [FROM SNAPSHOT] [AS alias] [USING using_item] [WHERE where_item] | ALTER [SNAPSHOT] { ADD and_item | DROP drop_item } [, ...] } [; ...] ); 删除快照。 PURGE SNAPSHOT PURGE SNAPSHOT qualified_name @ version; 快照采样。 SAMPLE SNAPSHOT SAMPLE SNAPSHOT qualified_name @ version [STRATIFY BY attr_list] { AS alias AT RATIO num [COMMENT IS comment_item] } [, ...] 快照发布。 PUBLISH SNAPSHOT PUBLISH SNAPSHOT qualified_name @ version; 快照存档。 ARCHIVE SNAPSHOT ARCHIVE SNAPSHOT qualified_name @ version; 查询快照。 SELECT * FROM DB4AISHOT (qualified_name @ version );

注意事项 本特性GUC参数db4ai_snapshot_mode，快照存储模型分为MSS和 CSS 两种；GUC参数db4ai_snapshot_version_delimiter，用于设定版本分隔符，仅接受设定单字节参数值，默认为“@”;GUC参数db4ai_snapshot_version_separator，用于设定子版本分隔符，仅接受设定单字节参数值，默认为“.”。 当快照选用增量存储方式时，各个快照中具有依赖关系。删除快照需要按照依赖顺序进行删除。 snapshot特性用于团队不同成员间维护数据，涉及管理员和普通用户之间的数据转写。所以在私有用户、三权分立(enableSeparationOfDuty=ON)等状态下，数据库不支持snapshot功能特性。 当需要稳定可用的快照用于AI训练等任务时，用户需要将快照发布。

参数说明 qualified_name 创建snapshot的名称。 取值范围：字符串，需要符合标识符命名规范。 version (可省略)snapshot的版本号，当省略设置。系统会自动顺延编号。 取值范围：字符串，数字编号配合分隔符。 comment_item 指定添加的评论内容。 取值范围：字符串，需要符合标识符命名规范。 insert_item 需要插入的对象名字。 取值范围：字符串，需要符合标识符命名规范。 alias 对当前对象取的别名。 取值范围：字符串，需要符合标识符命名规范。 set_item 当前操作的对象名。 取值范围：字符串，需要符合标识符命名规范。 from_item 用于连接的查询源对象的名称。 取值范围：字符串，需要符合标识符命名规范。 where_item 返回值为布尔型的任意表达式。 取值范围：字符串，需要符合标识符命名规范。 using_item 用于连接的对象名称。 取值范围：字符串，需要符合标识符命名规范。 and_item 需要并列处理的对象名称。 取值范围：字符串，需要符合标识符命名规范。 drop_item 需要drop的对象名称。 取值范围：字符串，需要符合标识符命名规范。 attr_list 目标对象的list集合。 取值范围：字符串，需要符合标识符命名规范。 num 指定的比例值。 取值范围：数字。

智能助手 智能助手通过NLP (Natural Language Processing) 机器学习，理解用户输入的集成业务需求，匹配系统支持的触发器、连接器和数据处理器，生成组合应用。可以对生成的组合应用进一步配置和编排，最后构建，部署上线。 操作步骤 登录新版ROMA Connect控制台。 在“工作台”页单击“智能助手”，弹出“智能助手”窗口。 在输入框输入想创建的组合应用描述内容，或者单击输入框下面的语言描述模板。 单击带下划线的连接器或处理器，可以在下拉框中替换所需的其它连接器或处理器。 单击键盘的“Enter”键生成组合应用，再单击“应用结果”，生成组合应用。 继续在编辑组合应用画布页面，进行流任务的配置和编排。 完成后单击右上角的“保存”。 在新建组合任务弹窗中填写组合应用的名称和描述，然后单击“确定”，完成组合应用的创建。

操作步骤 进入购买ROMA Connect套餐包页面。 在购买套餐包页面配置套餐包信息，完成后勾选“我已阅读并同意以上规则”，然后单击“下一步”。 表1 套餐包配置信息 参数 说明 区域 选择套餐包要使用的区域，即套餐包所应用的ROMA Connect实例所在区域。 规格选择 选择套餐包的规格，不同规格所提供的RCU时额度不同。 以月为单位，规格内提供RCU时/月用量。例如购买了1000RCU时/月规格的套餐包，开通5RCU的实例，则当月内该实例可以使用200小时，200小时后按需计费。如果有多个实例，则多个实例合并计算RCU数量。 购买时长 选择套餐包的购买时长，即套餐包的续使用周期。 如购买2个月，则可在连续2个月使用套餐包，每月套餐包内规格相同。 购买数量 填写套餐包的购买数量。同时购买多个套餐包时，套餐包同时生效，非依次生效。 在配置确认界面勾选同意协议的选项，然后单击“立即购买” ，在支付页面付费成功后完成套餐包购买。

创建FTP连接 登录新版ROMA Connect控制台。 在左侧导航栏选择“连接器”，在连接器页面单击“新建连接”。 选择“FTP”连接器。 在弹窗中配置连接器信息，完成后单击“确定”。 参数 说明 连接名称 填写连接器实例名称。 协议 选择FTP连接所使用的协议，当前支持选择“FTP”和“SFTP”。 主机IP FTP服务器的IP地址。 端口 FTP协议中，默认使用TCP端口中的20和21两个端口，其中20端口用于传输数据，21端口用于传输控制信息（命令）。 用户名 FTP用户名。 密码 FTP用户密码。 描述 填写连接器的描述信息，用于识别不同的连接器。

配置参数 参数 说明 操作 当前支持对称加密、对称解密、HMAC签名、HMAC验签。 加密算法 对称加/解密当前支持AES算法。 HMAC签名/验签当前支持HMAC算法。 加密模式 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 当前支持GCM模式。 PBKDF2口令 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 用于生成PBKDF2密钥。 PBKDF2哈希算法 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 支持SHA256、SHA384。 PBKDF2盐值 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 用于生成PBKDF2密钥。 密钥长度 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 生成的密钥长度，可选128、192、256。 明文 待加密明文/待签名或验签明文。 密文 待解密密文。 内容填充模式 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 当前支持PK CS 5Padding。 PBKDF2迭代次数 仅当“操作”选择“对称加密”和“对称解密”时需要配置。 用于生成PBKDF2密钥，默认为1000000。 消息认证码长度 仅当“操作”选择“对称加密”时需要配置。 用于生成随机TAG，默认为16。 初始向量长度 仅当“操作”选择“对称加密”时需要配置。 用于生成随机IV，默认为12。 额外认证数据长度 仅当“操作”选择“对称加密”时需要配置。 用于生成随机AAD，默认为16。 密钥 仅当“操作”选择“HMAC签名”和“HMAC验签”时需要配置。 HMAC签名密钥。 签名 仅当“操作”选择“HMAC验签”时需要配置。 HMAC签名结果。 签名算法 仅当“操作”选择“HMAC签名”和“HMAC验签”时需要配置。 HMAC签名算法，可选择SHA256、SHA384。

创建ActiveMQ连接 登录新版ROMA Connect控制台。 在左侧导航栏选择“连接器”，在连接器页面单击“新建连接”。 选择“ActiveMQ”连接器。 在弹窗中配置连接器信息，完成后单击“确定”。 参数 说明 连接名称 填写连接器实例名称。 Broker列表 ActiveMQ的Broker列表。 用户名 连接ActiveMQ的用户名。 密码 连接ActiveMQ的用户密码。 是否开启SSL认证 连接ActiveMQ时是否使用SSL认证。 描述 填写连接器的描述信息，用于识别不同的连接器。

创建ArtemisMQ连接 登录新版ROMA Connect控制台。 在左侧导航栏选择“连接器”，在连接器页面单击“新建连接”。 选择“ArtemisMQ”连接器。 在弹窗中配置连接器信息，完成后单击“确定”。 参数 说明 连接名称 填写连接器实例名称。 主机IP地址 填写ArtemisMQ的连接IP地址。 端口 链接ArtemisMQ的端口号。 用户名 连接ArtemisMQ的用户名。 密码 连接ArtemisMQ的用户密码。 是否开启SSL认证 连接ArtemisMQ时是否使用SSL认证。 描述 填写连接器的描述信息，用于识别不同的连接器。

修订记录 发布时间 修订记录 2023-11-15 第二十三次正式发布。 API V2新增桶操作、云服务、区域 2023-09-20 第二十二次正式发布。 更新终端节点。 2023-04-14 第二十一次正式发布。 更新创建迁移任务组。 2022-09-16 第二十次正式发布。 新增迁移任务组管理。 2022-07-28 第十九次正式发布。 更新终端节点。 2022-06-23 第十八次正式发布。 更新创建同步事件。 2021-05-28 第十七次正式发布。 更新错误码。 2021-02-25 第十六次正式发布。 优化错误码内容。 优化API v2（推荐）内容。 2020-12-28 第十五次正式发布。 优化API v2（推荐）、错误码内容。 2020-09-15 第十四次正式发布。 新增API v2（推荐）内容。 2019-11-30 第十三次正式发布。 在创建任务中，优化object_key、list_file与task_type对应关系说明。 在历史错误码中，新增错误码：S3M.0088。 2019-10-30 第十二次正式发布。 在终端节点中，更新 OMS 的Endpoint。 2019-08-31 第十一次正式发布。 在创建任务的请求参数中，增加参数bandwidth_policy。 增加修改流量控制策略一节。 在查询某个租户的所有任务的响应参数中，增加参数bandwidth_policy。 在查询指定ID的任务的响应参数中，增加参数bandwidth_policy。 在历史错误码中，增加错误码TRF.0013、TRF.0014、TRF.0301、S3M.0083~S3M.0087。 2019-04-29 第十次正式发布。 在创建任务的请求参数中，增加参数auto_restore。 在查询某个租户的所有任务的响应参数中，增加参数auto_restore。 在查询指定ID的任务的响应参数中，增加参数auto_restore。 在历史错误码中，增加错误码S3M.0082、TRF.0063、TRF.0064。 2019-04-17 第九次正式发布。 在认证鉴权中，更新Token认证的内容。 在终端节点中，更新OMS的Endpoint。 在API示例中，参数thread_num更新取值。 在创建任务中，参数region、topicUrn增加说明。 在创建任务中，源端cloud_type参数增加取值“HuaweiCloud”。 在创建任务中，dst_node数据结构的参数object_key修正为必选。 在创建任务中，参数authentication_type、authentication_key更新描述。 在创建任务中，参数enable_failed_object_recording更新描述。 在查询某个租户的所有任务中，参数authentication_type更新描述。 在历史错误码中，增加错误码S3M.0168、S3M.0169、TRF.0160。 2019-01-22 第八次正式发布。 在创建任务中，参数path更新描述。 2018-12-21 第七次正式发布。 在创建任务中，参数obs_bucket增加说明。 在创建任务中，参数protocol增加http取值。 在创建任务中，参数migrate_since更新描述。 在历史错误码中，错误码S3M.0081更新错误信息。 2018-09-30 第六次正式发布。 优化文档整体架构。 新增查询API版本接口。 源端cloud_type参数增加取值KingsoftCloud。 task_type参数增加取值prefix。 object_key参数增加废弃说明。 在API说明章节增加失败对象重传参数。 增加错误码：S3M.0079、S3M.0080、S3M.0081、S3M.0162、S3M.0163、S3M.0167、S3M.0256、TRF.0012、TRF.0159。 2018-08-09 第五次正式发布。 新增任务创建接口传入参数migrate_since, source_cdn, task_type。 新增任务查询接口响应参数source_cdn, task_type。 2018-06-06 第四次正式发布。 增加错误状态码406。 将object_key数据结构的参数名称“Keys”修改为“keys”。 2018-03-02 第三次正式发布。 增加错误码TRF.0158。 增加查询配额的接口。 2018-01-15 第二次正式发布。 修改源端cloud_type参数说明。 2017-09-15 第一次正式发布。

请求消息体（可选） 该部分可选。请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中username为用户名，domainname为用户所属的账号名称，********为用户登录密码，xxxxxxxxxxxxxxxxxx为project的名称，如“cn-north-1”，您可以从地区和终端节点获取。 scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token的作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxxxxxxxxxxxx" } } } } 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

请求方法 HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。 表2 HTTP方法 方法 说明 GET 请求服务器返回指定资源。 PUT 请求服务器更新指定资源。 POST 请求服务器新增资源或执行特殊操作。 DELETE 请求服务器删除指定资源，如删除对象等。 HEAD 请求服务器资源头部。 PATCH 请求服务器更新资源的部分内容。 当资源不存在的时候，PATCH可能会去创建一个新的资源。 在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为： 1 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 详细的公共请求消息头字段请参见表3。 表3 公共请求消息头 名称 描述 是否必选 示例 Host 请求的服务器信息，从服务API的URL中获取。值为hostname[:port]。端口缺省时使用默认的端口，https的默认端口为443。 否 使用AK/SK认证时该字段必选。 code.test.com or code.test.com:443 Content-Type 消息体的类型（格式）。推荐用户使用默认值application/json，有其他取值时会在具体接口中专门说明。 是 application/json Content-Length 请求body长度，单位为Byte。 否 3495 X-Project-Id project id，项目编号。请参考获取项目ID章节获取项目编号。 否 如果是专属云场景采用AK/SK认证方式的接口请求或者多project场景采用AK/SK认证的接口请求，则该字段必选。 e9993fc787d94b6c886cbaa340f9c0f4 X-Auth-Token 用户Token。 用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 请求响应成功后在响应消息头（Headers）中包含的“X-Subject-Token”的值即为Token值。 否 使用Token认证时该字段必选。 注：以下仅为Token示例片段 MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参见认证鉴权的“AK/SK认证”。 对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。 1 2 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求URI 请求URI由如下部分组成： {URI-scheme}://{Endpoint}/{resource-path}?{query-string} 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 表1 URI中的参数说明 参数 描述 URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint 指定承载REST服务端点的服务器 域名 或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点获取。 例如 IAM 服务在“华北-北京一”区域的Endpoint为“iam.cn-north-1.myhuaweicloud.com”。 resource-path 资源路径，也即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。 query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。 例如您需要获取IAM在“华北-北京一”区域的Token，则需使用“华北-北京一”区域的Endpoint（iam.cn-north-1.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。 1 https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens 图1 URI示意图 为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

AK/SK认证 AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。 AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。 AK（Access Key ID）：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。 SK（Secret Access Key）：与访问密钥ID结合使用的密钥，对请求进行加密签名，可标识发送方，并防止请求被修改。 使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。 签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。