华为云用户手册

响应消息 响应参数说明请参见下表： 参数 是否必选 类型 取值范围 说明 resultCode M String 6 调用结果码。 000000：表示资源同步开通 000004：表示资源异步开通 具体请参见《调用结果码说明》。 resultMsg O String 255 调用结果描述。 请及时关注商家信息中客服邮箱以及云商店账号绑定的邮箱的通知，收到调用失败通知邮件及时处理接口异常。 云商店会对接口异常的情况做监控，如商品频繁出现因接口异常的情况，云商店将对该商品做下架处理。 响应消息示例： { "resultCode":"000000", "resultMsg":"success." }

Sdk::CheckNewVersions 场景描述 升级信息查询函数，由工业软件调用。工业软件查询升级信息时，调用此函数，向ISCDesk查询是否存在升级版本。查询成功后会触发“EVENT_UPGRADENOTICE”事件，将升级信息告知工业软件。 升级信息样例如下： {"operate":"UpgradeNotice","params":{"available":"false"},"comeBackParams":{}} “available”字段表示是否存在可升级版本，字段值为“true”表示存在可升级版本；字段值为“false”表示不存在可升级版本。 当存在可升级版本时，ISCDesk会弹窗提示是否升级。若选择升级，则触发“EVENT_UPDATE”升级事件，将升级事件连同升级信息一同告知工业软件，工业软件可自行决定是否退出升级或继续使用。 升级信息（强制升级）样例如下： {"operate":"Update","params":{"fromForceWin":"true"},"comeBackParams":{}} “fromForceWin”字段表示升级类别，当前包含非强制升级和强制升级两种类别。 “fromForceWin”字段值为“false”，表示非强制升级。工业软件可选择是否升级并通知ISCDesk，如果工业软件选择升级，则ISCDesk会在工业软件关闭后进行升级。 “fromForceWin”字段值为“true”，表示强制升级。工业软件无法选择是否升级，ISCDesk会在工业软件关闭后进行升级。 当工业软件选择升级或存在强制升级信息时，建议工业软件执行保存并退出操作。 涉及接口 Sdk::CheckNewVersions 调用示例 ResultStatus CheckNewVersions(); 父主题： 升级相关

请求方法：POST 接口URL：生产地址+固定子路径，其中固定子路径为/produceAPI/singleOrgSync； 接口示例：生产地址为https://example.isv.com，则接口URL为https://example.isv.com/produceAPI/singleOrgSync Headers请参数 参数 必选 参数类型 描述 authToken M String(255) 签名信息，请参考auth Token取值说明。 BODY请求参数 参数 必选 参数类型 描述 instanceId M String(64) 说明： 卖家申请应用凭证的时候传空，买家必传。 tenantId M String(64) 租户ID，与租户的同步信息保持一致 orgCode M String(64) 部门代码 租户自定义，租户内唯一 orgName M Vachar(128) 部门名称 所在层级唯一，允许租户更新名称 parentCode O String(64) 上级部门的orgCode，如果是顶层部门，这个值为空，其他场景不能为空，允许租户更新当前部门归属的上层部门 flag M Integer(2) 0-删除 1-新增，2-修改 testFlag M Integer(2) 0-生产正式数据 1-调测数据 timeStamp M String 默认时区东8区，时间戳,时间格式：20220420114117642 响应参数 参数 必选 参数类型 描述 resultCode M String(6) 响应码,具体请参见调用结果码说明。 resultMsg O String(255) 响应信息 示例： POST https://example.isv.com/produceAPI/singleOrgSync Connection: keep-alive Content-Type: application/json authToken: "stbNYlu**************2Ubt271qDr6WDAVLtLRb” Host: example.isv.com User-Agent: Apache-HttpClient/4.5.3 (Java/1.8.0_191) { "instanceId": "hua********23456", "instanceId": "hua********23456", "tenantId": "68cbc********0d92f36422fa0e", "orgCode": "10000", "orgName": "开发部", "parentCode": "", "flag": 1, "testFlag": 0, "timeStamp": "20220413093539534" , } HTTP/1.1 200 OK Body-Sign: sign_type="HMAC-SHA256", signature= "xxxxxxxxxx" Content-Type: application/json { " resultCode": "000000", " resultMsg": "Success" } HTTP Body签名: Body-Sign: sign_type="HMAC-SHA256", signature= "xxxxxxxxxxxxx" ，详情参考《HTTP Body签名》。

接口说明 管理员被授权管理某企业后，在买家中心登录，对管理的企业执行新建、编辑、删除部门操作时，云商店调用该接口，请求商家同步该企业的组织增量变更；商家接口需要执行增量组织信息同步，保存信息，并返回通知云商店。 商家的服务器在处理接口请求时，需要做好幂等性处理。 对于同一个实例，相同的租户，相同的orgCode，要支持多次请求新增，或者删除，多次新增不应产生新的数据，且需要返回成功，如果是删除，多次删除也需要返回成功，不能因已删除返回失败，删除时不需要校验(新购商品)接口产生的实例是否存在。

公共错误码 表1 错误码 http状态码 error_code error_msg 描述 200 CBC.0000 Success 成功 403 CBC.0150 Illegal operation 鉴权失败 400 CBC.0101 Invalid parameter 请求参数不合法 500 CBC.0999 internal error 其它服务内部错误 200 91381033 License resource invalid License资源不可用 200 91381034 license apply invalid 用户License申请不合法 200 91381035 license period has no remain amount License资源周期没余额了 200 91381036 inner error 内部错误 200 91381037 Invalid license format. License格式不正确 200 91381038 License apply has been denied. License申请已拒绝 200 91380150 Role permission denied 没有权限执行该操作，角色权限错误 父主题： 云商店开放接口指南

请求消息 请求参数说明请参见下表： 请求方法：POST 参数 是否必选 类型 取值范围 说明 activity M String 20 接口请求标识，用于区分接口请求场景。 续费场景取值：refreshInstance scene M String 64 场景，触发实例变更的场景： TRIAL_TO_FORMAL：试用转正 RENEWAL：续费 UNSUBSCRIBE_RENEWAL_PERIOD：退续费 orderId M String 64 云商店订单ID， 试用转正时传递转正订单ID 续费时传递当前续费订单ID 退续费时传递需要退订的续费订单ID orderLineId M String 64 云商店订单行ID。 instanceId M String 64 实例ID。 productId O String 64 产品标识，租户续费或转正产品实例时，如果订购周期类型发生变化，会传入变化后的产品类型对应的productId。 expireTime M String 20 过期时间。 格式：yyyyMMddHHmmss testFlag O String 2 是否为调试请求。 1：调试请求 0：非调试请求 默认取值为“0”。 请求消息示例： curl -X POST 'https://www.isvwebsite.com/saasproduce?signature=3F6E6652B7BE26B27ABFC3D112***********20174FE8DE062×tamp=1680509496350&nonce=8BF8496A350E37BDB0E8956D39D433ED417C3FC9459DCFFE7F03BFBF69B12085' -H 'Accept:application/json' -H 'Content-Type:application/json;charset=utf8' -d'{"activity":"refreshInstance","expireTime":"20221124023618256","instanceId":"10e758d0-31ad********03469a10e","orderId":"CS2211*******VS","orderLineId":"CS221******000001","productId":"OFFI461******240","scene":"RENEWAL","testFlag":"0"}'

接口说明 按周期售卖的商品，用户试用转正、续费、退续费后，云商店调用该接口，更新实例的到期日期。 客户商品转正、续费下单或退订续费周期后，云商店将调用该接口请求商家执行业务变更，商家接口需要执行将到期日进行更新，并返回通知云商店。 商家需要保障更新实例接口通畅，如调用失败，将可能导致用户的业务被释放的风险。 请及时关注商家信息中客服邮箱以及云商店账号绑定的邮箱的通知，收到调用失败通知邮件及时处理接口异常。 云商店会对接口异常的情况做监控，如商品频繁出现因接口异常的情况，云商店将对该商品做下架处理。 商品更新实例流程如下图所示：

请求消息 请求参数 请求方法：GET 参数 是否必选 参数类型 取值范围 描述 orderId M String 64 云商店订单ID orderLineId O String 64 云商店订单行ID 需要对mkt.myhuaweicloud.com HTTPS证书进行强校验，不能忽略证书校验，从而保证调用的是真实而非伪造的云商店服务。 请求示例 GET /api/mkp-openapi-public/global/v1/order/query?orderId=CS2207261447AUY4H&orderLineId=CS2207261447AUY4H-000001 Host: Host Server Content-Type: application/json charset=UTF-8 X-Sdk-Date: request time Authorization: authorization

响应消息 响应参数说明请参见下表： 参数 是否必选 类型 最大字符长度 说明 resultCode M String 6 调用结果码。 具体请参见调用结果码说明。 resultMsg O String 255 调用结果描述。 商家的服务器在处理接口请求时，需要做好幂等性处理。 云商店服务有可能重发请求，针对同一orderId，商家的服务器不应该重复做实例资源升级处理，返回成功响应即可。 响应消息示例： { "resultCode":"000000", "resultMsg":"success." }

请求方法：GET 参数 是否必选 类型 最大字符长度 说明 authToken M String 50 安全校验令牌。 取值请参见authToken取值说明。 activity M String 20 接口请求标识，用于区分接口请求场景。 升级场景取值：upgrade instanceId M String 64 实例ID。 说明： 升级时，instanceId不变。 orderId M String 64 升级后的新订单ID。 说明： 升级操作会产生新的订单，与新购时订单ID不一致，请通过instance Id做资源识别。 skuCode M String 64 升级后产品规格标识。 说明： 对于自定义属性模板规格，如果租户升级时选择了其他属性值，instanceId对应的规格会发生变化，因此skuCode会变化； 如果仅扩容（调整增加线性属性值大小，例如：从当前的10用户增加到20用户），skuCode不变。 productId M String 64 升级后产品ID。 如果skuCode变化，productId也会发生变化； 如果仅扩容，productId不变。 timeStamp M String 20 请求发起时的时间戳，取UTC时间。 格式：yyyyMMddHHmmssSSS amount O Integer 4 数量类型的商品定价属性。非必填。 属性名称：数量（支持商家自定义名称） 单位：个（次） 说明： 对于包周期或一次性计费的SaaS商品，租户下单购买包含“数量”线性属性的规格时，会填写及调整购买的个数或次数。 例如：30个用户 diskSize O Integer 4 数量类型的商品定价属性。非必填。 属性名称：硬盘大小（支持商家自定义名称） 单位：GB 说明： 对于包周期或一次性计费的SaaS商品，租户下单购买包含“硬盘大小”线性属性的规格时，会填写及调整购买多少GB。 例如：100GB bandWidth O Integer 4 数量类型的商品定价属性。非必填。 属性名称：带宽（支持商家自定义名称） 单位：Mbps 说明： 对于包周期或一次性计费的SaaS商品，租户下单购买包含“带宽”线性属性的规格时，会填写及调整购买多少Mbps。 例如：20Mbps testFlag O Integer 1 是否调测数据。 1：接口调测数据 不传参数：真实买家同步数据 请求消息示例： https://example.isv.com?activity=upgrade&amount=6456&instanceId=huaweitest123456&orderId=CS1906666688ABCDE&productId=00301-666688-0-0&saasExtendParams=W3sibmFtZSI6ImlkTnVtIiwidmFsdWUiOiIzNTIyNTU1NTU1NTU2NTYifSx7Im5hbWUiOiJ1c2VyTmFtZSIsInZhbHVlIjoiaHVhd2VpMTIzIn0seyJuYW1lIjoiY3VzdEVtYWlsIiwidmFsdWUiOiIxMjNAaHVhd2VpLmNvbSJ9XQ==&skuCode=d0abcd12-1234-5678-ab90-11ab012aaaa1&testFlag=1&timeStamp=20191216013757582&authToken=a3Bl+C93xv3ENgm40ngyYvQnYcTS/pgY5ugl20wtzGg=

响应消息 响应参数说明请参见下表： 参数 是否必选 类型 取值范围 参数说明 resultCode M String 6 调用结果码。 000000：表示资源同步开通 000004：表示资源异步开通 具体请参见《调用结果码说明》。 说明：如果创建实例耗时较长，建议返回0000004，云商店后续会通过查询实例信息接口查询实例开通结果 resultMsg O String 255 调用结果描述。 instanceId M String 64 实例ID 响应消息示例： { "resultCode":"000000", "resultMsg":"success." , "instanceId":"03pf80c2bae96vc49*********" }

接口说明 客户购买商品并付款成功，云商店将调用本接口通知商家创建实例。 商家需要返回此订单的唯一ID（instanceId）。建议此ID直接使用该订单首次请求时云商店传入的businessId，以确保instanceId的唯一性。 在正常购买场景中，请不要阻塞此接口，如果耗时较长，建议异步创建实例，可以先生成instanceId，然后立即返回。 获取订单信息，请参考《在线开通License接口示例代码》。 云商店服务有可能重发请求，针对同一订单号（orderId）和订单行（orderLineId），商家的服务器应当返回相同的instanceId，不应该创建新的License实例，返回之前成功创建的实例id即可。 创建实例流程如下图所示：

请求消息 请求参数说明请参见下表。云商店会结合商家创建上架的商品售卖模式来对应请求，商家也需要根据请求的信息来对应执行生产。 请求方式：POST 参数 是否必选 参数类型 最大字符长度 说明 activity M String 20 接口请求标识，用于区分接口请求场景。 新购场景取值：newInstance orderId M String 64 云商店订单ID。 orderLineId M String 64 云商店订单行ID。 businessId M String 64 云商店业务ID。 每一次请求，businessId皆不一致。 testFlag O String 2 是否为调试请求。 1：调试请求 0：非调试请求 默认取值为“0”。 请求消息示例： curl -X POST 'https://www.isvwebsite.com/saasproduce?signature=11C4CD6279191DE931DEF5C51531DFFA9D37969F4E356B**********8×tamp=1680508066618&nonce=50D83FDECAED6CCD8EF597F2A577950527928BA287D04E6036E92B2806FD17DA' -H 'Accept:application/json' -H 'Content-Type:application/json;charset=utf8' -d'{"activity":"newInstance","businessId":"87b947**********-69420d60e3c8","orderId":"CS221118******","orderLineId":"CS22111********-000001","testFlag":"0"}'

接口调用场景 创建实例：客户购买商品并付款成功。 云商店将调用创建实例接口通知商家根据订单号创建实例。 商家系统收到该请求信息，需调用云商店查询订单接口，获取本次订购的相关信息，执行新购对应动作。 更新实例：客户试用转正、续费、退续费。 云商店将调用更新实例接口，通知商家系统对相应资源变更过期时间，商家本地系统需执行相应动作，并将执行结果返回给云商店。 更新实例状态：用户资源实例因到期、违规等情况下会对用户的实例进行冻结，同时在用户续费后，或资源解除违规后会对用户的实例进行解锁。 云商店将调用更新实例状态接口，通知商家系统对相应资源执行冻结、解冻操作，并将执行结果返回给云商店。 用户订单到期后，有 15天的资源冻结期，冻结期内资源不可使用，但可以对此订单续费以解冻继续使用，故商家需对在线开通License商品设置15天的冻结期，并在冻结期内保留用户数据。 释放实例：用户释放购买产品的实例时（到期不续费、退订等场景）。 云商店将调用释放实例接口，通知商家系统对相应资源执行释放操作，并将执行结果返回云商店。

登录场景：accesstoken续期 用户登录获得的access_token有效期默认为2小时，refresh_token刷新令牌有效期默认为30天，在用户持续访问应用的情况下，服务端应提供access_token的续期功能。 续期功能内部调用时序图： 接口URL请参考联营能力开放接口的刷新Access Token，示例URL如下： {domain_name}/api/v1/oauth2/token Content-Type:application/x-www-form-urlencoded&client_id=NzZeWuiJa91dPSRdZQChMazIh13AW...&client_secret=******...&refresh_token=******...&grant_type=refresh_token 父主题： 企业提供独立的登录页面

响应参数 表2 状态码 状态码 描述 200 请求成功。 401 认证失败。 表3 响应Body参数 参数 参数类型 描述 id String 用户ID userName String 用户名 name String 姓名 email String 邮箱地址 mobile String 手机号 error String 错误类型。 error_description String 错误描述。 role String 角色 organizationName String 组织名称 userId String 用户id organizationCode String 组织编码 projectName String 租户名称 tenant String 租户id

请求参数 表1 请求Header 参数 是否必选 参数类型 描述 Accept 是 String 接收响应类型，值：application/json。 Authorization 是 String 认证凭据，值：Bearer {access_token}。 请求示例 GET {domain_name}/api/v1/oauth2/userinfo Authorization: Bearer ****** Accept: application/json

接入流程 SaaS类商品接入云商店的流程如下图所示： 流程说明如下： 申请入驻云商店，成为商家。 云商店运营人员审核公司的资质信息。 准备生产接口服务器，根据本接入指南开发生产接口。 在卖家中心调试生产接口，参考接口调试。 在卖家中心完成安全漏洞扫描，参考安全漏洞扫描操作指导及安全规范。 在卖家中心创建应用凭证，参考应用凭证申请。 在卖家中心申请测试账号。 SDK账密或WEB场景的界面登录。 验证登录成功。 加入联营计划，成为联营商家，参考联营认证及商品发布流程概览。 在卖家中心申请发布商品，参考联营商品上架。 云商店运营人员审批通过后，产品发布为联营商品。 在卖家中心自助管理生产接口通知消息。 联营SaaS类商品接入可参考《联营SaaS类商品接入视频指导》。 父主题： 联营SaaS类商品接入指南 V1.0

使用方法 华为云API符合RESTful API设计理论。 REST从资源的角度观察整个网络，分布在各处的资源由URI（Uniform Resource Identifier）确定，客户端的应用通过URL（Unified Resource Locator）获取资源。 URL的一般格式为：https://Endpoint/uri。 URL中的参数说明如表1所示。 表1 URL中的参数说明 参数 描述 Endpoint 云商店的Endpoint为“mkt.myhuaweicloud.com”和“mkt.myhuaweicloud.com”。 uri 资源路径，也即API访问路径。从具体接口的URI模块获取，例如“v1.0/{partner_id}/billing/bill-mgr/push-usage-data”。 其中，uri中的用户标识参数说明如下： 使用“partner_id”标识，表示该接口只能使用合作伙伴（ISV）自身的AK/SK或者Token调用。 华为云接口采用HTTP传输协议，有如下约束条件： 请求/响应报文使用JSON报文UTF-8字符集编码。 媒体类型表示为Application/json。 可选参数在消息体中可以不编码。 接口请求参数和响应参数中时间格式统一为UTC时间（包括时区），格式为yyyyMMdd'T'HHmmss'Z'。 其中，HH范围是0～23，mm和ss范围是0～59。 父主题： 接口使用方法

响应消息 响应参数说明请参见下表： 表2 响应参数表 参数 是否必选 类型 最大字符长度 说明 resultCode M String 6 调用结果码。 具体请参见调用结果码说明。 resultMsg O String 255 调用结果描述。 encryptType O String 3 敏感信息加密算法 1：AES256_CBC_PKCS5Padding（默认值） 2：AES128_CBC_PKCS5Padding 说明： 敏感信息加密算法是AES256_CBC_PKCS5Padding时返回值为1； 敏感信息加密算法是AES128_CBC_PKCS5Padding时返回值为2； info O InstanceInfo[] / 实例详情 InstanceInfo数据结构定义如下： 参数 是否必选 类型及范围 最大字符长度 参数说明 instanceId M String 64 实例id appInfo O AppInfo N/A 应用实例信息。 客户购买商品后，商家需要返回登录服务地址（网站地址）或免登地址供客户后续操作。 说明： SaaS商品必须向客户提供应用使用信息，包括使用地址、账号、密码等。 如可实现通过短信、邮件等其他方式发送使用信息，则接口中允许不响应；否则，必须在接口中返回应用实例信息。 如使用信息不仅包含使用地址及账号密码，可通过如下memo参数灵活返回其他使用信息或使用说明等。 appInfo数据结构定义请参见下表。 usageInfos O UsageInfo[] N/A 应用实例关联的用量信息，按需和按需套餐包实例需要返回，对应按需套餐包，需要分别返回套餐包关联的所有费用项的用量信息。 AppInfo数据结构定义如下： 参数 是否必选 类型及范围 最大字符长度 参数说明 frontEndUrl M String 512 前台地址。 客户购买商品后，可以访问的网站地址。 adminUrl O String 512 管理地址。 客户购买商品后，可以访问的管理后台地址。 userName O String 128 加密后的管理员账号。 客户购买商品后，访问商家管理后台的账号（一般为邮箱和手机号）。该值由16位iv加密向量和base编码后的用户名密文组成。 iv+base64(AES_CBC(accessKey,userName)) 需要使用Key值对账号做加密处理，加密算法以encryptType参数为准。代码示例请参见ISV Server对资源开通后的用户名和密码加密。 password O String 128 加密后的管理员初始密码。 客户购买商品后，访问商家管理后台的密码（一般由商家生成）。该值由16位iv加密向量和base编码后的密码密文组成。 iv+base64(AES_CBC(accessKey,pwd)) 需要使用Key值对密码做加密处理，加密算法以encryptType参数为准。代码示例请参见ISV Server对资源开通后的用户名和密码加密。 memo O String 1024 备注。 说明： 如果备注包含中文内容，请将中文转换成unicode编码，例如：“中文”可以转换成“\u4e2d\u6587”。 UsageInfo数据结构定义如下： 参数 是否必选 类型及范围 最大字符长度 参数说明 relatedInstanceId O String 64 关联的按需实例ID，当查询按需套餐包实例的用量数据时，还需要返回此用量对应的按需实例id，譬如，当前套餐包包含短信100条和彩信50条，则在查询此套餐包的用量扣减时需要返回两个UsageInfo信息，分别对应短信和彩信的用量信息，relatedInstanceId分别对应短信和彩信按需实例ID usageValue M Double(12,4) 20 使用量具体值，最多支持4位有效小数，对于按需实例，应该是一个总体的累积值，对于按需套餐包实例，应该是套餐包的已用用量信息 statisticalTime M String 20 使用量统计时间，取UTC时间。 格式：yyyyMMddHHmmssSSS dashboardUrl O String 512 用量详细查看看板地址。 客户购买按需或按需套餐包商品后，可以在这个平台查看具体的用量信息。 响应消息示例： { "resultCode" : "000000", "resultMsg" : "success.", "encryptType" : "1", "info" : [{ "instanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654", "appInfo" : { "frontEndUrl" : "https://www.***.com", "adminUrl" : "https://www.*****.com/admin", "userName" : "*****", "password" : "*****", "memo" : "hvave a test, 测试！" }, "usageInfo" : [{ "relatedInstanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654", "usageValue" : "0.12", "statisticalTime" : "20221101025113409", "dashboardUrl" : "https://www.baidu.com/dashboard" } ] }, { "instanceId" : "fe28e27e-1157-4105-8592-24cc9488db10", "appInfo" : { "frontEndUrl" : "https://www.***.com", "adminUrl" : "https://www.***.com/admin", "userName" : "*****", "password" : "*****", "memo" : "hvave a test, 测试！" }, "usageInfo" : [{ "relatedInstanceId" : "fe28e27e-1157-4105-8592-24cc9488db10", "usageValue" : "2042", "statisticalTime" : "20221101025113409", "dashboardUrl" : "https://www.baidu.com/dashboard" } ] }, { "instanceId" : "92df74e4-163e-4e0b-a206-d9800d33881b", "appInfo" : { "frontEndUrl" : "https://www.baidu.com", "adminUrl" : "https://www.baidu.com/admin", "userName" : "huawei", "password" : "huawei123456", "memo" : "hvave a test, 测试！" }, "usageInfo" : [{ "relatedInstanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654", "usageValue" : "3309", "statisticalTime" : "20221101025113409", "dashboardUrl" : "https://www.baidu.com/dashboard" }, { "relatedInstanceId" : "fe28e27e-1157-4105-8592-24cc9488db10", "usageValue" : "3309", "statisticalTime" : "20221101025113409", "dashboardUrl" : "https://www.baidu.com/dashboard" } ] } ] }

请求方法：GET 请求参数说明请参见下表： 表1 请求参数表 参数 是否必选 类型 最大字符长度 说明 authToken M String 50 安全校验令牌。 取值请参见authToken取值说明。 activity M String 20 接口请求标识，用于区分接口请求场景。 查询实例场景取值：queryInstance timeStamp M String 20 请求发起时的时间戳，取UTC时间。 格式：yyyyMMddHHmmssSSS instanceId M String 64 实例ID，支持批量，多个实例批量查询时用逗号分隔，单次最多支持100个实例查询。 testFlag O String 2 是否为调试请求。 1：调试请求 0：非调试业务 默认取值为“0”。 请求示例： https://example.isv.com?activity=queryInstance&instanceId=ebc28eb6-4606-4098-b4bd-c201c99a0654%2Cfe28e27e-1157-4105-8592-24cc9488db10%2C92df74e4-163e-4e0b-a206-d9800d33881b&testFlag=1&timeStamp=20230327065233980&authToken=Eh%2F3Ud%2BR1j3d%2FwOui5CAcvRipM8IuribvgkXfJAsTfE%3D

请求行 请求行以一个方法符号开头，以空格分开，后面跟着请求的URI和协议的版本，格式如下： Method Request-URI HTTP-Version CRLF Method：表示请求方法（所有方法全为大写），各个方法的解释如下： GET：请求获取Request-URI所标识的资源。 POST：在Request-URI所标识的资源后附加新的数据。 PUT：请求服务器存储一个资源，并用Request-URI作为其标识。 DELETE：请求服务器删除Request-URI所标识的资源。 Request-URI：是一个统一资源标识符。 可以在URI后面用‘?’和‘&’添加不同的查询条件组合。URI中“{}”中包含的内容为URI的参数，其中“?”之前的部分是路径参数，之后的部分是查询参数。HTTP-Version：表示请求的HTTP协议版本。 CRLF：表示回车和换行（除了作为结尾的CRLF外，不允许出现单独的CR或LF字符）。

状态行 状态行格式如下： HTTP-Version Status-Code Reason-Phrase CRLF HTTP-Version：表示服务器HTTP协议的版本号。 Status-Code：表示服务器发回的响应状态代码。 状态代码有三位数字组成，第一个数字定义了响应的类别，且有五种可能取值： 1xx：指示信息，表示请求已接收，继续处理。 2xx：成功，表示请求已被成功接收、理解、接受。 3xx：重定向，要完成请求必须进行更进一步的操作。 4xx：客户端错误，请求有语法错误或请求无法实现。 5xx：服务器端错误，服务器未能实现合法的请求。 Reason-Phrase：表示状态代码的文本描述。

License相关 在进行License验证时，需要收集用户设备指纹信息，包括MAC地址、硬盘序列号、主板序列号和CPU序列号。设备指纹最大长度限制为5K字节。 设备指纹字符串拼接时，各参数之间以“|”号分割，获取不到时就为空。获取到的MAC地址和硬盘序列号有多个时，以英文“,”号分隔。字符串拼接完成后，转换为大写。字符串拼接如下： string='${macAddr}|${diskId}|${boardId}|${cpuId}'.toUpperCase(); 设备指纹示例：04:7C:16:5E:E3:5D|001B_444A_488B_5CEC.||BFEBFBFF00090672 Sdk::GetLicenseFileRequest Sdk::GetLicenseStringRequest Sdk::LicenseVerifyNotify Sdk::TrialExpirationAndGetLicense 父主题： 管理在云

限定条件下载 下载对象时，可以指定一个或多个限定条件，满足限定条件时则进行下载，否则抛出异常，下载对象失败。 您可以使用的限定条件如下： 参数 作用 OBS iOS SDK对应方法 ifModifiedSince 如果对象在指定的时间后有修改，则返回对象内容，否则返回错误。 request.ifModifiedSince ifUnmodifiedSince 如果对象在指定的时间后没有修改，则返回对象内容，否则返回错误。 request.ifUnmodifiedSince ifETagMatch 如果对象的ETag值与该参数值相同，则返回对象内容，否则抛出异常。 request.ifETagMatch ifETagNoneMatch 如果对象的ETag值与该参数值不相同，则返回对象内容，否则抛出异常。 request.ifETagNoneMatch 对象的ETag值是指对象数据的MD5校验值。 如果限制条件不符合，则会返回错误preconditionFailed。 以下代码展示了如何进行限定条件下载： static OBSClient *client; NSString *endPoint = @"your-endpoint"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html char* ak_env = getenv("AccessKeyID"); char* sk_env = getenv("SecretAccessKey"); NSString *AK = [NSString stringWithUTF8String:ak_env]; NSString *SK = [NSString stringWithUTF8String:sk_env]; // 初始化身份验证 OBSStaticCredentialProvider *credentialProvider = [[OBSStaticCredentialProvider alloc] initWithAccessKey:AK secretKey:SK]; //初始化服务配置 OBSServiceConfiguration *conf = [[OBSServiceConfiguration alloc] initWithURLString:endPoint credentialProvider:credentialProvider]; // 初始化client client = [[OBSClient alloc] initWithConfiguration:conf]; // 流式下载 OBSGetObjectToDataRequest *request = [[OBSGetObjectToDataRequest alloc]initWithBucketName:@"bucketname" objectKey:@"objectname"]; // 限定条件 request.ifModifiedSince = [[OBSUtils getDateFormatterRFC1123]dateFromString:@"Mon, 18 Dec 2017 03:50:49 GMT"]; // Etag相等 request.ifETagMatch = @"123223"; // 下载进度 request.downloadProgressBlock = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) { NSLog(@"%0.1f%%",(float)(totalBytesWritten)*100/(float)totalBytesExpectedToWrite); }; // 下载的数据 __block NSMutableData *objectData = [NSMutableData new]; request.onReceiveDataBlock = ^(NSData *data) { [objectData appendData:data]; }; // 下载结果 [client getObject:request completionHandler:^(OBSGetObjectResponse *response, NSError *error){ NSLog(@"%@",response); }] ; 当使用OBSGetObjectToFileRequest时，可以设置background属性为YES进行后台下载。 父主题： 下载对象

修订记录 发布日期 修订记录 2024-04-30 第十次正式发布。 修改章节： SDK下载。 2020-04-21 第九次正式发布。 修改章节： 配置OBS客户端，新增配置请求连接数的相关说明。 2020-03-13 第八次正式发布。 修改章节： 使用临时URL进行授权访问，新增获取对象的示例代码。 2019-11-20 第七次正式发布。 调整以下章节的位置： 示例程序。 技术支持渠道。 2019-11-1 第六次正式发布 修改章节： 2.13-OBS客户端通用示例，新增以局部变量形式创建OBS客户端的相关说明。 3.2-创建OBS客户端，新增以自定义域名访问方式创建OBS客户端的使用说明。 5.5-设置对象属性，新增以任意字符串设置对象上传类型的相关内容。 7.3-列举对象，添加了列举根目录下所有文件夹的代码样例。 7.5-复制对象，完善复制对象时的属性重写相关代码样例。 2019-08-20 第五次正式发布 修改章节： 创建OBS客户端，新增并发场景下的使用说明。 文件上传，完善错误处理的判断方式。 设置对象属性，新增上传时设置文件类型的介绍。 2019-05-30 第四次正式发布 修改章节： OBS服务环境搭建，增加临时访问密钥相关内容。 创建OBS客户端，增加临时访问密钥相关代码样例。 2019-03-05 第三次正式发布 新增章节： API参考。 2018-10-31 第二次正式发布 新增章节： 追加上传。 修改章节： 管理桶访问权限，修改成自定义接口枚举值。 2018-5-31 第一次正式发布。

对象上传简介 在OBS中，用户操作的基本数据单元是对象。OBS iOS SDK提供了丰富的对象上传接口，可以通过以下方式上传对象： 流式上传 文件上传 分段上传 追加上传 断点续传上传 SDK支持上传0KB~5GB的对象。流式上传、文件上传和追加上传的内容大小不能超过5GB；当上传较大文件时，请使用分段上传，分段上传每段内容大小不能超过5GB。 如果上传的对象权限设置为匿名用户读取权限，对象上传成功后，匿名用户可通过链接地址访问该对象数据。对象链接地址格式为：https://桶名.域名/文件夹目录层级/对象名。如果该对象存在于桶的根目录下，则链接地址将不需要有文件夹目录层级。 父主题： 上传对象

断点续传下载 当下载大对象到本地文件时，经常出现因网络不稳定或程序崩溃导致下载失败的情况。失败后再次重新下载不仅浪费资源，而且当网络不稳定时仍然有下载失败的风险。断点续传下载接口能有效地解决此类问题引起的下载失败，其原理是将待下载的对象分成若干个分段分别下载，并实时地将每段下载结果统一记录在checkpoint文件中，仅当所有分段都下载成功时返回下载成功的结果，否则抛出异常提醒用户再次调用接口进行重新下载（重新下载时因为有checkpoint文件记录当前的下载进度，避免重新下载所有分段，从而节省资源提高效率）。 您可以通过downloadFile进行断点续传下载。该接口可设置的参数如下： 参数 作用 OBS iOS SDK对应方法 bucketName 桶名，必选参数。 request.bucketName objectKey 对象名，必选参数。 request.objectKey downloadFilePath 下载对象的本地文件全路径。 request.downloadFilePath versionID 对象的版本号。 request.versionID enableCheckpoint 是否开启断点续传模式，默认为NO，表示不开启。 request.enableCheckpoint enableMD5Check 是否开启MD5校验。 request.enableMD5Check enableForceOverwrite 是否开启强制覆盖。 request.enableForceOverwrite checkpointFilePath 记录下载进度的文件，只在断点续传模式下有效。当该值为空时，默认与下载对象的本地文件路径同目录。 request.checkpointFilePath partSize 分段大小，单位字节，取值范围是5MB~5GB。 request.partSize ifModifiedSince 如果对象在指定的时间后有修改，则返回对象内容，否则返回错误。。 request.ifModifiedSince ifUnmodifiedSince 如果对象在指定的时间后没有修改，则返回对象内容，否则返回错误。 request.ifUnmodifiedSince ifETagMatch 如果对象的ETag值与该参数值相同，则返回对象内容，否则抛出异常。 request.ifETagMatch ifETagNoneMatch 如果对象的ETag值与该参数值不相同，则返回对象内容，否则抛出异常。 request.ifETagNoneMatch 以下代码展示了如何使用断点续传下载接口下载对象到本地文件： static OBSClient *client; NSString *endPoint = @"your-endpoint"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html char* ak_env = getenv("AccessKeyID"); char* sk_env = getenv("SecretAccessKey"); NSString *AK = [NSString stringWithUTF8String:ak_env]; NSString *SK = [NSString stringWithUTF8String:sk_env]; // 初始化身份验证 OBSStaticCredentialProvider *credentialProvider = [[OBSStaticCredentialProvider alloc] initWithAccessKey:AK secretKey:SK]; //初始化服务配置 OBSServiceConfiguration *conf = [[OBSServiceConfiguration alloc] initWithURLString:endPoint credentialProvider:credentialProvider]; // 初始化client client = [[OBSClient alloc] initWithConfiguration:conf]; // 存储路径 NSString * outfilePath = [NSTemporaryDirectory() stringByAppendingString:@"filename"]; // 最大并发数 self.client.configuration.maxConcurrentDownloadRequestCount = 5; // 断点续传下载 OBSDownloadFileRequest *request = [[OBSDownloadFileRequest alloc]initWithBucketName:@"bucketname" objectKey:@"objectname" downloadFilePath:outfilePath]; // 是否打开强制覆盖 request.enableForceOverwrite = YES; // 分段大小 request.partSize = [NSNumber numberWithInteger:5*1024*1024]; // 是否开启断点续传 request.enableCheckpoint = YES; request.downloadProgressBlock = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) { NSLog(@"%0.1f%%",(float)floor(totalBytesWritten*10000/totalBytesExpectedToWrite)/100); }; OBSBFTask *task = [client downloadFile:request completionHandler:^(OBSDownloadFileResponse *response, NSError *error) { NSLog(@"%@",response); }]; [task waitUntilFinished]; if(task.error){ // 重新下载 } 父主题： 下载对象

追加上传 追加上传可实现对同一个对象追加数据内容的功能。您可以通过appendObject进行追加上传。示例代码如下： NSString *filePath = [[NSBundle mainBundle] pathForResource:@"FileName" ofType:@"FileSuffix"]; NSFileManager *manager = [NSFileManager defaultManager]; NSDictionary *fileDic = [manager attributesOfItemAtPath:filePath error:nil]; unsigned long long size = [[fileDic objectForKey:NSFileSize] longLongValue]; int filesize = size; //第一次追加上传 OBSAppendObjectWithFileRequest *request = [[OBSAppendObjectWithFileRequest alloc] initWithBucketName:@"bucketName" objectKey:@"objectname" uploadFilePath:filePath]; request.position = [NSNumber numberWithFloat:0]; request.uploadProgressBlock = ^(int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend) { NSLog(@"%0.1f%%",(float)floor(totalBytesSent*10000/totalBytesExpectedToSend)/100); }; [client appendObject:request completionHandler:^(OBSAppendObjectResponse *response, NSError *error) { NSLog(@"%@",response); //下次上传位置 Int position = response.nextPosition; }]; //第二次追加上传 OBSAppendObjectWithFileRequest *request = [[OBSAppendObjectWithFileRequest alloc] initWithBucketName:@"bucketName" objectKey:@"objectname" uploadFilePath:filePath]; request.position = [NSNumber numberWithFloat:size]; request.uploadProgressBlock = ^(int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend) { NSLog(@"%0.1f%%",(float)floor(totalBytesSent*10000/totalBytesExpectedToSend)/100); }; [client appendObject:request completionHandler:^(OBSAppendObjectResponse *response, NSError *error) { NSLog(@"%@",response); //下次上传位置 Int position = response.nextPosition; }]; putObject上传的对象可覆盖appendObject上传的对象，覆盖后对象变为普通对象，不可再进行追加上传。 第一次调用追加上传时，如果已存在同名的普通对象，则会抛出异常（HTTP状态码为409）。 追加上传返回的ETag是当次追加数据内容的ETag，不是完整对象的ETag。 单次追加上传的内容不能超过5GB，且最多支持10000次追加上传。 追加上传成功后，可通过response.nextPosition获取下次追加上传的位置；或者通过getObjectMetadata接口获取下次追加上传的位置。 父主题： 上传对象

断点续传上传 当上传大文件时，经常出现因网络不稳定或程序崩溃导致上传失败的情况。失败后再次重新上传不仅浪费资源，而且当网络不稳定时仍然有上传失败的风险。断点续传上传接口能有效地解决此类问题引起的上传失败，其原理是将待上传的文件分成若干个分段分别上传，并实时地将每段上传结果统一记录在checkpoint文件中，仅当所有分段都上传成功时返回上传成功的结果，否则抛出异常提醒用户再次调用接口进行重新上传（重新上传时因为有checkpoint文件记录当前的上传进度，避免重新上传所有分段，从而节省资源提高效率）。 您可以通过uploadFile进行断点续传上传。该接口可设置的参数如下： 参数 作用 OBS iOS SDK对应方法 bucketName 桶名，必选参数。 request.bucketName objectKey 对象名，必选参数。 request.objectKey objectACLPolicy 对象访问策略。 request.objectACLPolicy storageClass 对象存储类型。 request.storageClass metaDataDict 对象元数据。 request.metaDataDict websiteRedirectLocation 网址重定向位置。 request.websiteRedirectLocation encryption 加密方式。 request.encryption enableCheckpoint 是否开启断点续传模式，默认为NO，表示不开启。 request.enableCheckpoint enableMD5Check 是否开启MD5校验，默认为NO，表示不开启。 request.enableMD5Check checkpointFilePath 记录上传进度的文件，只在断点续传模式下有效。当该值为空时，默认与待上传的本地文件同目录。文件名后缀可指定为obsuploadcheckpoint。 request.checkpointFilePath partSize 分段大小，单位字节，取值范围是100KB~5GB，默认为5MB。 request.partSize 以下代码展示了如何使用断点续传上传接口上传文件： static OBSClient *client; NSString *endPoint = @"your-endpoint"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html char* ak_env = getenv("AccessKeyID"); char* sk_env = getenv("SecretAccessKey"); NSString *AK = [NSString stringWithUTF8String:ak_env]; NSString *SK = [NSString stringWithUTF8String:sk_env]; // 初始化身份验证 OBSStaticCredentialProvider *credentialProvider = [[OBSStaticCredentialProvider alloc] initWithAccessKey:AK secretKey:SK]; //初始化服务配置 OBSServiceConfiguration *conf = [[OBSServiceConfiguration alloc] initWithURLString:endPoint credentialProvider:credentialProvider]; // 初始化client client = [[OBSClient alloc] initWithConfiguration:conf]; // 分段上传的最大并发数 client.configuration.maxConcurrentUploadRequestCount = 5; // 分段上传请求的最大连接数 client.configuration.uploadSessionConfiguration.HTTPMaximumConnectionsPerHost = 10; NSString *filePath = [[NSBundle mainBundle]pathForResource:@"fileName" ofType:@"Type"]; OBSUploadFileRequest *request = [[OBSUploadFileRequest alloc]initWithBucketName:@"bucketname" objectKey:@"objectname" uploadFilePath:filePath]; // 分段大小为5MB request.partSize = [NSNumber numberWithInteger: 5 * 1024*1024]; // 开启断点续传模式 request.enableCheckpoint = YES; // 指定checkpoint文件路径 request.checkpointFilePath = @"Your CheckPoint File"; // 上传文件 request.uploadProgressBlock = ^(int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend) { NSLog(@"%0.1f%%",(float)floor(totalBytesSent*10000/totalBytesExpectedToSend)/100); }; OBSBFTask *task = [client uploadFile:request completionHandler:^(OBSUploadFileResponse *response, NSError *error) { NSLog(@"%@",response); if(error){ // 再次上传 } }]; 断点续传上传接口是利用分段上传特性实现的，是对分段上传的封装和加强。 断点续传上传接口不仅能在失败重传时节省资源提高效率，还因其对分段进行并发上传的机制能加快上传速度，帮助用户快速完成上传业务；且其对用户透明，用户不用关心checkpoint文件的创建和删除、分段任务的切分、并发上传的实现等内部细节。 enableCheckpoint参数默认是NO，代表不启用断点续传模式，此时断点续传上传接口退化成对分段上传的简单封装，不会产生checkpoint文件。 checkpointFile参数仅在enableCheckpoint参数为YES时有效。 当前，当有多个上传任务需要并发执行时，需为每个上传任务初始化一个client及request进行处理。 父主题： 上传对象