华为云用户手册

响应参数 状态码： 200 表3 响应Body参数 参数 是否必选 参数类型 描述 id 否 String 模板主键ID create_time 否 String 创建时间 update_time 否 String 更新时间[yyyy-MM-dd HH:mm:ss] customer_id 否 String 租户customer id tenant 否 TentantBasic - template_name 否 String 模板名称 template_id 否 String 模板ID 注：只有模板审核通过之后才有值，未审核通过时，该值为空。 template_type 否 String 模板类型 app_name 否 String 应用名称 app_key 否 String 应用key sign_id 否 String 签名id template_content 否 String 模板内容 has_variable 否 String 是否有变量 Yes No template_desc 否 String 申请描述 review_desc 否 String 审核意见 review_order 否 String 审核人账号 flow_status 否 String 流程状态 Adopted：通过 Reviewing：审核中 Reject：拒绝 universal_template 否 String 是否是通用模板 0：否 1：是 status 否 String 模板状态 Test：测试 Normal：正常 region 否 String 地域 1. cn：国内 2. intl：国际 brackets 否 String 中括号类型。支持枚举值： CN：中文类型：【】 GB：英文类型： [] 须知： 默认值为：CN 输入值不在上述枚举值范围内的，也按CN处理。 只有地域为国内时，该字段有效。 site 否 String 地域，取值范围：cn及hk ，当前该参数暂时不使用 urge_status 否 String 催审状态 Yes No urge_time 否 String 催审时间 urge_desc 否 String 催审描述 send_country1 否 Integer 发送国家1 send_country2 否 Integer 发送国家2 send_country3 否 Integer 发送国家3 is_support_multiomp 否 Boolean 是否支持多OMP country_name 否 String 国家

请求示例 POST /report HTTP/1.1 Host: 205.145.111.168:9330 Content-Type: application/x-www-form-urlencoded Connection: close Pooltype: approxy Ompsid: 7f540777fe4b40dfb3c21d10f48781e3 TerminalIP: ****** TrcModule: AP UserTrace: application TraceHandle: DMZ_818405 sequence=1&total=1&orgCode=000&updateTime=2018-04-13T06%3A31%3A46Z&source=2&smsMsgId=b9d9b4fe-ad0e-4a2a-a2c7-445505b674ac_6&status=DELIVRD

接口类型 表1 接口类型说明 请求方法 POST 访问URI “发送短信”、“发送分批短信”接口中指定的用户回调地址。 通信协议 HTTPS/HTTP 回调接口使用HTTPS协议时，服务端需支持TLS1.2，加密套件需支持TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384，TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384中的一种或多种。

请求参数 表2 请求Headers参数 参数名称 是否必选 参数类型 默认值 说明 Content-Type 是 String 无 固定填application/x-www-form-urlencoded。 表3 请求Body参数说明 参数名称 是否必选 参数类型 默认值 说明 smsMsgId 是 String(1-50) 无 发送短信成功时返回的短信唯一标识。 total 否 String(1-2) 无 长短信拆分后的短信条数。 当短信未拆分时该参数取值为1。 sequence 否 String(1-2) 无 长短信拆分后的短信序号，当total参数取值大于1时，该参数才有效。 当短信未拆分时该参数取值为1。 status 是 String(1-7) 无 短信状态报告枚举值，常见取值请参考表 Status常见取值，处理方法请参考状态报告错误码。 source 否 String(枚举) 无 短信状态报告来源： 1：短信平台自行产生的状态报告。 2：短信中心返回的状态报告。 3：华为平台产生的状态报告。 updateTime 否 String(1-20) 无 短信资源的更新时间，通常为短信平台接收短信状态报告的时间，为UTC时间，格式为：yyyy-MM-dd'T'HH:mm:ss'Z'，该时间会通过urlencode转义为%3a。 当短信平台未收到短信中心上报的状态报告时，会自行构造状态报告，该状态报告中不携带“updateTime”参数。 extend 否 String(1-128) 无 扩展字段，由用户在发送短信的请求中携带。若用户发送短信时未携带extend参数，则状态报告中也不会携带extend参数。 to 否 String(1-21) 无 本条状态报告对应的短信的接收方号码，仅当状态报告中携带了extend参数时才会同时携带该参数。 表4 Status常见取值 取值 含义 DELIVRD 用户已成功收到短信。 EXPIRED 短信已超时。 DELETED 短信已删除。 UNDELIV 短信递送失败。 ACCEPTD 短信已接收。 UNKNOWN 短信状态未知。 REJECTD 短信被拒绝。 E200018 国内短信发送方通道校验失败。 E200019 国内短信发送方匹配通道失败。 E200020 国内短信签名通道校验失败。 E200021 国内短信签名匹配通道失败。 E200022 国内短信接收方通道校验失败。 E200023 国内短信接收方匹配通道失败。 E200025 国际短信接收方通道校验失败。 E200026 国际短信接收方匹配通道失败。 E200027 匹配网关失败。 E200032 短信需要模板。 E200034 短信重传超时。 E200035 短信协议字段替换失败。 E200036 南向速率管控配置为0。 E200038 接收长短信超时。 MILIMIT 号码达到分钟下发限制。 LIMIT 号码达到下发限制。 BEYONDN KEYWORD 短信关键字拦截。 BLACK 号码黑名单。 MBBLACK DJ:0255 运营商拦截，一般是因为短信内容不允许发送。 1 此类错误码多为手机号码问题，如手机为空号，关机，停机等。 24 MK:xxxx MN:xxxx LT:0001 MA:xxxx SMS C未返回响应消息。 MB:xxxx SMSC返回错误响应消息。 MC:xxxx 未从SMSC处接收到状态报告。 CA:xxxx SCP未返回响应消息。 CB:xxxx SCP返回错误响应消息。 DA:xxxx DSMP未返回响应消息。 DB:xxxx DSMP返回错误响应消息。 SA:xxxx SP未返回响应消息。 SB:xxxx SP返回错误响应消息。 IA:xxxx 下一级ISMG未返回响应消息。 IB:xxxx 下一级ISMG返回错误响应消息。 IC:xxxx 没有从下一级ISMG处接收到状态报告。 SC:0001 人工审核拦截 SC:0002 人工审核告警拦截 SC:0003 黑名单拦截 SC:0004 红名单拦截 SC:0005 投诉黑名单 SC:0006 禁用关键字拦截 SC:0007 特征关键字拦截 SC:0008 管控关键字拦截 SC:0009 缺失必备关键字 SC:0010 短信超频拦截 SC:0011 时段管控拦截 SC:0012 人工审核超时处理 SC:0013 签名黑名单拦截 SC:0014 免审核模板匹配 SC:0015 拦截模板匹配 SC:0016 退订黑名单拦截 SC:0017 非报备模板拦截 SC:0018 非报备签名拦截

支持的授权项 策略包含系统策略和自定义策略，如果系统策略不满足授权要求，管理员可以创建自定义策略，并通过给用户组授予自定义策略来进行精细的访问控制。策略支持的操作与API相对应，授权项列表说明如下： 权限：允许或拒绝某项操作。 对应API接口：自定义策略实际调用的API接口。 授权项：自定义策略中支持的Action，在自定义策略中的Action中写入授权项，可以实现授权项对应的权限功能。 依赖的授权项：部分Action存在对其他Action的依赖，需要将依赖的Action同时写入授权项，才能实现对应的权限功能。 IAM 项目(Project)/企业项目(Enterprise Project)：自定义策略的授权范围，包括IAM项目与企业项目。授权范围如果同时支持IAM项目和企业项目，表示此授权项对应的自定义策略，可以在IAM和企业管理两个服务中给用户组授权并生效。如果仅支持IAM项目，不支持企业项目，表示仅能在IAM中给用户组授权并生效，如果在企业管理中授权，则该自定义策略不生效。管理员可以在授权项列表中查看授权项是否支持IAM项目或企业项目，“√”表示支持，“×”表示暂不支持。关于IAM项目与企业项目的区别，详情请参见：IAM与企业管理的区别。 消息&短信的支持自定义策略授权项如表1所示。 表1 消息&短信授权项明细 权限 授权项 对应API接口 依赖的授权项 IAM项目(Project) 企业项目(Enterprise Project) 删除签名 msgsms:signatures:delete DELETE /v2/{project_id}/msgsms/signatures/{id} msgsms:service:getServicestatus msgsms:signatures:getSignature msgsms:signatures:getType msgsms:templates:getConfig √ × 删除短信模板 msgsms:templates:delete DELETE /v2/{project_id}/msgsms/templates/{id} msgsms:service:getServicestatus msgsms:templates:getMsgtemplate √ × 删除联系人 msgsms:contacts:delete 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:contacts:get √ × 查询短信应用数量 msgsms:applications:getCount GET /v2/{project_id}/msgsms/apps-count msgsms:service:getServicestatus √ × 查询短信应用 msgsms:applications:getApp GET /v2/{project_id}/msgsms/apps GET /v2/{project_id}/msgsms/apps/{id} msgsms:service:getServicestatus √ × 查询权限 msgsms:applications:getAuthority 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信应用密钥 msgsms:applications:getAppsecret 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询租户受限原因 msgsms:applications:getTenant 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询签名信息 msgsms:signatures:getSignature GET /v2/{project_id}/msgsms/signatures GET /v2/{project_id}/msgsms/signatures/{id} msgsms:service:getServicestatus √ × 查询短信类型 msgsms:signatures:getType 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询签名名称 msgsms:signatures:getSignatureName 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信模板 msgsms:templates:getMsgtemplate GET /v2/{project_id}/msgsms/templates GET /v2/{project_id}/msgsms/templates/{id} msgsms:service:getServicestatus √ × 查询催审配置 msgsms:templates:getConfig 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询校验租户订单状态 msgsms:service:getServicestatus 仅支持Console调用，API方式不支持 - √ × 查询开发者信息 msgsms:templates:getDeveloper 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信模板名称 msgsms:templates:getMsgtemplateName 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信模板变量 msgsms:templates:getVarilable GET /v2/{project_id}/msgsms/templates/{id}/varilable msgsms:service:getServicestatus √ × 查看群发助手任务名称 msgsms:msgBatchTasks:getMsgbatchtaskName 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询群发助手短信发送任务 msgsms:msgBatchTasks:getMsgbatchtask 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查看群发助手任务结果详情 msgsms:msgBatchTasks:getRecord 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 导出群发助手任务发送号码 msgsms:msgBatchTasks:download 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:msgBatchTasks:getMsgbatchtaskName msgsms:msgBatchTasks:getMsgbatchtask msgsms:msgBatchTasks:getRecord √ × 查询短信限额策略 msgsms:limits:get 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信业务统计数据 msgsms:statistics:getStatistics GET /v2/{project_id}/msgsms/metric/stat msgsms:service:getServicestatus √ × 导出短信业务统计数据 msgsms:statistics:exportStatistics 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:statistics:getStatistics √ × 查询联系人 msgsms:contacts:get 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询历史请求信息 msgsms:blacklists:getBlacklist 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信总览统计数据 msgsms:statistics:getOverviewStatistics 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询消息提醒 msgsms:notifications:get 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询单条短信价格 msgsms:price:getUnitPrice 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询企业项目 msgsms:enterpriseProjects:get 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询公共配置 msgsms:signatures:getConfig 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询租户企业名称 msgsms:signatures:getTenantEnterpriseName 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询短信发送国家 msgsms:templates:getCountry GET /v2/{project_id}/msgsms/country msgsms:service:getServicestatus √ × 创建短信应用 msgsms:applications:create POST /v2/{project_id}/msgsms/apps msgsms:service:getServicestatus msgsms:applications:getCount msgsms:applications:getTenant msgsms:applications:getAuthority msgsms:enterpriseProjects:get √ × 发送验证码 msgsms:verifycodes:sendVerifycode 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:applications:getCount msgsms:applications:getApp √ × 添加签名 msgsms:signatures:addSignature POST /v2/{project_id}/msgsms/signatures msgsms:service:getServicestatus msgsms:signatures:getType msgsms:templates:getDeveloper msgsms:applications:getTenant msgsms:applications:getApp msgsms:signatures:getConfig msgsms:signatures:getTenantEnterpriseName √ × 修改签名 msgsms:signatures:updateSignature PUT /v2/{project_id}/msgsms/signatures/{id} msgsms:service:getServicestatus msgsms:signatures:getSignature msgsms:signatures:getType msgsms:templates:getConfig √ × 签名申请催审 msgsms:signatures:approval 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:signatures:getSignature msgsms:signatures:getType msgsms:templates:getConfig √ × 创建短信模板 msgsms:templates:create POST /v2/{project_id}/msgsms/templates msgsms:service:getServicestatus msgsms:applications:getTenant msgsms:applications:getApp msgsms:signatures:getType msgsms:templates:getDeveloper msgsms:templates:getMsgtemplateName √ × 导入群发助手短信发送任务 msgsms:msgBatchTasks:upload 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 创建群发助手短信发送任务 msgsms:msgBatchTasks:create 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:applications:getApp msgsms:signatures:getType msgsms:msgBatchTasks:upload √ × 查看短信详情 msgsms:details:get GET /v2/{project_id}/msgsms/detail msgsms:service:getServicestatus √ × 添加联系人 msgsms:contacts:create 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 新增解除黑名单请求 msgsms:blacklists:update 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 更新短信应用密钥 msgsms:applications:updateAppsecret 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:applications:getCount msgsms:applications:getApp msgsms:verifycodes:sendVerifycode msgsms:applications:getAppsecret √ × 修改短信应用 msgsms:applications:updateApp PUT /v2/{project_id}/msgsms/apps/{id} msgsms:service:getServicestatus msgsms:applications:getCount msgsms:applications:getApp msgsms:enterpriseProjects:get √ × 申请激活签名 msgsms:signatures:activate PUT /v2/{project_id}/msgsms/signatures/{id}/active msgsms:service:getServicestatus msgsms:signatures:getSignature msgsms:signatures:getType msgsms:signatures:getSignatureName msgsms:templates:getConfig √ × 修改短信模板 msgsms:templates:update PUT /v2/{project_id}/msgsms/templates/{id} msgsms:service:getServicestatus msgsms:templates:getMsgtemplate msgsms:templates:getConfig msgsms:signatures:getSignature msgsms:applications:getTenant msgsms:applications:getApp msgsms:signatures:getType msgsms:templates:getDeveloper msgsms:templates:getMsgtemplateName √ × 更新群发助手定时任务 msgsms:msgBatchTasks:update 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:applications:getApp msgsms:signatures:getType √ × 设置短信限额策略 msgsms:limits:update 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 修改联系人 msgsms:contacts:update 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus msgsms:contacts:get √ × 批量导入短信模板 msgsms:templates:import 仅支持Console调用，API方式不支持 msgsms:service:getServicestatus √ × 查询企业营业执照文件 msgsms:businessLicense:get GET /v2/{project_id}/msgsms/upload-files msgsms:service:getServicestatus √ × 上传企业营业执照文件 msgsms:businessLicense:import POST /v2/{project_id}/msgsms/upload-files msgsms:service:getServicestatus √ ×

注意事项 短信发送成功后，平台收到状态报告，会实时推送状态报告给用户，最迟不超过72小时。 平台推送汇聚后的状态报告，状态报告存在一定时延。 短信平台批量推送状态报告，单次最多推送50条。 若“statusCallback”字段已设置，则优先使用该字段的取值作为短信状态报告的回调地址。 若“statusCallback”字段未设置，则使用应用中配置的批量接收状态报告地址。 若“statusCallback”字段未设置且未在应用端配置批量接收状态报告地址，则用户无法接收短信平台主动发送的状态报告。

请求示例 POST /batchReport HTTP/1.1 Host: 205.145.111.168:9330 Content-Type: application/JSON;charset=UTF-8 Connection: close Pooltype: approxy Ompsid: 7f540777fe4b40dfb3c21d10f48781e3 TerminalIP: ****** TrcModule: AP UserTrace: application TraceHandle: DMZ_818405 {"statusReportList":[{"sequence":"1","total":"1","updateTime":"2023-04-18T07:26:00Z","source":"2","smsMsgId":"f6dcba15-ced9-45f7-9f5e-af82328c5253_1188602","status":"DELIVRD"},{"sequence":"1","total":"1","updateTime":"2023-04-18T07:26:00Z","source":"2","smsMsgId":"f6dcba15-ced9-45f7-9f5e-af82328c5253_123456","status":"DELIVRD"}]}

接口类型 表1 接口类型说明 请求方法 POST 访问URI 用户在应用中配置的批量接收状态报告地址。 通信协议 HTTPS/HTTP 回调接口使用HTTPS协议时，服务端需支持TLS1.2，加密套件需支持 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384，TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256，TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384中的一种或多种。

请求URI 请求URI由如下部分组成。 {URI-scheme} :// {Endpoint} / {resource-path} ? {query-String} 请求URI包含在请求消息头中，大多数语言或框架都要求您从请求消息中单独传递，所以需要单独强调。 表1 URI中的参数说明 参数 描述 URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint 指定承载REST服务端点的服务器域名或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点获取。 消息&短信服务可用的Endpoint请参见获取终端节点。 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），拼接起来如下所示。 https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens 图1 URI示意图 为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，同一个服务的Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求消息体 请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中username为用户名，********为用户的登录密码，domainname为用户所属的账号名称，xxxxxxxxxxxxxxxxxx为project的名称，如“cn-north-1”，获取方法请参见获取账号、用户、项目的名称和ID。 scope参数定义了Token的作用域，上面示例中获取的Token仅能访问project下的资源。您还可以设置Token作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。 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”，则其请求为： POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 如下公共消息头需要添加到请求中。 Content-Type：消息体的类型（格式），必选，默认取值为“application/json”，有其他取值时会在具体接口中专门说明。 X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字段。用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

获取账号、用户、项目的名称和ID 从控制台获取账号名、账号ID、用户名、用户ID、项目名称、项目ID 在华为云首页右上角，单击“控制台”。 在右上角的用户名中选择“我的凭证”。 图1 进入我的凭证 在“我的凭证”界面，API凭证页签中，查看账号名、账号ID、用户名、用户ID、项目名称、项目ID。 图2 查看账号名、账号ID、用户名、用户ID、项目名称、项目ID 调用API获取用户ID、项目ID 获取用户ID请参考：管理员查询IAM用户列表。 获取项目ID请参考：查询指定条件下的项目列表。 父主题： 获取调用信息

注意事项 支持对行存表、行存分区表、列存表、列存分区表、复制表、unlogged表、hash表定义行访问控制策略。 不支持HDFS表、外表、临时表定义行访问控制策略。 不支持对视图定义行访问控制策略。 同一张表上可以创建多个行访问控制策略，一张表最多创建100个行访问控制策略。 具有管理员权限的用户和初始运维用户(Ruby)不受行访问控制影响，可以查看表的全量数据。 通过SQL语句、视图、函数、存储过程查询包含行访问控制策略的表，都会受影响。 不支持对行访问控制策略依赖的列进行类型修改。例如，不支持如下修改： 1 ALTER TABLE public.all_data ALTER COLUMN role TYPE text;

参数说明 policy_name 行访问控制策略名称，同一个数据表上行访问控制策略名称不能相同。 table_name 行访问控制策略的表名。 PERMISSIVE 指定行访问控制策略的类型为宽容性策略。对于一个给定的查询，将使用“OR”操作符将所有的宽容性策略组合。行访问控制策略的类型默认为宽容性策略。 RESTRICTIVE 指定行访问控制策略的类型为限制性策略。对于一个给定的查询，将使用“AND”操作符将所有的限制性策略组合。 至少需要一条宽容性策略允许对记录的访问。如果只有限制性策略存在，则不能访问任何记录。当宽容性和限制性策略共存时，只有当记录能通过至少一条宽容性策略以及所有的限制性策略时，该记录才能访问。 command 当前行访问控制影响的SQL操作，可指定操作包括：ALL、SELECT、UPDATE、DELETE。当未指定时，ALL为默认值，涵盖SELECT、UPDATE、DELETE操作。 当command为SELECT时，SELECT类操作受行访问控制的影响，只能查看到满足条件（using_expression返回值为TRUE）的元组数据，受影响的操作包括SELECT，UPDATE ... RETURNING，DELETE ... RETURNING。 当command为UPDATE时，UPDATE类操作受行访问控制的影响，只能更新满足条件（using_expression返回值为TRUE）的元组数据，受影响的操作包括UPDATE, UPDATE ... RETURNING, SELECT ... FOR UPDATE/SHARE。 当command为DELETE时，DELETE类操作受行访问控制的影响，只能删除满足条件（using_expression返回值为TRUE）的元组数据，受影响的操作包括DELETE, DELETE ... RETURNING。 行访问控制策略与适配的SQL语法关系参见下表： 表1 ROW LEVEL SECURITY策略与适配SQL语法关系 Command SELECT/ALL policy UPDATE/ALL policy DELETE/ALL policy SELECT Existing row No No SELECT FOR UPDATE/SHARE Existing row Existing row No UPDATE No Existing row No UPDATE RETURNING Existing row Existing row No DELETE No No Existing row DELETE RETURNING Existing row No Existing row role_name 行访问控制影响的数据库用户。 当未指定时，PUBLIC为默认值，PUBLIC表示影响所有数据库用户，可以指定多个受影响的数据库用户。 系统管理员不受行访问控制特性影响。

语法格式 1 2 3 4 5 CREATE [ ROW LEVEL SECURITY ] POLICY policy_name ON table_name [ AS { PERMISSIVE | RESTRICTIVE } ] [ FOR { ALL | SELECT | UPDATE | DELETE } ] [ TO { role_name | PUBLIC } [, ...] ] USING ( using_expression )

功能描述 对表创建行访问控制策略。 对表创建行访问控制策略时，需打开该表的行访问控制开关（ALTER TABLE ... ENABLE ROW LEVEL SECURITY）策略才能生效，否则不生效。 当前行访问控制会影响数据表的读取操作（SELECT、UPDATE、DELETE），暂不影响数据表的写入操作（INSERT、MERGE INTO）。表所有者或系统管理员可以在USING子句中创建表达式，并在客户端执行数据表读取操作时，数据库后台在查询重写阶段会将满足条件的表达式拼接并应用到执行计划中。针对数据表的每一条元组，当USING表达式返回TRUE时，元组对当前用户可见，当USING表达式返回FALSE或NULL时，元组对当前用户不可见。 行访问控制策略名称是针对表的，同一个数据表上不能有同名的行访问控制策略；对不同的数据表，可以有同名的行访问控制策略。 行访问控制策略可以应用到指定的操作（SELECT、UPDATE、DELETE、ALL），ALL表示会影响SELECT、UPDATE、DELETE三种操作；定义行访问控制策略时，若未指定受影响的相关操作，默认为ALL。 行访问控制策略可以应用到指定的用户（角色），也可应用到全部用户（PUBLIC）；定义行访问控制策略时，若未指定受影响的用户，默认为PUBLIC。

示例 为一个INSERT语句创建一个预备语句，然后执行它： 1 2 PREPARE insert_reason(integer,character(16),character(100)) AS INSERT INTO tpcds.reason_t1 VALUES($1,$2,$3); EXECUTE insert_reason(52, 'AAAAAAAADDAAAAAA', 'reason 52');

示例 使用ANALYZE语句更新表customer_info统计信息： 1 ANALYZE customer_info; 使用ANALYZE VERBOSE语句更新表customer_info统计信息，并输出表的相关信息： 1 2 3 4 5 ANALYZE VERBOSE customer_info; INFO: analyzing "cstore.pg_delta_3394584009"(cn_5002 pid=53078) INFO: analyzing "public.customer_info"(cn_5002 pid=53078) INFO: analyzing "public.customer_info" inheritance tree(cn_5002 pid=53078) ANALYZE

功能描述 用于收集有关数据库中表内容的统计信息，统计结果存储在系统表PG_STATISTIC下。执行计划生成器会使用这些统计数据，以确定最有效的执行计划。 如果没有指定参数，ANALYZE会分析当前数据库中的每个表和分区表。同时也可以通过指定table_name、column和partition_name参数把分析限定在特定的表、列或分区表中。 能够执行ANALYZE特定表的用户，包括表的所有者、表所在数据库的所有者、通过GRANT被授予该表上ANALYZE权限的用户或者被授予了gs_role_analyze_any角色的用户以及有SYSADMIN属性的用户。 在百分比采样收集统计信息时，用户需要被授予ANALYZE和SELECT权限。 ANALYZE|ANALYSE VERIFY用于检测数据库中普通表（行存表、列存表）的数据文件是否损坏，目前此命令暂不支持HDFS表。

语法格式 收集表的统计信息。 1 2 { ANALYZE | ANALYSE } [ VERBOSE ] [ table_name [ ( column_name [, ...] ) ] ]; 收集分区表的统计信息。 1 2 3 { ANALYZE | ANALYSE } [ VERBOSE ] [ table_name [ ( column_name [, ...] ) ] ] PARTITION ( patrition_name ) ; 普通分区表目前支持针对某个分区的统计信息的语法，但功能上不支持针对某个分区的统计信息收集。对指定分区执行ANALYZE，会有相应的WARNING提示。 收集外表的统计信息。 1 2 { ANALYZE | ANALYSE } [ VERBOSE ] { foreign_table_name | FOREIGN TABLES };

注意事项 仅8.1.1及以上集群版本支持在匿名块、事务块、函数或存储过程内对单表进行ANALYZE操作。 对于ANALYZE全库，库中各表的ANALYZE处于不同的事务中，所以不支持在匿名块、事务块、函数或存储过程内对全库执行ANALYZE。 统计信息的回滚操作不支持PG_CLASS中相关字段的回滚。 ANALYZE VERIFY操作处理的大多为异常场景检测需要使用RELEASE版本。ANALYZE VERIFY场景不触发远程读，因此远程读参数不生效。对于关键系统表出现错误被系统检测出页面损坏时，将直接报错不再继续检测。

参数说明 VERBOSE 启用显示进度信息。 如果指定了VERBOSE，ANALYZE发出进度信息，表明目前正在处理的表。各种有关表的统计信息也会打印出来。 table_name 需要分析的特定表的表名（可能会带模式名），如果省略，将对数据库中的所有表（非外部表）进行分析。 对于ANALYZE收集统计信息，目前仅支持行存表、列存表、HDFS表、ORC格式的OBS外表、CARBONDATA格式的OBS外表、协同分析的外表。 取值范围：已有的表名。 column_name，column_1_name，column_2_name 需要分析特定列的列名，默认为所有列。 取值范围：已有的列名。 partition_name 如果table为分区表，在关键字PARTITION后面指定分区名partition_name表示分析该分区表的统计信息。目前语法上支持分区表做ANALYZE，但功能实现上暂不支持对指定分区统计信息的分析。 取值范围：表的某一个分区名。 foreign_table_name 需要分析的特定外表的表名（可能会带模式名），该表的数据存放于HDFS分布式文件系统中。 取值范围：已有的表名。 FOREIGN TABLES 分析所有当前用户权限下，数据位于HDFS分布式文件系统中的HDFS外表。 index_name 需要分析的特定索引表的表名（可能会带模式名）。 取值范围：已有的表名。 FAST|COMPLETE 对于行存表，FAST模式下主要对于行存表的CRC和page header进行校验，如果校验失败则会告警; 而COMPLETE模式下，则主要对行存表的指针、tuple进行解析校验。 对于列存表，FAST模式下主要对于列存表的CRC和magic进行校验，如果校验失败则会告警；而COMPLETE模式下，则主要对列存表的CU进行解析校验。 CASCADE CASCADE模式下会对当前表的所有索引进行检测处理。

XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type 描述：从XML类型的值生成一个字符串。 返回值类型：type，可以是character，character varying或text（或其别名） 示例： 1 2 3 4 5 SELECT xmlserialize(content 'good' AS CHAR(10)); xmlserialize -------------- good (1 row)

示例 建立一个hdfs_server，其中hdfs_fdw为数据库中存在的foreign data wrapper： 1 2 3 4 5 CREATE SERVER hdfs_server FOREIGN DATA WRAPPER HDFS_FDW OPTIONS (address '10.10.0.100:25000,10.10.0.101:25000', hdfscfgpath '/opt/hadoop_client/HDFS/hadoop/etc/hadoop', type 'HDFS' ) ; 建立一个obs_server，其中dfs_fdw为数据库中存在的foreign data wrapper： 1 2 3 4 5 6 CREATE SERVER obs_server FOREIGN DATA WRAPPER DFS_FDW OPTIONS ( address 'obs.xxx.xxx.com', access_key 'xxxxxxxxx', secret_access_key 'yyyyyyyyyyyyy', type 'obs' ); 建立一个dli_server，其中dfs_fdw为数据库中存在的foreign data wrapper： 1 2 3 4 5 6 7 8 9 CREATE SERVER dli_server FOREIGN DATA WRAPPER DFS_FDW OPTIONS ( address 'obs.xxx.xxx.com', access_key 'xxxxxxxxx', secret_access_key 'yyyyyyyyyyyyy', type 'dli', dli_address 'dli.xxx.xxx.com', dli_access_key 'xxxxxxxxx', dli_secret_access_key 'yyyyyyyyyyyyy' ); 建立另外一个同构集群的server，其中gc_fdw为数据库中存在的foreign data wrapper： 1 2 3 4 5 6 CREATE SERVER server_remote FOREIGN DATA WRAPPER GC_FDW OPTIONS (address '10.10.0.100:25000,10.10.0.101:25000', dbname 'test', username 'test', password '{Password}' );

参数说明 server_name 要创建的外部服务器的名称。服务器名称在数据库中必须唯一。 取值范围：长度必须小于等于63。 FOREIGN DATA WRAPPER fdw_name 指定外部数据封装器的名字。 取值范围：fdw_name是数据库初始化时系统创建的数据封装器，目前对于HDFS集群，fdw_name的名字可以是hdfs_fdw或者dfs_fdw，对于其他同构集群，fdw_name为gc_fdw。 OPTIONS ( { option_name ' value ' } [, ...] ) 用于指定外部服务器的各类参数，详细的参数说明如下所示： address 指定的OBS服务终端节点或HDFS集群的IP地址。 OBS：OBS服务的终端节点（Endpoint）。 HDFS：HDFS集群的元数据节点（NameNode）所在的IP地址以及端口，或者同构其他集群的CN的IP地址以及端口。 为保证HA（High Availability），HDFS NameNode经常采用主备模式。主备NameNode的地址都需要加入到address值中。 GaussDB (DWS)访问HDFS服务时，会动态查找当前处于active状态的主NameNode。 若HDFS为联邦模式时，可将Router的地址都加入到address值中，GaussDB(DWS)访问HDFS服务时，会动态随机查找当前处于active状态的Router。 address option必须存在，若用于跨集群互联互通场景则只允许设置1个。 当server类型为 DLI 时，address为DLI服务上数据所存储的OBS address。 若HDFS为联邦模式时，即fed 'rbf'，address可设置为多组IP、port，对应为HDFS Router的address。 hdfscfgpath 该参数仅支持type为HDFS时设置。 用户通过配置hdfscfgpath参数来指定HDFS配置文件路径。GaussDB(DWS)会根据配置文件路径下的HDFS配置文件指定的连接配置方式，以及安全模式，来访问HDFS集群。非安全模式连接HDFS集群时，不支持数据传输加密。 如果没有指定address选项，默认采用hdfscfgpath指定的配置文件中指定的address。 fed 表示dfs_fdw连接的是HDFS为联邦模式。 取值rbf，表示HDFS为联邦rbf方式。 该参数8.1.2及以上版本支持。 encrypt 是否对数据进行加密，该参数仅支持type为OBS时设置。默认值为off。 取值范围： on表示对数据进行加密。 off表示不对数据进行加密。 access_key OBS访问协议对应的AK值（OBS云服务界面由用户获取），创建外表时AK值会保存到数据库的元数据表中。该参数仅支持type为OBS时设置。 secret_access_key OBS访问协议对应的SK值（OBS云服务界面由用户获取），创建外表时SK值会加密保存到数据库的元数据表中。该参数仅支持type为OBS时设置。 type 表示dfs_fdw连接的类型。 取值范围： OBS表示连接的是OBS。 HDFS表示连接的是HDFS。 DLI表示连接的是DLI。 dli_address DLI服务的终端节点，即endpoint。该参数仅支持type为DLI时设置。 dli_access_key DLI访问协议对应的AK值（DLI云服务界面由用户获取），创建外表时AK值会保存到数据库的元数据表中。该参数仅支持type为DLI时设置。 dli_secret_access_key DLI访问协议对应的SK值（DLI云服务界面由用户获取），创建外表时SK值会加密保存到数据库的元数据表中。该参数仅支持type为DLI时设置。 dbname 用于协同分析、跨集群互联互通，表示将要连接的远端集群的数据库名字。 username 用于协同分析、跨集群互联互通，表示将要连接的远端集群的用户名。 password 用于协同分析、跨集群互联互通，表示将要连接的远端集群的用户名密码。 对于云下集群迁移到云上的场景，从云下集群导出的server配置中密码为密文，由于云上和云下集群加解密的密钥不同，如果直接在云上集群执行导出时的CREATE SERVER，会执行失败，报解密失败的错误。这种场景下需要将CREATE SERVER中的password手动修改成明文密码进行配置。 syncsrv 仅用于跨集群互联互通，表示数据同步过程中使用到的GDS服务，设置方式与GDS外表的location属性相同。

语法格式 为当前会话设置会话用户标识符和当前用户标识符。 1 SET [ SESSION | LOCAL ] SESSION AUTHORIZATION role_name PASSWORD 'password'; 重置会话和当前用户标识符为初始认证的用户名。 1 2 {SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT | RESET SESSION AUTHORIZATION};

注意事项 一个数据库可以包含一个或多个已命名的Schema，Schema又包含表及其他数据库对象，包括数据类型、函数、操作符等。同一对象名可以在不同的Schema中使用而不会引起冲突。例如，Schema1和Schema2都可以包含一个名为mytable的表。 和数据库不同，Schema不是严格分离的。用户根据其对Schema的权限，可以访问所连接数据库的Schema中的对象。进行Schema权限管理首先需要对数据库的权限控制进行了解。 不能创建以PG_为前缀的Schema名，该类Schema为数据库系统预留的。 在当前数据库中创建用户时，系统会在当前数据库中为新用户创建一个同名Schema。 只要用户对当前数据库有CREATE权限，就可以创建Schema。 系统管理员在普通用户同名Schema下创建的对象，所有者为Schema的同名用户（非系统管理员）。 通过未修饰的表名（名字中只含有表名，没有“Schema名”）引用表时，系统会通过search_path（搜索路径）来判断该表是哪个Schema下的表。pg_temp和pg_catalog始终会作为搜索路径顺序中的前两位，无论二者是否出现在search_path中，或者出现在search_path中的任何位置。search_path（搜索路径）是一个Schema名列表，在其中找到的第一个表就是目标表，如果没有找到则报错。某个表即使存在，如果它的Schema不在search_path中，依然会查找失败，在搜索路径中的第一个Schema叫做“当前Schema”。它是搜索时查询的第一个Schema，同时在没有声明Schema名时，新创建的数据库对象会默认存放在该Schema下。

语法格式 根据指定的名字创建模式： 1 2 CREATE SCHEMA schema_name [ AUTHORIZATION user_name ] [ WITH PERM SPACE 'space_limit'] [ schema_element [ ... ] ]; 根据用户名创建模式： 1 CREATE SCHEMA AUTHORIZATION user_name [ WITH PERM SPACE 'space_limit'] [ schema_element [ ... ] ];

参数说明 schema_name 模式名字。 模式名不能和当前数据库里其他的模式重名。 模式的名字不可以“pg_”开头。 取值范围：字符串，要符合标识符的命名规范。 AUTHORIZATION user_name 指定模式的所有者。当不指定schema_name时，把user_name当作模式名，此时user_name只能是角色名。 取值范围：已存在的用户名/角色名。 WITH PERM SPACE 'space_limit' 指定模式的永久表存储空间上限。当不指定space_limit时，则不限制。 取值范围：字符串格式为正整数+单位，单位当前支持K/M/G/T/P。解析后的数值以K为单位，且范围不能够超过64比特表示的有符号整数，即1KB~9007199254740991KB。 schema_element 在模式里创建对象的SQL语句。目前仅支持CREATE TABLE、CREATE VIEW、CREATE INDEX、CREATE PARTITION、GRANT子句。 子命令所创建的对象都被AUTHORIZATION子句指定的用户所拥有。 如果当前搜索路径上的模式中存在同名对象时，需要明确指定引用对象所在的模式。可以通过命令SHOW SEARCH_PATH来查看当前搜索路径上的模式。