华为云用户手册

约束与限制 同一个环境中，一个API只能被一个跨域共享策略绑定，但一个跨域共享策略可以绑定多个API。 同一API分组下，相同请求路径的所有API，只能绑定同一个跨域资源共享策略。 如果API开启了“支持CORS”功能的同时，也绑定了跨域资源共享策略，则以绑定的策略为准。 如果某个请求路径下有OPTIONS方法的API，则该请求路径下的所有API均不允许绑定跨域资源共享策略。 为策略绑定API时，API的请求方法必须为allow_methods中允许的请求方法。 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 策略的绑定、解绑、更新会实时生效，不需要重新发布API。 API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 如果策略与API有绑定关系，则策略无法执行删除操作。

脚本配置示例 { "allow_origin": "*", "allow_methods": "GET,POST,PUT", "allow_headers": "Content-Type,Accept,Accept-Ranges,Cache-Control", "expose_headers": "X-Request-Id,X-Apig-Latency", "max_age": 86400, "allow_credentials": true}

网关错误响应类型说明 API网关提供的错误响应类型见下表，其中响应状态码可以按实际需要做自定义修改。 表1 API网关的错误响应类型 错误说明 默认的响应状态码 详细说明 拒绝访问 403 拒绝访问，如触发配置的访问控制策略、或异常攻击检测拦截 自定义认证配置错误 500 自定义认证方异常，通信失败、返回异常响应等错误 自定义认证失败 500 自定义认证方返回认证失败 自定义认证身份来源错误 401 前端自定义认证的身份来源信息缺失或不合法错误 第三方认证配置错误 500 第三方认证方异常，通信失败、返回异常响应等错误 第三方认证失败 401 第三方认证方返回认证失败 第三方认证身份来源错误 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.apiName API名称 $context.appId API调用者的凭据对象ID $context.appName API调用者的凭据对象名称 $context.requestId 当次API调用生成请求ID $context.stage API调用的部署环境 $context.sourceIp API调用者的源地址 $context.reqPath API请求路径，不包含query参数 $context.reqUri API请求路径，包含query参数 $context.reqMethod API请求方法 $context.authorizer.frontend.property 前端自定义认证响应的context映射的指定键值对的字符串值 $context.authorizer.backend.property 后端自定义认证响应的context映射的指定键值对的字符串值 $context.error.message 当前网关错误响应的错误信息 $context.error.code 当前网关错误响应的错误码 $context.error.type 当前网关错误响应的错误类型

约束与限制 每个分组最多可新增4个网关响应。 最多支持10个响应头自定义，响应头的key支持数字、英文字母和下划线（1到128位），value可以引用运行时变量（可以引用的变量见API网关运行时可获取变量），value不能包含“[[”和“]]”。 不论是默认网关响应“default”或是您自定义的网关响应，响应类型范围固定不可修改。您可以修改每种响应的状态码，以及响应内容。 网关响应所定义的错误类型固定且不可修改，具体见网关错误响应类型说明。 响应内容支持调用API网关运行时变量（$context变量），具体见API网关运行时可获取变量。

x-apigateway-any-method 含义：API网关定义的API请求方法，用以匹配未指定定义的HTTP方法。 作用域：Path Item Object(2.0)/Path Item Object(3.0) 示例： paths: '/path': get: produces: - application/json responses: "200": description: "get response" x-apigateway-any-method: produces: - application/json responses: "200": description: "any response" 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-any-method 否 String API请求方法。 父主题： APIG的API设计文件扩展定义

APIG使用流程 API网关（API Gateway）是为您提供高性能、高可用、高安全的API托管服务，帮助您轻松构建、管理和部署任意规模的API。借助API网关的开放API和调用API功能，可以简单、快速、低成本、低风险地实现内部系统集成、业务能力开放。 开放API 企业或开发者通过API网关开放自身的服务与数据。 图1 API网关服务开放API 开放API的业务使用流程如下图所示。 图2 API网关服务开放API基本流程 创建实例 共享版无需购买实例，可直接进入共享版。 创建API分组 每个API都归属到某一个API分组下，在创建API前应提前创建API分组。 绑定 域名 在开放API前，您需要为API分组绑定一个独立域名，供API调用者访问API使用。 在绑定独立域名前，您可以使用系统为API分配的默认子域名进行API调试，每天最多可以访问默认子域名1000次。 创建API 把已有后端服务封装为标准RESTFul API，并对外开放。 API创建成功后，您可根据业务需求对API设置访问策略： 流控控制 流量控制可限制单位时间内API的被调用次数，保护后端服务。 访问控制 访问API的IP地址和账户，您可以通过设置IP地址或账户的黑白名单来拒绝/允许某个IP地址或账户访问API。 签名密钥 签名密钥用于后端服务验证API网关的身份，在API网关请求后端服务时，保障后端服务的安全。 调试API 验证 API服务 的功能是否正常可用。 发布API 把API发布到环境中，API只有在发布到环境后，才支持被调用。 调用API 企业或开发者如何获取并调用他人在API网关开放的API，减少开发时间与成本。 图3 API网关服务调用API 调用API的业务使用流程如下图所示。 图4 API网关服务调用API基本流程 获取API 获取API的请求信息，包括访问域名、请求协议、请求方法、请求路径以及认证方式等信息。 创建应用 使用APP认证的API，需要在API网关中创建一个应用，以生成应用ID和密钥对（AppKey、AppSecret）。将创建的应用绑定API后，使用APP认证调用API。 获取SDK 可通过SDK对AK/SK生成签名，并调用API。 调用API 通过获取API及API访问地址，调用API。根据API使用认证方式的不同，调用API时需要进行不同的认证鉴权操作。 父主题： 共享版操作指导（仅存量用户使用）

x-apigateway-backend-policies.conditions 含义：API网关定义的API后端策略条件。 作用域：x-apigateway-backend-policies 示例： 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 参数说明 参数 是否必选 类型 说明 type 是 String 策略条件类型，支持equal、enum、pattern。 value 是 String 策略条件值。 origin 是 String 策略条件输入来源，支持source、request。 parameter 否 String 策略条件输入来源为request时，请求入参的名称。 父主题： APIG的API设计文件扩展定义

操作场景 API可以同时提供给不同的环境调用，如生产、测试或开发。RELEASE是默认存在的环境，无需创建。且API网关提供环境变量功能，通过创建环境变量，实现在不同的环境定义不同的API调用路径。 环境变量是指在环境上创建可管理的一种变量，该变量固定在环境上。通过创建环境变量，实现同一个API，在不同环境中调用不同的后端服务。 当创建API时定义了变量标识，则需要在环境中添加变量。例如创建API时定义了变量名为“Path”，在环境1中创建了变量名“Path”，变量值“/Stage/test”，则API在发布到环境1时，使用“/Stage/test”代替“Path”，API调用者在环境1中调用此API时，后端服务请求Path为“/Stage/test”。在环境2中创建了变量名“Path”，变量值“/Stage/AA”，则API在发布到环境2时，使用“/Stage/AA”代替“Path”，API调用者在环境2中调用此API时，后端服务请求Path为“/Stage/AA”。 图1 环境变量 每个分组在任意一个环境中，最多创建50个变量。

前提条件 已有独立域名。可通过 域名注册服务 申请新的域名。 公网独立域名需要备案，未备案的独立域名无法被访问。备案时长需几个工作日，建议您提前进行备案。 共享版：已将独立域名CNAME解析到分组的子域名上，具体方法请参见增加CNAME类型记录集。 如果API分组中的API支持HTTPS请求协议，那么在独立域名中需要添加SSL证书，请您提前准备SSL证书。此证书不支持导入，您需要填写证书的名称、内容和密钥。

操作场景 开放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设计文件扩展定义

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