流控失败常见问题及处理 接口报错样例: {"status_code":429,"request_id":"7e6c1***********c610","error_code":"APIGW.0308","error_message":"The throttling threshold has been reached: policy user over ratelimit,limit:10,time:1 second","encoded_authorization_message":""} 处理方式: 华为云为客户运营能力API均提供默认的流量配额，用户可根据自己实际业务场景对额度进行升级。用户可以监视429状态码并构建重试机制。重试机制应遵循指数回退计划，以在必要时减少请求量。用户还可以在退避时间表中建立一些随机性，以避免严重的羊群效应。

后端服务调用失败“Backend unavailable”或超时“Backend timeout”原因分析 以下原因可能导致后端服务调用失败或者超时，请逐一排查。 原因 解决方案 后端服务地址错误。 在编辑API中修改后端服务地址。 如果是 域名 ，请确认域名能正确解析到后端服务IP地址。 后端超时时间设置不合理。 当后端服务没有在设置的后端超时时间内返回时，API网关提示后端服务调用失败。 在编辑API中增加后端超时时间。 如果“后端服务地址”在E CS （Elastic Cloud Server），ECS的安全组的出/入方向规则可能拦截了请求。 检查后端服务所在ECS的安全组，确保出/入方向端口规则和协议都设置正确。 请求协议配置错误，如后端服务为HTTP，在API网关配置为HTTPS。 创建的API与后端服务配置相同的协议。 API网关客户侧后端服务链接链路不通。 排查链接链路。 父主题： API调用

约束与限制 使用APP认证方式的API必须先通过应用授权才能调用。 APP认证方式的API只能授权给APP类型的应用。 如果对无认证方式的API进行应用授权，则系统会忽略此操作。 仅数据服务专享版支持重置APP类型应用的AppSecret。 仅DAYU Administrator、Tenant Administrator或者工作空间管理员支持重置APP类型应用的AppSecret。 APPSecret限制一分钟内重置一次，重置记录可在事件管理内查看。 重置APPSecret会导致已授权的API调用失败，请谨慎操作。

API调用授权概述 使用APP认证方式的API，需要配置调用授权，把API授权给指定凭据。API调用者在调用API时，可以通过凭据的Key和Secret进行安全认证，也可以通过AppCode进行简易认证。 配置APIG的API认证凭据 在API网关中创建一个凭据，生成密钥对（Key、Secret），在调用API时，API网关服务根据密钥对进行身份核对，完成鉴权。Key唯一且不可重置，支持重置Secret。 配置APIG的API简易认证AppCode API配置简易认证模式后，在调用API时，API网关服务既可以根据AppCode进行简易认证，也可以根据密钥对进行鉴权。 父主题： 配置API调用授权（可选）

流控失败常见问题及处理 接口报错样例: {"status_code":429,"request_id":"7e6c1***********c610","error_code":"APIGW.0308","error_message":"The throttling threshold has been reached: policy user over ratelimit,limit:10,time:1 second","encoded_authorization_message":""} 处理方式: 华为云为客户运营能力API均提供默认的流量配额，用户可根据自己实际业务场景对额度进行升级。用户可以监视429状态码并构建重试机制。重试机制应遵循指数回退计划，以在必要时减少请求量。用户还可以在退避时间表中建立一些随机性，以避免严重的羊群效应。

准备开发环境 安装开发工具 请根据所使用语言选择适合的开发工具。 安装2018.3.5或以上版本的IntelliJ IDEA，安装包请至IntelliJ IDEA官方网站下载。 安装2019 version 16.8.4及以上版本的Visual Studio，安装包请至Visual Studio官方网站下载。 安装开发语言环境 Java：安装1.8.111或以上版本的Java Development Kit，安装包请至Oracle官方下载页面下载。 Go：安装1.14及以上版本的Go安装包，安装包请至Go官方下载页面下载。 Python：安装2.7或3.X版本的Python安装包，安装包请至Python官方下载页面下载。 JavaScript：安装15.10.0及以上版本的Nodejs安装包，安装包请至Nodejs官方下载页面下载。 PHP：安装8.0.3及以上版本的PHP安装包，安装包请至PHP官方下载页面下载。 Android：安装4.1.2及以上版本的Android Studio，安装包请至Android Studio官方网站下载。

API调用授权（伙伴） 伙伴操作员账号调用API需要经过授权，可通过伙伴中心对操作员赋予有权限项的角色来进行授权，如何为角色授权请参见为组织人员分配权限。接口对应的权限项如下表，只要有权限项中的一条即可以调用。 未在表里的接口不需要做细粒度权限校验，操作员账号均可调用。 官网参考资料链接： 合作伙伴中心API参考（中国站） 表1 场景 子场景 接口名称 接口URL 权限项 权限项名称 管理产品 查询产品信息 查询产品的折扣和激励策略 GET /v2/products/incentive-discount-policies BPC_ITEM_SALES_040100 销售-激励-产品激励策略-产品折扣与激励策略查看 管理客户 注册客户 校验客户注册信息 POST /v2/partners/sub-customers/users/check-identity BPC_ITEM_SUBCUSTSERV_010118 销售-客户-客户管理-客户列表-创建伙伴子客户（能力开放） 发送验证码 POST /v2/bases/verificationcode/send BPC_ITEM_SUBCUSTSERV_010118 销售-客户-客户管理-客户列表-创建伙伴子客户（能力开放） 创建客户 POST /v2/partners/sub-customers BPC_ITEM_SUBCUSTSERV_010118 销售-客户-客户管理-客户列表-创建伙伴子客户（能力开放） 实名认证 申请个人实名认证 POST /v2/customers/realname-auths/individual BPC_ITEM_SUBCUSTSERV_010119 销售-客户-客户管理-客户列表-实名认证同步（能力开放） 申请企业实名认证 POST /v2/customers/realname-auths/enterprise BPC_ITEM_SUBCUSTSERV_010119 销售-客户-客户管理-客户列表-实名认证同步（能力开放） 申请实名认证变更 PUT /v2/customers/realname-auths/enterprise BPC_ITEM_SUBCUSTSERV_010119 销售-客户-客户管理-客户列表-实名认证同步（能力开放） 查询实名认证审核结果 GET /v2/customers/realname-auths/result BPC_ITEM_SUBCUSTSERV_010119 销售-客户-客户管理-客户列表-实名认证同步（能力开放） 管理客户 查询客户列表 POST /v2/partners/sub-customers/query BPC_ITEM_SUBCUSTSERV_010100|BPC_ITEM_SUBCUSTSERV_010500 销售-客户-客户管理-客户列表-查看列表 销售-客户-客户管理-二级经销商子客户-查看客户信息 查询客户的新客标签 POST /v2/partners/sub-customers/new-customers-tags/batch-query BPC_ITEM_SUBCUSTSERV_010100 销售-云经销商-云经销商管理-我的二级分销商列表-查看历史客户经理 管理云经销商 查询云经销商 查询云经销商列表 POST /v2/partners/indirect-partners/query BPC_ITEM_SALES_020100 销售-云经销商-云经销商管理-我的二级分销商列表-查询二级分销商列表 管理云经销商账户 向云经销商账户拨款 POST /v2/accounts/partner-accounts/indirect-partner-adjust BPC_ITEM_SALES_020104 销售-云经销商-云经销商管理-我的二级分销商列表-拨款 回收云经销商账户拨款 POST /v2/accounts/partner-accounts/indirect-partner-reclaim BPC_ITEM_SALES_020105 销售-云经销商-云经销商管理-我的二级分销商列表-回收 管理云经销商优惠券 查询已发放的代金券额度 GET /v2/partners/issued-coupon-quotas BPC_ITEM_SUBCUSTSERV_030600 销售-客户-券管理-已发放代金券-查询已发放列表 向云经销商发放代金券额度 POST /v2/partners/coupon-quotas/indirect-partner-adjust BPC_ITEM_SALES_020106|BPC_ITEM_SUBCUSTSERV_030104 销售-云经销商-云经销商管理-我的二级经销商列表-发放代金券额度 销售-客户-券管理-代金券额度-发放额度 回收代金券额度 POST /v2/partners/coupon-quotas/indirect-partner-reclaim BPC_ITEM_SUBCUSTSERV_030601|BPC_ITEM_SUBCUSTSERV_030602 销售-客户-券管理-已发放代金券额度-批量回收代金券额度 销售-客户-券管理-已发放代金券额度-回收代金券额度 查询代金券额度的发放回收记录 GET /v2/partners/coupon-quotas/records BPC_ITEM_SUBCUSTSERV_030102 销售-客户-券管理-代金券额度-查看操作记录 管理交易 管理客户账户 向客户账户拨款 POST /v2/accounts/partner-accounts/adjust-amount BPC_ITEM_SUBCUSTSERV_010103 销售-客户-客户管理-客户列表-拨款 查询客户账户余额 POST /v2/accounts/customer-accounts/balances/batch-query BPC_ITEM_SUBCUSTSERV_010103|BPC_ITEM_SUBCUSTSERV_010104|BPC_ITEM_SUBCUSTSERV_010100 销售-客户-客户管理-客户列表-拨款 销售-客户-客户管理-客户列表-回收 销售-客户-客户管理-客户列表-查看列表 回收客户账户余额 POST /v2/accounts/partner-accounts/reclaim BPC_ITEM_SUBCUSTSERV_010104 销售-客户-客户管理-客户列表-回收 查询收支明细 GET /v2/accounts/partner-accounts/account-change-records BPC_ITEM_FINANCE_030100 销售-账务-资金管理-收支明细-查看收支明细 查询调账记录 GET /v3/accounts/partner-accounts/adjust-records BPC_ITEM_FINANCE_040100 销售-客户-客户管理-调账记录-查看调账记录 查询伙伴/云经销商账户余额 GET /v2/accounts/partner-accounts/balances BPC_ITEM_VIEW_010100|BPC_ITEM_SUBCUSTSERV_010103|BPC_ITEM_SUBCUSTSERV_010104|BPC_ITEM_SALES_020104|BPC_ITEM_SALES_020105 主页-账号 销售-客户-客户管理-客户列表-拨款 销售-客户-客户管理-客户列表-回收 销售-云经销商-云经销商管理-我的二级分销商列表-拨款 销售-云经销商-云经销商管理-我的二级分销商列表-回收 管理优惠券 查询优惠券列表 GET /v2/promotions/benefits/coupons BPC_MENU_FINANCE_100100|BPC_ITEM_SUBCUSTSERV_050101 销售-客户-券管理-代金券额度-查看代金券列表 销售-客户-客户订单-订单支付-支付订单 查询优惠券额度 POST /rest/cbc/openapi/v2/partners/coupon-quotas/query BPC_ITEM_SUBCUSTSERV_030100 销售-客户-券管理-代金券额度-查看代金券列表 发放优惠券 POST /v2/promotions/benefits/partner-coupons BPC_ITEM_SUBCUSTSERV_030102|BPC_ITEM_SUBCUSTSERV_030103 销售-客户-券管理-代金券额度-发放代金券 销售-客户-券管理-现金券额度-查看操作记录 回收优惠券 POST /v2/promotions/benefits/partner-coupons/reclaim BPC_ITEM_SUBCUSTSERV_030201 销售-客户-券管理-已发放代金券-回收代金券 查询优惠券的发放回收记录 GET /v2/promotions/benefits/partner-coupons/records/query BPC_ITEM_SUBCUSTSERV_030102 销售-客户-券管理-代金券额度-查看操作记录 管理包年/包月订单 查询订单列表 GET /v2/orders/customer-orders BPC_ITEM_SUBCUSTSERV_060100|BPC_ITEM_SUBCUSTSERV_060200 销售-客户-客户订单-客户订单-查看列表 销售-客户-客户订单-二级经销商的客户-查看列表 查询订单详情 GET /v2/orders/customer-orders/details/{order_id} BPC_ITEM_SUBCUSTSERV_060100|BPC_ITEM_SUBCUSTSERV_060200 销售-客户-客户订单-客户订单-查看列表 销售-客户-客户订单-二级经销商的客户-查看列表 管理按需资源 查询客户按需资源列表 POST /v2/partners/sub-customers/on-demand-resources/query BPC_ITEM_SUBCUSTSERV_010105 销售-客户-客户管理-客户列表-查看客户资源 管理账单 - 查询客户月度消费账单 GET /v2/bills/partner-bills/subcustomer-bills/monthly-sum BPC_ITEM_FINANCE_090100 销售-账务-伙伴账单-查看伙伴账单 管理客户消费 查询伙伴消费子客户列表 POST /v2/bills/subcustomer-bills/res-fee-records/sub-customers/query BPC_ITEM_FINANCE_020100 销售-客户-客户消费-消费记录-查看列表 查询伙伴子客户消费记录 GET /v2/bills/subcustomer-bills/res-fee-records BPC_ITEM_FINANCE_020101 销售-客户-客户消费-消费记录-查看详情 父主题： API调用方式

调用API示例 在工程中引入sdk。 using APIGATEWAY_SDK; 生成一个新的Signer， 输入API所授权凭据的Key和Secret，可参考获取API的调用信息获取。 Signer signer = new Signer(); // Directly writing AK/SK in code is risky. For security, encrypt your AK/SK and store them in the configuration file or environment variables. // In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, set environment variables HUAWEICLOUD_SDK_AK and HUAWEICLOUD_SDK_SK. signer.Key = Environment.GetEnvironmentVariable("HUAWEICLOUD_SDK_AK"); signer.Secret = Environment.GetEnvironmentVariable("HUAWEICLOUD_SDK_SK"); 生成一个Request对象，指定方法名、请求url和body，可参考获取API的调用信息获取。 HttpRequest r = new HttpRequest("POST", new Uri("https://c967a237-cd6c-470e-906f-a8655461897e.apigw.exampleRegion.com/app1?query=value")); r.body = "{\"a\":1}"; 给请求添加x-stage头，内容为环境名。如有需要，添加需要签名的其他头域。 r.headers.Add("x-stage", "RELEASE"); 进行签名，执行此函数会生成一个新的HttpWebRequest，并在请求参数中添加用于签名的X-Sdk-Date头和Authorization头。 1 HttpWebRequest req = signer.Sign(r); 若使用系统分配的子域名访问https请求的API，需要忽略证书校验，否则跳过此步。 System.Net.ServicePointManager.ServerCertificateValidationCallback = new System.Net.Security.RemoteCertificateValidationCallback(delegate { return true; }); 访问API，查看访问结果。 var writer = new StreamWriter(req.GetRequestStream()); writer.Write(r.body); writer.Flush(); HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); var reader = newStreamReader(resp.GetResponseStream()); Console.WriteLine(reader.ReadToEnd());

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 total Integer 调用API总次数 succeed Integer 调用API成功次数 failed Integer 调用API失败次数 openapi_called_records Array of OpenApiCalledRecord objects API调用记录列表 next_marker String 获取下一页所需的标识符。 表4 OpenApiCalledRecord 参数 参数类型 描述 user_name String 调用API的user_name user_id String 调用API的user_id domain_name String 调用API的domain_name domain_id String 调用API的domain_id request_url String 调用API的URL request_method String http请求方法 response_code String http状态码 fail_reason String 调用API失败原因 timestamp Long 调用API的时间（Unix timestamp），单位：毫秒 状态码： 400 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误信息

URI GET /v1/{project_id}/openapi/called-records 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID。 表2 Query参数 参数 是否必选 参数类型 描述 limit 否 Integer 分页大小，默认1000，最大2000。 called_url 否 String 需要查询调用记录的URL，例如：/v1/{project_id}/sdg/database/watermark/embed start_time 否 Long 开始时间（Unix timestamp），单位：毫秒，例如：0 end_time 否 Long 结束时间（Unix timestamp），单位：毫秒，例如：1638515803572 marker 否 String 指定一个标识符。获取第一页时不用赋值，获取下一页时取上页查询结果的返回值。

响应示例 状态码： 200 OK { "total" : 11, "succeed" : 11, "failed" : 0, "openapi_called_records" : [ { "user_name" : "xxxxxxxxxxxxx", "user_id" : "xxxxxxxxxxxxxxxxx", "domain_name" : "xxxxxxxxxxxxxxxxx", "domain_id" : "xxxxxxxxxxxxxxxxxxx", "request_url" : "/v1/xxxxxxxxxxxxxxxxxxxxxxxxxxx/sdg/doc/watermark/embed", "request_method" : "POST", "response_code" : "200", "fail_reason" : "", "timestamp" : 1638427576524 } ], "next_marker" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } 状态码： 400 无效请求 { "error_code" : "dsc.40000011", "error_msg" : "Invalid parameter" }

调用API 配置请求地址相关参数。 API调用场景 API请求参数配置 使用域名调用API ROMA API允许使用服务分配的子域名或服务绑定的域名调用API，无需另外配置。 使用IP调用API ROMA API的实例配置参数“app_route”已设置为“on”，允许通过IP访问API。 允许使用IP地址调用API，无需另外配置。 配置认证参数。 API认证方式 API请求参数配置 APP认证 签名认证 使用获取的SDK对API请求进行签名，具体请参考APP认证开发。 简易认证 在ROMA API请求中添加Header参数“X-Apig-AppCode”，参数值为获取API的请求信息中获取到的AppCode。 双重认证 在API请求参数中增加自定义认证信息进行认证。 凭证认证 在API请求中添加Header参数“X-HW-ID”，获取API的请求信息中获取到凭证信息的Key。 在API请求中添加Header参数“X-HW-AppKey”，获取API的请求信息中获取到凭证信息的Secret。 app_api_key认证 ROMA API的实例配置参数“app_api_key”已设置为“on”，开启app_api_key认证。 在API请求中添加Header或Query参数“apikey”，参数值为获取API的请求信息中获取到的Key或AppKey。 app_secret认证 ROMA API的实例配置参数“app_secret”已设置为“on”，开启app_secret认证，且“app_api_key”已设置为“off”，关闭app_api_key认证。 在API请求中添加Header参数“X-HW-ID”，参数值为API所授权的Key或客户端的AppKey。 在API请求中添加Header参数“X-HW-AppKey”，参数值为获取API的请求信息中获取到的Secret或AppSecret。 app_basic认证 ROMA API的实例配置参数“app_basic”已设置为“on”，开启app_basic认证。 在API请求中添加Header参数“Authorization”，参数值为"Basic "+base64(appkey+":"+appsecret)，其中appkey和appsecret分别为获取API的请求信息中获取到的Key和Secret（或AppKey和AppSecret）。 app_jwt认证 ROMA API的实例配置参数“app_jwt”已设置为“on”，开启app_jwt认证。 在API请求中添加Header参数“Timestamp”，参数值为当前时间的Unix时间戳。 在API请求中添加Header参数“Authorization”，参数值为sha256(appkey+appsecret+timestamp)，其中appkey和appsecret分别为获取API的请求信息中获取到的Key和Secret（或AppKey和AppSecret），timestamp为当前时间的Unix时间戳。 华为 IAM 认证 Token认证 先获取云服务平台的认证Token，然后在API请求中携带Token进行认证。 AK/SK认证 调用API时，使用获取的SDK对API请求进行签名，具体请参考IAM认证开发（AK/SK）。 双重认证 在API请求参数中增加自定义认证信息进行认证。 自定义认证 在API请求参数中携带认证信息进行认证。 无认证 无需认证，可直接调用API。

获取API的请求消息 在调用API前，您需要向API管理者获取API的请求信息，包括访问域名、请求协议、请求方法、请求路径以及请求参数。 根据API使用的安全认证方式，还要获取相关的请求认证信息： APP认证： 签名认证：向API管理者获取该API所授权应用的Key和Secret（或客户端的AppKey和AppSecret），以及用于调用API的SDK。 简易认证：向API管理者获取该API所在应用的AppCode。 其他认证：向API管理者获取该API所授权应用的Key和Secret（或客户端的AppKey和AppSecret）或凭证信息。 华为IAM认证：通过云服务平台的账号凭证（账号和密码 获取Token 或者AK/SK）进行认证。如果使用AK/SK进行认证，还需要向API管理者获取用于调用API的SDK。 自定义认证：向API管理者获取请求参数中要携带的自定义认证信息。 无认证：无需认证信息。

导入工程 打开IntelliJ IDEA，在菜单栏选择“Import Project”。 弹出“Select File or Directory to Import”对话框。 在弹出的对话框中选择解压后的SDK路径，单击“OK”。 “Import project from external model”选择“Eclipse”，单击“Next”，进入下一页后保持默认连续单击“Next”，直到“Please select project SDK”页面。 图2 Import Project 单击“Finish”，完成工程导入。 图3 Finish 完成导入后，目录结构如下图。 图4 目录结构

操作场景 当您使用Token认证方式完成认证鉴权时，需要获取用户Token并在调用接口时增加“X-Auth-Token”到业务接口请求消息头中。 调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。 Token认证：通过Token认证调用请求。 AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key）对调用请求内容进行签名认证。 Site实例中不支持IAM认证开发。