华为云用户手册

操作场景 开放API前，您需要为API分组绑定一个或多个独立 域名 ，API网关通过独立域名定位到此分组。 共享版中，不同分组下不能绑定相同的独立域名。 在绑定域名前，您需要理解以下2个概念： 子域名：API分组创建后，系统为分组自动分配一个内部测试用的子域名，此子域名唯一且不可更改，每天最多可以访问1000次。 独立域名：您自定义的域名，最多可以添加5个独立域名，不限访问次数。API调用者通过访问独立域名来调用您开放的API。

脚本配置示例 { "auth_request": { "method": "GET", "protocol": "HTTPS", "url_domain": "192.168.10.10", "timeout": 5000, "path": "/", "vpc_channel_enabled": false, "vpc_channel_info": null }, "custom_forbid_limit": 100, "carry_body": { "enabled": true, "max_body_size": 1000 }, "auth_downgrade_enabled": true, "carry_path_enabled": true, "return_resp_body_enabled": false, "carry_resp_headers": [], "simple_auth_mode_enabled": true, "match_auth": null, "rule_enabled": false, "rule_type": "allow"}

前提条件 同一个环境中，一个API只能被一个第三方认证策略绑定，但一个第三方认证策略可以绑定多个API。 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 策略的绑定、解绑、更新会实时生效，不需要重新发布API。 API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 如果策略与API有绑定关系，则策略无法执行删除操作。

为策略绑定API 单击策略名称，进入策略详情。 在API列表区域选择环境后，单击“绑定API”。 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 单击“确定”，绑定完成。 如果单个API不需要绑定此策略，单击API所在行的“解绑”。 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方“解绑”。最多同时解绑1000个API。

x-apigateway-ratelimits 含义：流控策略名称与关联策略映射。 作用域：Swagger Object 示例： x-apigateway-ratelimits: customRatelimitName: api-limit: 200 app-limit: 200 user-limit: 200 ip-limit: 200 interval: 1 unit: second/minute/hour shared: true special: - type: APP limit: 100 instance: xxxxxxxxx 表1 参数说明 参数 是否必选 类型 说明 customRatelimitName 否 x-apigateway-ratelimits.policy 指定名称的流控策略。 要使用该策略，将x-apigateway-ratelimit属性值引用为该策略名称。 父主题： APIG的API设计文件扩展定义

脚本配置示例 { "scope": "basic", "default_interval": 60, "default_time_unit": "second", "api_limit": 100, "app_limit": 50, "user_limit": 50, "ip_limit": 20, "specials": [ { "type": "app", "policies": [ { "key": "e9230d70c749408eb3d1e838850cdd23", "limit": 10 } ] }, { "type": "user", "policies": [ { "key": "878f1b87f71c40a7a15db0998f358bb9", "limit": 10 } ] } ], "algorithm": "counter", "parameters": [ { "id": "3wuj354lpptv0toe0", "value": "reqPath", "type": "path", "name": "reqPath" }, { "id": "53h7e7j11u38l3ocp", "value": "method", "type": "method", "name": "method" }, { "id": "vv502bnb6g40td8u0", "value": "Host", "type": "header", "name": "Host" } ], "rules": [ { "match_regex": "[\"Host\",\"==\",\"www.abc.com\"]", "rule_name": "u8mb", "time_unit": "second", "interval": 2, "limit": 5 } ]}

为策略绑定API 单击策略名称，进入策略详情。 在API列表区域选择环境后，单击“绑定API”。 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 单击“确定”，绑定完成。 如果单个API不需要绑定此策略，单击API所在行的“解绑”。 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方“解绑”。最多同时解绑1000个API。

约束与限制 同一个环境中，一个API只能被一个流量控制2.0策略绑定，但一个流量控制2.0策略可以绑定多个API。 如果一个API绑定流量控制策略后，继续绑定流量控制2.0策略，流量控制策略会失效。 参数流控的参数支持1~32个字符；参数流控的规则最多可定义100个。 策略内容最大长度65535。 策略参数会明文展示，为防止信息泄露，请谨慎配置。 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 策略的绑定、解绑、更新会实时生效，不需要重新发布API。 API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 如果策略与API有绑定关系，则策略无法执行删除操作。

x-apigateway-match-mode 含义：API网关定义的API请求URL的匹配模式，支持NORMAL和SWA。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: x-apigateway-match-mode: 'SWA' 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-match-mode 是 String API匹配模式，支持SWA和NORMAL。 SWA：前缀匹配，如“/prefix/foo”和“/prefix/bar”都会被“/prefix ”匹配，但“/prefixpart”却不会被匹配。 NORMAL：绝对匹配，如“/prefix/foo”只能被“/prefix/foo”匹配。 父主题： APIG的API设计文件扩展定义

x-apigateway-backend.mockEndpoints 含义：API网关定义的MOCK类型API后端服务定义。 作用域：x-apigateway-backend 示例： paths: '/users/{userId}': get: produces: - "application/json" parameters: - name: "X-Auth-Token" description: "认证token" type: "string" in: "header" required: true responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "MOCK" mockEndpoints: result-content: "mocked" 表1 参数说明 参数 是否必选 类型 说明 result-content 是 String MOCK返回结果。 父主题： APIG的API设计文件扩展定义

为策略绑定API 单击策略名称，进入策略详情。 在API列表区域选择环境后，单击“绑定API”。 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 单击“确定”，绑定完成。 如果单个API不需要绑定此策略，单击API所在行的“解绑”。 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方“解绑”。最多同时解绑1000个API。

约束与限制 同一个API在同一个环境中只能绑定一个相同限制类型的访问控制策略，一个访问控制策略可以绑定多个API。 2022年12月31日后创建的实例支持限制调用API的账号ID，在这之前创建的专享版实例不支持，如需使用，请联系客服。 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 策略的绑定、解绑、更新会实时生效，不需要重新发布API。 API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 如果策略与API有绑定关系，则策略无法执行删除操作。

绑定API 在“访问控制”页面，通过以下任意一种方法，进入“绑定API”页面。 在待绑定的访问控制策略所在行，单击“绑定API”，进入已绑定API列表页面。单击“绑定API”。 单击策略名称，进入策略详情页面。单击“绑定API”。 选择“API分组”、“环境”以及“API名称”，筛选所需的API。 勾选API，单击“绑定”，完成API绑定策略。 在访问控制策略绑定API后，如果API不需要调用此策略，单击“解除”，解除绑定。如果需要批量解绑API，则勾选待解绑的API，单击“解除”。最多同时解绑1000个API。

为策略绑定API 单击策略名称，进入策略详情。 在API列表区域选择环境后，单击“绑定API”。 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 单击“确定”，绑定完成。 如果单个API不需要绑定此策略，单击API所在行的“解绑”。 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方“解绑”。最多同时解绑1000个API。

脚本配置示例 { "cache_key": { "system_params": [ "$context.sourceIp", "$context.requestId" ], "parameters": [ "demo_parameters" ], "headers": [ "demo_header" ] }, "cache_http_status_and_ttl": [ { "http_status": [ 200 ], "ttl": 300 } ], "client_cache_control": { "mode": "apps", "datas": [ "demo_app_id_1,demo_app_id_2" ] }, "cacheable_headers": [ "demo_cacheable_headers_1,demo_cacheable_headers_2" ]}

x-apigateway-backend-policies 含义：API网关定义的API后端策略。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/users/{userId}': get: produces: - "application/json" responses: default: description: "default response" x-apigateway-request-type: "public" x-apigateway-backend: type: "backend endpoint type" x-apigateway-backend-policies: - type: "backend endpoint type" name: "backend policy name" conditions: - type: "equal/enum/pattern", value: "string", origin: "source/request_parameter", parameter_name: "string" 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-backend-policies 否 x-apigateway-backend-policies 策略后端。 type 是 String 后端服务类型，支持HTTP、HTTP-VPC、FUNCTION、MOCK。 name 是 String 后端策略名称。 parameters 否 x-apigateway-backend.parameters 后端参数定义。 httpEndpoints 否 x-apigateway-backend.httpEndpoints HTTP类型服务定义。 httpVpcEndpoints 否 x-apigateway-backend.httpVpcEndpoints HTTP-VPC类型服务定义。 functionEndpoints 否 x-apigateway-backend.functionEndpoints FUNCTION类型服务定义。 mockEndpoints 否 x-apigateway-backend.mockEndpoints MOCK类型服务定义。 conditions 是 x-apigateway-backend-policies.conditions 策略条件数组。 父主题： APIG的API设计文件扩展定义

x-apigateway-plugins 含义：API网关定义的API插件服务。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: x-apigateway-plugins: ['Plugin_mock'] 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-plugins 否 Array API所绑定的插件名列表。 父主题： APIG的API设计文件扩展定义

x-apigateway-orchestrations 含义： API请求参数的编排规则列表。 作用域： Operation Object(2.0)/Operation Object(3.0) 示例： paths: /: get: parameters: - maximum: 0 minimum: 0 maxLength: 0 minLength: 0 type: string x-apigateway-orchestrations: - Orchestration_114w x-apigateway-pass-through: always x-apigateway-sample: '' name: test in: query required: true` 父主题： APIG的API设计文件扩展定义

操作场景 流量控制可限制单位时间内API的被调用次数，保护后端服务。 为了提供持续稳定的服务，您可以通过创建流控策略，针对部分API进行流量控制。 流控策略和API本身是相互独立的，只有将流控策略绑定API后，流控策略才对绑定的API生效。 同一个环境中，一个API只能被一个流控策略绑定，但一个流控策略可以绑定多个API。 如果API未绑定流控策略，共享版API网关系统默认流控限制为200次/秒。

绑定API 在“流量控制”页面，通过以下任意一种方法，进入“绑定API”页面。 在待绑定的流量控制策略所在行，单击“绑定API”，进入已绑定API列表页面。单击“绑定API”。 单击策略名称，进入策略详情页面。在“绑定的API列表”页签中单击“绑定API”。 选择“API分组”、“环境”以及“API名称”，筛选所需的API。 勾选API，单击“绑定”，完成API绑定策略。 图1 绑定API 在流控策略绑定API后，如果API不需要调用此策略，单击“解除”，解除绑定。如果需要批量解绑API，则勾选待解绑的API，单击“解除”。最多同时解绑1000个API。

操作场景 网关响应，指API网关未能成功处理API请求，从而产生的错误响应。API网关提供默认的网关响应（default），如果您需要自定义响应状态码或网关响应内容，可在API分组管理中新增网关响应，其中响应内容符合JSON格式即可。 例如，“default”网关的响应内容为： {"error_code": "$context.error.code", "error_msg": "$context.error.message", "request_id": "$context.requestId"} 您可以自定义为： {"errorcode": "$context.error.code", "errormsg": "$context.error.message", "requestid": "$context.requestId","apiId":"$context.apiId"} JSON体的内容可以按需定制，包括增减字段内容。 API提供的默认网关响应“default”也可以编辑修改。 您可以新增多个网关响应，支持同一分组下不同API配置不同的网关响应内容。 网关响应所定义的错误类型固定且不可修改，具体见网关错误响应类型说明。 响应内容支持调用API网关运行时变量（$context变量），具体见API网关运行时可获取变量。

网关错误响应类型说明 API网关提供的错误响应类型见表1，其中响应状态码可以按实际需要做自定义修改。 表1 API网关的错误响应类型 错误说明 默认的响应状态码 详细说明 拒绝访问 403 拒绝访问，如触发配置的访问控制策略、或异常攻击检测拦截 自定义认证配置错误 500 自定义认证方异常，通信失败、返回异常响应等错误 自定义认证失败 500 自定义认证方返回认证失败 自定义认证身份来源错误 401 前端自定义认证的身份来源信息缺失或不合法错误 认证失败 401 认证失败， IAM 或APP认证校验失败 认证身份来源缺失 401 认证身份来源信息缺失 后端超时 504 后端超时，与后端的网络交互超过预配置的时间错误 后端不可用 502 后端不可用，网络不可达错误 默认4XX - 其它4XX类错误 默认5XX - 其它5XX类错误 未找到匹配的API 404 未匹配到API 请求参数错误 400 请求参数校验失败、不支持的HTTP方法 调用次数超出阈值 429 API调用次数超出所配置的流量策略阈值 应用未授权 401 使用的应用未被授权访问该API

API网关运行时可获取变量 表2 网关错误响应消息体支持的变量 运行时变量名称 描述 $context.apiId API的ID $context.appId API调用者的APP对象ID $context.requestId 当次API调用生成请求ID $context.stage API调用的部署环境 $context.sourceIp API调用者的源地址 $context.authorizer.frontend.property 前端自定义认证响应的context映射的指定键值对的字符串值 $context.authorizer.backend.property 后端自定义认证响应的context映射的指定键值对的字符串值 $context.error.message 当前网关错误响应的错误信息 $context.error.code 当前网关错误响应的错误码 $context.error.type 当前网关错误响应的错误类型

使用AppCode进行API请求的简易认证 在创建API时，选择“APP认证”并且开启“支持简易认证”。 如果您修改已有API为简易认证，需要在修改完成后，将API重新发布，使简易认证模式生效。 将支持简易认证的API绑定到已创建的应用。 发送请求时，增加请求头部参数“X-Apig-AppCode”，省略请求签名相关信息。 以Curl方式为例，增加头部参数名称：X-Apig-AppCode，参数值填已生成的AppCode。 curl -X GET "https://api.exampledemo.com/testapi" -H "content-type: application/json" -H "host: api.exampledemo.com" -H "X-Apig-AppCode: xhrJVJKABSOxc7d***********FZL4gSHEXkCMQC"

操作场景 自定义认证包含两种认证：前端自定义认证和后端自定义认证。 前端自定义认证：如果您希望使用自己的认证系统，而不是APP认证/华为IAM认证对API的访问进行认证鉴权时，您可以使用自定义认证，通过您自定义的函数进行认证鉴权。 后端自定义认证：当不同的后端服务使用不同的认证系统时，导致您需要为不同的认证系统定制化开发API，而APIG通过自定义认证功能，将多种认证系统集成，简化API开发的复杂度。您只需要在APIG中创建自定义的函数认证，APIG通过此函数对接后端认证系统，获取后端服务的访问授权。 自定义认证依赖 函数工作流 服务。如果当前Region没有上线函数工作流服务，则不支持使用自定义认证。 自定义认证的具体使用指导，可参考《API网关开发指南》的自定义认证相关章节。 使用自定义认证调用API的流程如下图所示： 图1 通过自定义认证调用API

操作场景 简易认证指调用API时，在HTTP请求头部消息增加一个参数X-Apig-AppCode（参数值填应用详情中“AppCode”的值），而不需要对请求内容签名，API网关也仅校验AppCode，不校验请求签名，从而实现快速响应。 当使用APP认证，且开启了简易认证模式，API请求既可以选择使用Appkey和AppSecret做签名和校验，也可以选择使用AppCode进行简易认证。 为了确保安全，简易认证仅支持HTTPS方式调用API，不支持HTTP。 每个应用最多可创建5个AppCode。

配置终端节点信息 进入API网关控制台页面。 在左侧导航栏选择“实例管理”。 在已创建的实例上，单击“查看控制台”或实例名称。 单击“终端节点管理”页签，根据下表参数说明，查看终端节点信息，详细信息可参考终端节点管理。 表1 终端节点信息 参数 说明 服务信息 展示的名称由{region}.{终端节点服务名称}.{终端节点服务ID}组成。您在购买实例时，会同步创建 VPC终端节点 服务，可以设置终端节点服务名称，也可以在此处修改终端节点服务名称。 连接管理 展示连接到网关实例的终端节点信息。如果需要新建终端节点，请单击“创建终端节点”创建。 终端节点ID：终端节点的ID。 报文标识：终端节点ID的标识，用来识别是哪个终端节点。 状态：终端节点的状态。 关于终端节点的各个状态，请查看终端节点服务和终端节点有哪些状态？。 拥有者：终端节点创建者的账号ID。 创建时间：终端节点的创建时间。 操作：终端节点服务对终端节点的连接审批，可选择“接受”或“拒绝”。 须知： 如您仍有业务通过该连接进行访问，拒绝已建立的连接可能导致业务受损，请谨慎操作。 权限管理 权限管理用于控制是否允许跨租户的终端节点进行访问。可以设置允许连接该终端节点服务的授权账号ID，将授权账号ID添加至终端节点服务的白名单中。 单击“添加白名单记录”，填写账号ID。 授权账号ID：连接访问终端节点的授权账号ID。 创建时间：白名单的创建时间。 操作：对连接访问终端节点的授权账号进行操作，支持将授权账号从白名单中删除。

x-apigateway-request-type 含义：API网关定义的API请求类型，支持public和private。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: x-apigateway-request-type: 'public' 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-request-type 是 String API类型，支持public和private。 public：公开类型API，可以上架。 private：私有类型API，不会被上架。 父主题： APIG的API设计文件扩展定义

使用AppCode进行API请求的简易认证 在创建API时，选择“APP认证”并且开启“支持简易认证”。 如果您修改已有API为简易认证，需要在修改完成后，将API重新发布，使简易认证模式生效。 将支持简易认证的API绑定到已创建的凭据。 发送请求时，增加请求头部参数“X-Apig-AppCode”，省略请求签名相关信息。 以Curl方式为例，增加头部参数名称：X-Apig-AppCode，参数值填已生成的AppCode。 curl -X GET "https://api.exampledemo.com/testapi" -H "content-type: application/json" -H "host: api.exampledemo.com" -H "X-Apig-AppCode: xhrJVJKABSOxc7d***********FZL4gSHEXkCMQC"

为策略绑定API 单击策略名称，进入策略详情。 在API列表区域选择环境后，单击“绑定API”。 筛选API分组以及发布环境，勾选所需的API。 支持通过API名称或标签筛选API，标签为创建API时定义的标签。 单击“确定”，绑定完成。 如果单个API不需要绑定此策略，单击API所在行的“解绑”。 如果批量API不需要绑定此策略，则勾选待解绑的API，单击列表上方“解绑”。最多同时解绑1000个API。