华为云用户手册

响应示例 状态码：200 操作成功，返回删除结果。 { "data" : { "id" : "djh28e62-xxxxxxxxx-a15be0d63812", "name" : "知识库名称", "result" : false, "reason" : "知识库已启用" } } 状态码：400 请求错误。 { "error_code" : "AIAE.40001001", "error_msg" : "参数xxxx不合法。" }

请求示例 删除Agent文件盒子中的文件。 DELETE https://aiae.appstage.myhuaweicloud.com/v1/routes/open/file/053f5dda365345a9a80cc63895df1647?agent-id=1eb7f2f6f105496c8065be77dc038b63 \ --header "Authorization: sk-162xxxxxxxxxxxx"

请求示例 { "name" : "测试", "description" : "测试", "data_type" : "TEXT", "tags" : [ "对话问答", "文案生成" ], "ingestion_config" : { "data_source" : "FILE_UPLOAD", "file_types" : [ "txt" ] }, "schedule_config" : { "schedule_type" : "ONCE" }, "preprocess_config" : { "cleaning_methods" : [ "invisible" ], "pdf_preprocess_type" : "NO_PREPRO CES S" }, "chunk_config" : { "slicing_configs" : { "txt" : { "slicing_method" : "autoSlicing" } } }, "extraction_config" : { "extraction_example" : "今天天气如何？答：还不错哦。", "extraction_mode" : "RULE_EXTRACTION", "rule_extraction_configs" : [ { "extraction_rule" : "SEPARATOR", "field_name" : "question", "separator_extraction" : { "contain_separator" : false, "extraction_code" : 1, "separator" : "？" } }, { "extraction_rule" : "TEMPLATE", "field_name" : "answer", "template_extraction" : { "contain_end" : true, "contain_start" : false, "end_with" : "。", "extraction_code" : 1, "start_with" : "答" } } ] }, "index_config" : { "description" : "索引配置", "long_text_solution" : "TRUNCATE_MODE", "name" : "索引配置", "rag_type" : "VECTOR_RAG", "retrieval_configs" : [ { "category" : "FULL_CHUNK", "name" : "chunk", "retrieval_return" : false, "text_filter" : false, "vector_retrieval" : false }, { "category" : "CHUNK_FRAGMENT", "name" : "question", "retrieval_return" : true, "text_filter" : true, "vector_retrieval" : true }, { "category" : "CHUNK_FRAGMENT", "name" : "answer", "retrieval_return" : true, "text_filter" : true, "vector_retrieval" : false } ], "vector_model_service_key" : "GPT-4" } }

请求示例 { "name" : "知识库名称", "description" : "知识库描述", "retrieval_status" : "ENABLE", "rag_type" : "VECTOR_RAG", "retrieval_config" : { "retrieval_modes" : [ "SEMANTIC_RETRIEVAL", "FULL_TEXT_RETRIEVAL" ], "retrieval_hybrid_mode" : "RRF" }, "knowledge_data_sets" : [ { "data_set_id" : "djh28e62-xxxxxxxxx-a15be0d63812", "data_set_version" : "v2024-11-21T11:36:55Z", "index_config_id" : "d3f28e62-xxxxxxx-a15be0d638a2" } ] }

请求示例 { "model" : "publisher:baichuan:Baichuan2-Turbo", "messages" : [ { "role" : "system", "content" : "You are a helpful assistant." }, { "role" : "user", "content" : "你好!" } ] }

响应示例 状态码：200 OK { "created" : 1718772336, "usage" : { "completion_tokens" : 23, "prompt_tokens" : 45, "total_tokens" : 68 }, "model" : "Baichuan2-Turbo", "id" : "chatcmpl-xxx", "choices" : [ { "finish_reason" : "stop", "index" : 0, "message" : { "role" : "assistant", "content" : "你好，有什么我可以帮助你的吗？" }, "logprobs" : null } ], "object" : "chat.completion" } 状态码：500 服务器内部错误或三方服务器内部错误。 { "error" : { "message" : "Internal server error, please try again later!", "type" : "internal_error", "param" : null, "code" : "internal_error" }, "error_code" : "AIAE.31001001", "error_msg" : "Internal server error, please try again later!" }

响应参数 状态码：200 表7 响应Body参数 参数 参数类型 描述 id String 参数解释： 文本对话唯一标识符。 取值范围： 不涉及。 choices Array of choices objects 参数解释： 返回体列表。 如果‘n’大于1，则结果为多个。 取值范围： 不涉及。 created Integer 参数解释： 问答发生的时间（格式为时间戳）。 取值范围： 不涉及。 model String 参数解释： 实际转发后调用的模型名称，与请求体中model可能不同。 取值范围： 不涉及。异常详情 object String 参数解释： 固定值。 取值范围： ‘chat.completion’。 usage CompletionUsage object 参数解释： 每次请求的用量统计。 取值范围： 不涉及。 表8 choices 参数 参数类型 描述 finish_reason String 参数解释： 返回结束的原因。 1.stop：模型达到自然停止点或提供的停止序列； 2.length：达到请求中指定的最大令牌数； 3.content_filter：由于内容过滤器的标志而省略了内容。 取值范围： 不涉及。 index Integer 参数解释： 返回多个choices时，每个choice对应的顺序。 取值范围： 不涉及。 message ChatCompletionResponseMessage object 参数解释： 模型服务返回的具体消息体内容。 取值范围： 不涉及。 表9 ChatCompletionResponseMessage 参数 参数类型 描述 content String 参数解释： 返回消息体的内容。 取值范围： 不涉及。 role String 参数解释： 返回消息体的角色。 取值范围： 不涉及。 表10 CompletionUsage 参数 参数类型 描述 completion_tokens Integer 参数解释： 回答包含的token数。 取值范围： 不涉及。 prompt_tokens Integer 参数解释： 提问包含的token数。 取值范围： 不涉及。 total_tokens Integer 参数解释： 提问+回答token总数。 取值范围： 不涉及。 状态码：500 表11 响应Body参数 参数 参数类型 描述 error Error object 参数解释： 异常详情。 取值范围： 不涉及。 error_code String 参数解释： 平台异常错误码。 取值范围： 不涉及。 error_msg String 参数解释： 异常信息。 取值范围： 不涉及。 表12 Error 参数 参数类型 描述 code String 参数解释： 异常码。 取值范围： 不涉及。 message String 参数解释： 异常信息。 取值范围： 不涉及。 param String 参数解释： 异常参数，暂未使用。 取值范围： 不涉及。 type String 参数解释： 异常类型，同code。 取值范围： 不涉及。

chat 将用户输入的对话内容传递给大模型，大模型对当前对话做出响应。 输入 配置执行动作，相关参数说明如表4所示。 表4 输入参数说明 参数 是否必填项 说明 模型服务调用ID 是 需要调用的大模型。 对于资产中心的模型，在资产中心选择“大模型”页签，单击模型卡片进入模型详情页面，查看模型服务调用ID。 对于我的模型（我部署的、我接入的）和我的路由策略，需要填写模型服务调用ID，请单击“获取模型服务调用ID”，进入“我的模型服务”页面，在模型服务列表中单击复制。 消息 是 选择数组类型的节点输出。 单击可切换为数组样式，配置“角色”和“对话内容（输入）”。 角色：对话内容对应的角色，支持user或system。 user表示用户向大模型提问。 system表示给大模型输入对话背景及设定。 对话内容：支持自定义输入文本，也可将前置节点的输出作为输入。 当角色为user时，输入发送给大模型的问题。例如：请帮我分析一下这个股票的潜在价值。 当角色为system时，输入大模型的对话背景，即对大模型的设定。例如输入给大模型：你是一个理财专家，请在后续的回答中，结合理财技巧给出答复。 高级配置 频率惩罚 否 介于-2.0和2.0之间的数字。正值会尽量避免使用常见的单词和短语，更倾向于生成较少见的单词。 输入加输出最大token数 否 表示模型输入加输出的最大长度。 存在惩罚 否 介于-2.0和2.0之间的数字。正值会尽量避免重复已经使用过的词语，更倾向于生成新词语。 温度 否 较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定。建议该参数和“多样性”只设置1个。 多样性 否 影响输出文本的多样性，取值越大，生成文本的多样性越强。建议该参数和“温度”只设置1个。 输出 该执行动作是根据用户定义的内容输出指定参数。 节点实例 在工作流中首次调用LLM节点需要新增实例，实例是节点的鉴权方式，如果未新增实例，节点就无法调通。 单击“新增实例”，在“创建实例”面板，配置表5参数信息。 表5 创建实例参数说明 参数名称 参数说明 基本信息 实例名称 必填项，自定义实例名称。 描述 选填项，输入实例相关描述信息。 验证信息 API Key 必填项，具体介绍请参见创建API Key。 单击“保存”，创建实例成功。 节点备注 输入节点备注信息，方便后续查阅节点功能。

内置函数介绍 AI原生应用引擎除了支持用户创建自定义函数，同时也提供了内置函数供用户在Code节点中使用。内置函数的介绍如表1所示。 表1 内置函数介绍 类型 名称 说明 示例 数学函数 add 返回两个及以上数字相加的结果。 使用示例：add(1, 1.5) 结果示例：2.5 使用示例：add(1, 1) 结果示例：2 subtract 返回第一个数字减去第二个数字得到的结果。 使用示例：subtract(1.5, 1) 结果示例：0.5 使用示例：subtract(2, 1) 结果示例：1 multiply 返回将两个数字相乘得到的乘积。 使用示例：multiply(1.5, 1) 结果示例：1.5 使用示例：multiply(1.5, 2) 结果示例：3 division 返回第一个数字除以第二个数字的结果。 使用示例：division(10, 5) 结果示例：2 使用示例：division(11, 5) 结果示例：2.2 mod 返回第一个数字除以第二个数字的余数。 使用示例：mod(1, 3) 结果示例：1 使用梳理：mod(4, 2) 结果示例：0 roundingToNearest 按照指定的小数位数四舍五入。 使用示例：roundingToNearest(2.54,1) 结果示例：2.5 使用示例：roundingToNearest(2.55,1) 结果示例：2.6 roundingUp 按照指定的小数位数进位。 使用示例：roundingUp(2.54,1) 结果示例：2.6 使用示例：roundingUp(2.54,0) 结果示例：3 roundingDown 按照指定的小数位数舍弃。 使用示例：roundingDown(2.59,1) 结果示例：2.5 使用示例：roundingDown(2.599,2) 结果示例：2.59 操作函数 addProperty 将属性及其值添加到JSON对象，并返回更新的对象。将color属性添加到JSON对象，可通过jsonToBean ()函数将其从字符串转换为JSON。当前对象已包含brand、quantity两个属性。该函数将指定的值复制给指定的新属性，并返回更新后的对象。 使用示例：addProperty(jsonToBean({"brand":"huawei","quantity":"1000"}), color, red) 结果示例： { “brand”: “huawei”， “quantity”: “1000”， “color”: “red” } getProperty 获取Map对象属性值。 获取quantity属性对应的值，可通过jsonToBean ()函数将其从字符串转换为JSON。当前对象已包含brand、quantity两个属性。该函数返回指定属性对应的值，如果不存在，则返回指定的默认值。 使用示例：addProperty(jsonToBean({"brand":"huawei","quantity":"1000"}), ‘quantity, ‘500’) 结果示例：1000 对象函数 isEmpty 判断对象是否为空。 object代表一个JSON对象。 使用示例：isEmpty(object) 结果示例：false/true jsonQuery JSON对象查找。 object代表一个JSON对象。 使用示例：jsonQuery(object,/ItemCode) 结果示例：A0001 jsonToBean JSON字符串转对象。 使用示例：jsonToBean(jsonstring) 结果示例：object 字符串函数 beanToJson 对象转JSON字符串。 使用示例：beanToJson(object) jsonQueryToText JSON对象查找，返回String，查找对象中的ItemCode属性的值。 使用示例：jsonQuery(object,/ItemCode) 结果示例：A0001 length 返回字符串长度或数组中的项数。 使用示例：length("abcdef") 结果示例：6 日期函数 formatDateTime 以日期格式返回字符串。 使用示例：formatDateTime(1234,yyyy-MM-dd HH:mm:ss,GMT+8) 结果示例：1970-01-01 08:00:01 getSystemTime 获取当前系统时间。 使用示例：getSystemTime(yyyy-MM-dd HH:mm:ss,0) 结果示例：2023-11-03 15:12:48 getSystemTimestamp 获取当前系统时间戳。 使用示例：getSystemTimestamp(0) 结果示例：1.69900E+12 系统函数 getDomainId 获取当前登录用户的租户ID。 使用示例：getDomainId() 结果示例：d562d0bdc8************0048ad6702 getDomainName 获取当前登录用户的租户名称。 使用示例：getDomainName() 结果示例：zhangsan getProjectId 获取当前登录用户的项目ID。 使用示例：getProjectId() 结果示例：5d73148959************7ed5d88f1b 转换函数 parseInt 将String类型的参数转换为Int类型的数字。 使用示例：parseInt(12) 结果示例：12 parseBoolean 将字符串类型的参数转换为Boolean类型。 使用示例：parseBoolean(safdaf) 结果示例：FALSE SQL语句校验函数 sqlFormat 将SQL语句校验并格式化之后，输出原始SQL语句。 使用示例：sqlFormat(sql) 结果示例：sql sqlFormatToUppercase 将SQL语句校验并格式化之后，可以输出原始SQL语句，也可以输出关键字全大写语句。 使用示例：sqlFormat(sql,true) 结果示例：sql 父主题： 管理工作流

调用子流程 调用子流程是工作流的基础节点之一，仅包含“同步调用子流程”一个执行动作。 您可以使用该节点调用或触发另一个工作流（即子工作流）。 输入 表1 输入参数说明 参数 是否必填项 说明 引用集成流 是 选择待调用的子工作流。 集成流入参 是 子工作流的输入参数。 输出 该执行动作是根据用户定义的内容输出指定参数。 节点备注 输入节点备注信息，方便后续查阅节点功能。 父主题： 工作流基础节点说明

响应参数 表3 响应Body参数 参数 参数类型 描述 result String 调用是否成功。 SUCCESS：成功 FAIL：失败 data List of data 调用的返回结果。 errors List 异常信息列表。 表4 data 参数 参数类型 描述 data.id Long 事务型任务ID。 data.status String 事务型任务的提交状态。 not start：未提交 executing：执行中 success：提交成功 fail：提交失败，步骤2：执行iDME原子接口执行的任一原子接口若执行失败，均表示事务型任务提交失败。 data.tasks List of task 事务型任务下的原子接口列表。 表5 tasks 参数 参数类型 描述 data.tasks.result String 原子接口的执行详情。 data.tasks.task_no Integer 原子接口的执行序号。 data.tasks.task_status String 原子接口的执行状态。 success：成功 fail：失败 not start：未执行

请求示例 根据事务型任务ID，查询该事务型任务的执行结果。 GET https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v1/transaction-apis/transactions/538322343718555649 X-Auth-Token: ABCDEFJ....

响应示例 { "result": "SUCCESS", "data": [ { "id": 538322343718555649, "status": "success", "tasks": [ { "result": "{\"id\": 538327077254860800, \"tenant\": {\"id\": -1, \"code\": \"basicTenant\", \"name\": \"basicTenant\", \"creator\": \"xdmAdmin\", \"modifier\": \"xdmAdmin\", \"className\": \"Tenant\", \"createTime\": 1688108575000, \"dataSource\": \"DefaultDataSource\", \"rdmVersion\": 1, \"description\": \"默认租户\", \"disableFlag\": false, \"rdmDeleteFlag\": 0, \"securityLevel\": \"internal\", \"lastUpdateTime\": 1688108575000, \"rdmExtensionType\": \"Tenant\"}, \"creator\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"extAttrs\": [{\"name\": \"ExtString\", \"type\": \"STRING\", \"value\": \"0123\"}, {\"name\": \"ExtDouble\", \"type\": \"DECIMAL\"}], \"modifier\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"className\": \"ExtDataModel\", \"createTime\": 1693367976851, \"extAttrMap\": {}, \"rdmVersion\": 1, \"rdmDeleteFlag\": 0, \"lastUpdateTime\": 1693367976851, \"rdmExtensionType\": \"ExtDataModel\"}", "task_no": 1, "task_status": "success" }, { "result": "{\"id\": 535837830857887744, \"tenant\": {\"id\": -1, \"code\": \"basicTenant\", \"name\": \"basicTenant\", \"creator\": \"xdmAdmin\", \"modifier\": \"xdmAdmin\", \"className\": \"Tenant\", \"createTime\": 1688108575000, \"dataSource\": \"DefaultDataSource\", \"rdmVersion\": 1, \"description\": \"默认租户\", \"disableFlag\": false, \"rdmDeleteFlag\": 0, \"securityLevel\": \"internal\", \"lastUpdateTime\": 1688108575000, \"rdmExtensionType\": \"Tenant\"}, \"creator\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"extAttrs\": [{\"name\": \"ExtString\", \"type\": \"STRING\", \"value\": \"1234056789\"}, {\"name\": \"ExtDouble\", \"type\": \"DECIMAL\"}], \"modifier\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"className\": \"ExtDataModel\", \"createTime\": 1692774494000, \"extAttrMap\": {}, \"rdmVersion\": 38, \"rdmDeleteFlag\": 0, \"lastUpdateTime\": 1693367978040, \"rdmExtensionType\": \"ExtDataModel\"}", "task_no": 2, "task_status": "success" } ], "task_count": 2 } ], "errors": [] }

响应参数 同步提交 表4 响应Body参数 参数 参数类型 描述 result String 调用是否成功。 SUCCESS：成功 FAIL：失败 data List of data 调用的返回结果。 errors List 异常信息列表。 表5 data 参数 参数类型 描述 data.id Long 事务型任务ID。 data.status String 事务型任务是否提交成功。步骤2：执行iDME原子接口执行的任一原子接口若执行失败，均表示事务型任务提交失败。 success：成功 fail：失败 data.tasks List of task 事务型任务下的原子接口列表。 表6 tasks 参数 参数类型 描述 data.tasks.result String 原子接口的执行详情。 data.tasks.task_no Integer 原子接口的执行序号。 data.tasks.task_status String 原子接口的执行状态。 success：成功 fail：失败 异步提交 表7 响应Body参数 参数 参数类型 描述 result String 调用是否成功。 SUCCESS：成功 FAIL：失败 data List 调用的返回结果，默认为空。 errors List 异常信息列表。

响应示例 同步提交 { "result": "SUCCESS", "data": [ { "id": 538322343718555649, "status": "success", "tasks": [ { "result": "{\"id\": 538327077254860800, \"tenant\": {\"id\": -1, \"code\": \"basicTenant\", \"name\": \"basicTenant\", \"creator\": \"xdmAdmin\", \"modifier\": \"xdmAdmin\", \"className\": \"Tenant\", \"createTime\": 1688108575000, \"dataSource\": \"DefaultDataSource\", \"rdmVersion\": 1, \"description\": \"默认租户\", \"disableFlag\": false, \"rdmDeleteFlag\": 0, \"securityLevel\": \"internal\", \"lastUpdateTime\": 1688108575000, \"rdmExtensionType\": \"Tenant\"}, \"creator\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"extAttrs\": [{\"name\": \"ExtString\", \"type\": \"STRING\", \"value\": \"0123\"}, {\"name\": \"ExtDouble\", \"type\": \"DECIMAL\"}], \"modifier\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"className\": \"ExtDataModel\", \"createTime\": 1693367976851, \"extAttrMap\": {}, \"rdmVersion\": 1, \"rdmDeleteFlag\": 0, \"lastUpdateTime\": 1693367976851, \"rdmExtensionType\": \"ExtDataModel\"}", "task_no": 1, "task_status": "success" }, { "result": "{\"id\": 535837830857887744, \"tenant\": {\"id\": -1, \"code\": \"basicTenant\", \"name\": \"basicTenant\", \"creator\": \"xdmAdmin\", \"modifier\": \"xdmAdmin\", \"className\": \"Tenant\", \"createTime\": 1688108575000, \"dataSource\": \"DefaultDataSource\", \"rdmVersion\": 1, \"description\": \"默认租户\", \"disableFlag\": false, \"rdmDeleteFlag\": 0, \"securityLevel\": \"internal\", \"lastUpdateTime\": 1688108575000, \"rdmExtensionType\": \"Tenant\"}, \"creator\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"extAttrs\": [{\"name\": \"ExtString\", \"type\": \"STRING\", \"value\": \"1234056789\"}, {\"name\": \"ExtDouble\", \"type\": \"DECIMAL\"}], \"modifier\": \"XDM_Developer 93172bbfd0f64437956d4c9de9345386\", \"className\": \"ExtDataModel\", \"createTime\": 1692774494000, \"extAttrMap\": {}, \"rdmVersion\": 38, \"rdmDeleteFlag\": 0, \"lastUpdateTime\": 1693367978040, \"rdmExtensionType\": \"ExtDataModel\"}", "task_no": 2, "task_status": "success" } ], "task_count": 2 } ], "errors": [] } 异步提交 { "result": "SUCCESS", "data": [], "errors": [] }

请求示例 同步提交 PUT https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v1/transaction-apis/transactions/538322343718555649 X-Auth-Token: ABCDEFJ.... 异步提交 v1版本请求示例： PUT https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v1/transaction-apis/transactions/async/538322343718555649 X-Auth-Token: ABCDEFJ.... v2版本请求示例： PUT https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v2/transaction-apis/transactions/async/538322343718555650?api_count=2 X-Auth-Token: ABCDEFJ....

请求示例 创建一个执行原子接口数量为2的事务型任务。 v1版本请求示例： POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v1/transaction-apis/transactions?api-count=2 X-Auth-Token: ABCDEFJ.... v2版本请求示例： POST https://dme.cn-north-4.huaweicloud.com/rdm_fce01234567d41828cf3473b07fa7ae2_app/services/rdm/basic/api/v2/transaction-apis/transactions X-Auth-Token: ABCDEFJ....

响应示例 v1版本响应示例： { "result": "SUCCESS", "data": [ { "transactionId": 538322343718555649, "taskNo": 0, "taskCount": 2 } ], "errors": [] } v2版本响应示例： { "result": "SUCCESS", "data": [ { "transactionId": 538322343718555650, "taskNo": 0 } ], "errors": [] }

响应参数 表3 响应Body参数 参数 参数类型 描述 result String 调用是否成功。 SUCCESS：成功 FAIL：失败 data List of data 事务型任务数据。 errors List 异常信息列表。 表4 data 参数 参数类型 描述 data.transactionId Long 事务型任务ID。 data.taskNo Integer 原子接口的执行序号，默认为0。 data.taskCount Integer 原子接口的数量。仅v1版本接口会返回此参数信息。

软件升级流程 软件（Software）一般分为系统软件和应用软件，系统软件实现设备最基本的功能，比如编译工具、系统文件管理等；应用软件可以根据设备的特点，提供不同的功能，比如采集数据、数据分析处理等。 软件升级又称为SOTA（SoftWare Over The Air），是指用户可以通过OTA的方式支持对LWM2M协议的设备进行软件升级（基于MQTT协议的设备的软件升级能力即将上线，敬请期待）。软件升级遵循的协议为PCP协议，设备侧需要遵循PCP协议进行软件升级的适配开发，适配方法请参考设备侧适配。SOTA流程如下图所示： SOTA升级流程的详细说明： 1～2. 用户在设备管理服务的控制台上传软件包，并在控制台或者应用服务器上创建软件升级任务。 3. NB-IoT设备上报数据，平台感知设备上线，触发升级协商流程。 4～5. 物联网平台 向设备下发查询设备软件版本的命令，查询成功后，物联网平台根据升级的目标版本判断设备是否需要升级。 如果返回的软件版本信息与升级的目标版本信息相同，则升级流程结束，不做升级处理。 如果返回的软件版本信息与升级的目标版本信息不同，则继续进行下一步的升级处理。 6. 物联网平台向设备订阅软件升级的状态。 7～8. 物联网平台查询终端设备所在的无线信号覆盖情况，获取小区ID、RSRP（Reference Signal Received Power，参考信号接收功率）和SINR（Signal to Interference Plus Noise Ratio，信号干扰噪声比）信息。 查询成功：则根据如下方式计算可同时升级的并发数计算，并按照。 如下图所示，如果设备的RSRP强度和SINR强度均落在等级“0”中，则同时可以对该小区的50个相同信号覆盖区间的设备进行同时升级。 如果设备的RSRP强度和SINR强度分别落在等级“0”和“1”中，则以信号较弱的等级“1”为准，则只能同时对该小区的10个设备进行升级。 如果设备的RSRP强度和SINR强度分别落在等级“1”和“2”中，则以信号较弱的等级“2”为准，则只能同时对该小区的1个设备进行升级。 如果设备的RSRP强度和SINR强度不在该3个等级范围内，且均可以查询到，则按照信号最弱覆盖等级“2”处理，则只能同时对1个设备进行升级。 如果用户在软件升级中发现同时进行升级的设备数较少，则可以联系当地运营商检查和优化设备所在小区的无线覆盖情况。 查询失败：则按照流程9进行处理。 9. 物联网平台继续下发查询小区ID信息的命令，获取终端设备所在的小区ID信息。 如果查询成功：物联网平台支持同时对该小区的10个相同情况的设备进行软件升级。 如果查询失败：则升级失败。 10～12. 物联网平台通知设备有新的软件包版本，设备启动软件包的下载。软件包的下载按照分片的方式进行下载，支持断点续传功能，通过软件包分片中携带的“versionCheckCode”确定是否属于同一个软件包。下载完成后，设备知会物联网平台软件包已下载完毕。 13～14. 物联网平台向设备下发升级的命令，终端设备进行升级操作，升级完成后终端设备向物联网平台反馈升级的结果。 15. 物联网平台向控制台/应用服务器通知升级的结果。

业务流程 NB-IoT设备场景 物联网平台向应用返回200 OK，携带命令状态为SENT。（如果设备不在线或者设备没收到指令则下发失败，命令状态为命令执行状态说明） 设备收到命令后返回ACK响应。 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为DELIVERED。消息样例如下： 设备执行命令后通过205 Content响应返回命令执行结果。 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为SUCCESSFUL。消息样例如下： 物联网平台将命令写入缓存队列，并上报200 OK，携带命令状态为PENDING。 设备上线或设备上报数据到平台。 物联网平台调用编解码插件对命令请求进行编码后，根据协议规范下发命令给设备。 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为SENT。 后续流程请参考“命令立即下发”的步骤2到步骤5。 集成Agent Lite SDK设备/原生MQTT设备场景 对于集成Agent Lite SDK设备/原生MQTT设备，物联网平台只支持直接下发模式，设备不在线时命令下发失败。 物联网平台向应用返回200 OK，携带命令状态为SENT。 设备收到命令后返回ACK响应。 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为DELIVERED。消息样例如下： 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为SUCCESSFUL。消息样例如下：

概述 设备的OTA软件升级是基于华为定义的PCP协议进行的，设备侧需根据PCP协议定义的交互流程进行适配开发。下面我们将结合物联网平台与设备的软件升级交互流程，介绍终端设备将如何基于PCP协议构建交互过程中的请求消息和应答消息，帮助您更好的根据PCP协议进行终端侧的软件升级功能开发。 下面我们先了解下PCP消息的结构，PCP协议的请求消息和应答消息都遵循相同的消息结构，主要由这几部分组成： PCP协议消息由：起始标识位、版本号、消息码、校验码、数据区长度和数据区组成，各字段的要求和描述如下表所示。

查询设备版本号 从设备的软件升级流程（本流程只描述物联网平台与设备基于PCP协议交互的流程，完整的软件升级流程请参考软件升级流程）可以看到，首先物联网平台向设备下发查询版本号信息，设备进行应答。 物联网平台发送消息 根据PCP消息结构的定义可以得出，物联网平台向设备下发查询版本号时，各消息字段的填写如下： 起始标识：固定为消息流的前2个字节，固定为FFFE。 版本号：数据类型为1个字节整数，且固定为1，即在消息流中为01。 消息码：数据类型为1个字节整数，查询设备版本的消息码为19，转换为十六进制为13。 校验码：数据类型为2个字节整数，先将校验码置为0000，然后将完整的消息码流进行CRC16的算法计算得到校验码，再将得到的校验码替换原消息中的0000。 数据区长度：数据类型为2个字节整数，代表数据区的消息长度，根据数据区的数据结构可以得出该条消息无数据区，即数据区长度为0000。 数据区：数据区代表要真正发送给设备的数据，根据查询版本信息的数据区定义，该条消息是没有实际要传送的数据的，即无需数据区字段。 因此将查询版本消息的码流组合起来得到：FFFE 01 13 0000 0000。前面的校验码时讲了，需要将组合后的消息码流进行CRC16算法（物联网平台提供了基于JAVA和C语言的CRC16算法代码样例，您可以直接使用）得到校验码4C9A，然后将该校验码替换原码流中的0000后得到FFFE01134C9A0000，该消息码流即为物联网平台发送给设备的查询版本信息的消息码流。 设备返回的应答消息 设备收到物联网平台要查询设备的软件版本号消息，设备要向物联网平台反馈查询的结果，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为13。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为17个字节，转换为十六进制为：0011。 数据区：根据数据区的定义可知，处理成功的结果码为00，版本号信息假设为V0.9，将V0.9进行ASCII转码得到56302E39，由于版本号的数据类型为BYTE[16]，即16个字节，当前只有4个字节，因此需要在版本号数据后面补0，得到56302E39000000000000000000000000。因此，数据区合并后为0056302E39000000000000000000000000。 将查询版本信息的消息流组合起来得到：FFFE 01 13 0000 0011 0056302E39000000000000000000000000。前面讲到，还要将消息流进行CRC16算法计算得到校验码为8DE3。因此，物联网平台向设备查询版本号信息，设备向平台返回的消息流为FFFE01138DE300110056302E39000000000000000000000000。

下载新版本软件包通知 根据PCP协议约定的交互流程，查询完版本号后，物联网平台下发指令让设备下载新版本的软件包。 物联网平台发送消息 根据PCP消息结构的定义可以得出，物联网平台向设备下发下载新版本软件包通知时，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：此处为新版本通知，查询消息码表可以知道新版本通知为20，转换为十六进制为14。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的消息字段可以得出，数据区长度为22个字节，转换为十六进制为：0016。 数据区：根据数据区的定义可知。 目标版本号：由16个字节组成，假设升级的目标版本号为v1.0版本，转换为十六进制并在后面14个字节补充0后得到：56312E30000000000000000000000000。 升级包分片大小：由2个字节组成，升级包分片大小由“deviceShard”字段定义，假设为500byte，转换为十六进制后为：01F4。 升级包分片总数：由2个字节组成，由软件包大小除以每个分片的大小并向上取整获得。假设软件包大小为500byte，则分片数量为1，转换为十六进制后为：0001。 检验码：由2个字节组成，由“versionCheckCode”字段定义，假设为1234。 将下载新版本软件包通知的消息流组合起来得到：FFFE 01 14 0000 0016 56312E30000000000000000000000000 01F4 0001 0000。前面说了，还要将消息流进行CRC16算法计算得到校验码为02F7。因此，物联网平台向设备通知下载新版本软件包的信息，物联网平台向设备发送的消息流为FFFE011402F7001656312E3000000000000000000000000001F400011234。 设备返回的应答消息 设备收到下载新版本软件包通知后，设备向物联网平台返回应答消息，是否允许设备进行升级，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为14。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为1个字节，转换为十六进制为：0001。 数据区：设备根据自身的情况对平台下发的新版本通知进行响应，本示例以设备应答“允许升级”为例进行介绍，得出数据区为：00。其它应答消息请根据应答消息字段进行适配。 将设备给物联网平台的应答消息流组合起来得到：FFFE 01 14 0000 0001 00。前面说了，还要将消息流进行CRC16算法计算得到校验码为D768。因此，设备向平台返回的应答消息流为FFFE0114D768000100。

上报下载结果 根据PCP协议约定的交互流程，设备接收完所有分片数据并组装完软件包后，需要向物联网平台上报软件包的下载结果。 设备发送的请求消息 根据PCP消息结构的定义可以得出，设备向物联网平台发送的上报软件包升级结果消息，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为16。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为1个字节，转换为十六进制为：0001。 数据区：上报软件包的下载结果，比如下载成功，设备侧上报00。 设备向物联网平台发送请求软件包分片的第一条消息为：FFFE 01 16 0000 0001 00（CRC16校验前），经CRC16计算得到校验码为：850E。则替换校验码后设备发送的第一条请求分片消息为：FFFE0116850E000100。 设备上报的软件包下载结果，可根据以上规则自行进行适配，此处就不再展开。 物联网平台的应答消息 物联网平台收到设备上报的软件包下载结果后，将会向设备返回应答消息，各个消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：16。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，处理失败返回80。本示例以返回00处理成功为例进行说明。 物联网平台向设备应答的消息为：FFFE 01 16 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：850E。则替换校验码后设备发送的第一条请求分片消息为：FFFE0116850E000100。

下载升级包 根据PCP协议约定的交互流程，物联网平台通知设备有新的软件版本时，设备向物联网平台请求下载软件包，按照分片的序号进行下载。 设备发送的请求消息 根据PCP消息结构的定义可以得出，设备向物联网平台发送的请求软件包分片的第一条消息，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：查询消息码表可知请求升级包的消息码为21，转换为十六进制为：15。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为18个字节，转换为十六进制为：0012。 数据区：目标版本号为平台下发的新版本通知版本号，即v1.0，转换为十六进制为56312E30000000000000000000000000，分片序号为第0个分片，即0000。 设备向物联网平台发送请求软件包分片的第一条消息为：FFFE 01 15 0000 0012 56312E30000000000000000000000000 0000（CRC16校验前），经CRC16计算得到校验码为：5618。则替换校验码后设备发送的第一条请求分片消息为：FFFE01155618001256312E300000000000000000000000000000。 其它分片请求的消息流只需要替换分片序号后，重新计算并替换CRC16校验码即可，此处就不再展开。 物联网平台的应答消息 物联网平台收到设备的请求软件包分片消息后，将会给设备下发分片的数据。物联网平台向设备响应的第一条请求分片的消息，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：15。 校验码：CRC16计算前先用0000替代。 数据区：先讲数据区再讲数据区长度。结果码：00，分片序号：第0个分片：0000，分片数据：跟软件包定义的内容有关，我们假设软件包内容为HELLO, IoT SOTA!，经ASCII码转换为十六进制为：48454C4C4F2C20496F5420534F544121，共16字节。由于制作软件升级版本包中的“deviceShard”字段定义分片大小为500byte，即最大长度为500字节。这种情况下，无需在数据的后面补充0。 数据区长度：根据数据区的字段定义得出该数据长度为19，转换为十六进制为：0013。 设备向物联网平台发送请求软件包分片的第一条消息为：FFFE 01 15 0000 0013 00 0000 48454C4C4F2C20496F5420534F544121（CRC16校验前），经CRC16计算得到校验码为：E107。则替换校验码后设备发送的第一条请求分片消息为：FFFE0115E107001300000048454C4C4F2C20496F5420534F544121。 其它分片请求的消息流只需要替换分片序号和分片数据后，重新计算并替换CRC16校验码即可，此处就不再展开。

执行软件升级 根据PCP协议约定的交互流程，物联网平台收到设备发送的软件包下载结果通知后，需要通知设备进行升级操作。 物联网平台发送的请求消息 根据PCP消息结构的定义可以得出，物联网平台向设备发送执行软件升级消息，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为17。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出无数据区，即为0字节，转换为十六进制为：0000。 数据区：无数据区，无需携带该字段。 物联网平台向设备下发的执行软件升级的消息为：FFFE 01 17 0000 0000（CRC16校验前），经CRC16计算得到校验码为：CF90。则替换校验码后物联网平台向设备发送的消息为：FFFE0117CF900000。 设备发送的应答消息 设备收到物联网平台下发的执行升级消息后，将对收到消息后的执行动作进行应答，各消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：17。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，其它处理结果请参考数据区定义。本示例以返回00处理成功为例进行说明。 设备向物联网平台应答的消息为：FFFE 01 17 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：B725。则替换校验码后设备返回的响应消息为：FFFE0117B725000100 。

上报升级结果 根据PCP协议约定的交互流程，设备在执行完软件升级后，将会向物联网平台上报升级的结果。 设备发送的请求消息 根据PCP消息结构的定义可以得出，物联网平台向设备发送执行软件升级消息，各个消息字段的填写如下： 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致，为18。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段的数据类型得出数据区长度为17字节，转换为十六进制为：0011。 数据区：结果码，以上报升级成功为例，结果码为00。当前版本号：升级完成后的版本号，与物联网平台下发的软件版本一致，即v1.0，转换为十六进制为：56312E30000000000000000000000000。 物联网平台向设备下发的执行软件升级的消息为：FFFE 01 18 0000 0011 0056312E30000000000000000000000000（CRC16校验前），经CRC16计算得到校验码为：C7D2。则替换校验码后设备发送的消息上报升级结果码流为：FFFE0118C7D200110056312E30000000000000000000000000。 物联网平台发送的应答消息 物联网平台收到设备上报的升级结果消息后，将对设备进行应答，各个消息字段的填写如下。 起始标识固定为：FFFE。 版本号固定为：01。 消息码：与请求的消息码一致：18。 校验码：CRC16计算前先用0000替代。 数据区长度：根据数据区的字段定义得出该数据长度为1个字节，转换为十六进制为：0001。 数据区：处理成功，则返回00，升级任务不存在80。本示例以返回00处理成功为例进行说明。 设备向物联网平台应答的消息为：FFFE 01 18 0000 0001 00 （CRC16校验前），经CRC16计算得到校验码为：AFA1。则替换校验码后设备返回的响应消息为：FFFE0118AFA1000100 。 至此，设备的软件升级功能适配就完成了，赶紧动手试一试吧。

数据转发方案对比 在许多场景中，您需要将设备上报给物联网平台的数据进行加工处理或用于业务应用。使用物联网平台提供的订阅推送功能和数据转发功能，均可实现设备数据的转发。 数据转发：提供初级的数据过滤能力。支持对设备数据进行过滤，然后再转发到其他华为云服务。 订阅推送：第三方应用可在物联网平台订阅相关业务数据，当业务信息发生变化时（如设备注册、设备数据上报、设备状态变更等），平台会向第三方应用发送通知消息，通知其具体的变化信息。可快速地获取设备消息，无数据过滤能力，功能较为单一，但是简单易用且高效。 数据转发方案 适用场景 优缺点 数据转发 设备上报数据上云。 复杂场景。 优点： 支持将数据转发至其他华为云服务产品。 支持对数据进行条件过滤。 缺点： 只能转发设备上报数据，不支持设备注册、设备状态变更等数据的转发。 订阅推送 设备数据推送至第三方应用。 单纯的接收设备数据的场景。 优点： 支持将设备注册、设备数据上报、设备状态变更等多种数据推送至第三方应用。 缺点： 缺少过滤能力。 第三方应用需要自实现对推送数据的存储、分析等操作，无法使用其他华为云服务。 物联网平台默认只提供较弱的Http推送能力，高于10TPS的推送建议使用数据转发规则。

查看应用详情 应用可以理解为在物联网平台中为用户的业务划分一个项目空间，园区物联网平台默认就创建了应用。当用户在开发中心、线下环境里完成应用服务器侧的开发、物联网平台侧的开发以及设备侧的开发后，就需要将开发完的应用服务器与真实设备接入到这个项目空间中，实现设备的数据采集和设备管理。 登录园区物联网平台控制台，选择“应用配置详情”，即可查看应用信息。 参数类型 参数说明 基本 可查看应用的基本信息，包括应用名称、应用ID、创建时间，应用ID在应用服务器接入物联网平台时使用。 安全 可单击“重置密钥”，重置后旧密钥自动失效，应用服务器需要更新为新的密钥才能重新接入物联网平台。 单击“编辑”，可打开或者关闭消息跟踪数据授权开关。 打开授权，表示平台管理员在辅助用户进行设备的故障定位时，可以跟踪设备上报的业务数据，便于快速解决问题。授权打开的状态下需要设置“授权时效”，可设置“指定时间”或者“永久有效”。为了保证用户的数据权益，物联网平台运维管理员跟踪的设备数据保留时间不超过3天。 关闭授权，表示平台管理员在辅助用户进行设备的故障定位时，不能跟踪设备上报的业务数据，可能导致没有足够的信息，将会降低问题定位效率，建议您授权给平台管理员进行业务数据的跟踪。 推送协议 推送协议是由应用服务器在订阅物联网平台的设备信息时设置的传输协议来确定的。应用服务器设置的订阅数据推送的传输通道为HTTP时，用户可以设置采用加密的HTTPS协议或者非加密的HTTP协议进行传输数据。如果采用HTTPS协议，需要上传CA证书，证书的上传可参考CA证书加载方法。 说明： 如果采用HTTPS协议，应用服务器取消了订阅，则绑定的证书会自动解绑，重新订阅后，请重新上传CA证书。 HTTP/HTTPS订阅推送服务 园区物联网平台支持查看应用的北向推送配置消息以及回调地址状态记录。在180s周期内，园区物联网平台向回调地址推送消息连续失败数达到10次，回调地址就会被自动设置为无效地址。平台会定期检测该地址是否恢复，检测到恢复则设置该回调地址状态为有效。 MQS订阅推送服务 园区物联网平台支持将设备上报的数据通过消息队列服务MQS推送给华为智慧园区沃土数字平台进行数据分析处理，MQS作为华为IT服务提供的一个第三方组件，需要提前配置园区物联网平台与MQS的对接数据。单击“添加”，在弹出的对话框中填写相关参数。 iPaas地址：MQS Namesrv的地址信息，格式为“IP:端口”，如“10.10.11.11:8965”。 用户名：访问MQS的用户名信息。 密钥：访问MQS的用户名密码信息（iPaas地址，用户名和密钥请向MQS服务管理员获取。） 传输是否加密：是否对IoT平台发送给MQS的消息进行加密。建议勾选“加密”。 Topic：Topic名称，如To_Bigdata。不同的Topic用于处理不同的消息类型，目前只支持设置1个Topic，表示所有信息均发送到同一个Topic处理。请向MQS服务管理员获取。 ROMA订阅推送服务 园区物联网平台支持与华为云的企业集成平台ROMA服务进行对接，用于 设备接入服务 将设备上报的数据推送给ROMA。单击“添加”，在弹出的对话框中填写相关参数。 ROMA地址：在华为云中按照购买实例购买ROMA云服务，在购买中，需要选择“公网访问”，设置“弹性IP”。购买完成后，可以在ROMA管理控制台的“实例信息”中，查看“公网访问”中的“弹性IP地址”，端口固定为9095，多个地址之间使用英文逗号分隔。例如：139.128.xx.xx:9095,139.129.xx.xx:9095 账户名：在ROMA的消息集成MQS中创建的用户，详情可参考用户管理。 密钥：在ROMA的消息集成MQS中创建用户时设置的密码，详情可参考用户管理。 SSL证书：IoT平台与ROMA通信的传输加密证书，由ROMA提供，可以在SASL方式连接MQS中获取。 证书密钥：SSL证书对应的密钥，由ROMA提供，可以在SASL方式连接MQS中获取。 Topic：用于指定IoT平台向ROMA推送消息的Topic名称，需提前按照Topic创建进行定义。 说明： 平台与ROMA服务对接完成后，还需通过管理规则功能，配置设备的数据转发规则，将数据转发至ROMA服务。 CA证书加载方法： 单击“证书管理”，在弹出的对话框中单击“添加”按钮。 按照表格填写相关信息后，单击“确定”完成证书的加载。 父主题： Console操作