华为云用户手册

查看关键操作列表 通过 云审计 服务，您可以记录与API网关相关的操作事件，便于日后的查询、审计和回溯。 表1 云审计服务支持的API Gateway操作列表 操作名称 资源类型 事件名称 创建API分组 ApiGroup createApiGroup 删除API分组 ApiGroup deleteApiGroup 更新API分组 ApiGroup updateApiGroup 绑定 域名 ApiGroup createDomainBinding 修改安全传输协议 ApiGroup modifySecureTransmission 解绑域名 ApiGroup relieveDomainBinding 添加域名证书 ApiGroup addDomainCertificate 删除域名证书 ApiGroup deleteDomainCertificate 创建API Api createApi 删除API Api deleteApi 批量删除API Api batchDeleteApi 更新API Api updateApi 发布API Api publishApi 下线API Api offlineApi 批量发布/下线API Api batchPublishOrOfflineApi 切换API版本 Api switchApiVersion 根据版本号下线API Api offlineApiByVersion 调试API Api debugApi 创建环境 Environment createEnvironment 删除环境 Environment deleteEnvironment 更新环境 Environment updateEnvironment 创建环境变量 EnvVariable createEnvVariable 更新环境变量 EnvVariable updateEnvVariable 删除环境变量 EnvVariable deleteEnvVariable 创建应用 App createApp 删除应用 App deleteApp 更新应用 App updateApp 重置签名密钥 App resetAppSecret 客户端绑定API AppAuth grantAuth 客户端解绑API AppAuth relieveAuth 创建签名密钥 Signature createSignature 删除签名密钥 Signature deleteSignature 更新签名密钥 Signature updateSignature 绑定签名密钥 SignatureBinding createSignatureBinding 解绑签名密钥 SignatureBinding relieveSignatureBinding 创建访问控制 Acl createAcl 删除访问控制 Acl deleteAcl 批量删除访问控制 Acl batchDeleteAcl 更新访问控制 Acl updateAcl 增加流控黑名单 Acl addAclValue 删除流控黑名单 Acl deleteAclValue API绑定访问控制 AclBinding createAclBinding API解绑访问控制 AclBinding relieveAclBinding 批量解绑访问控制 AclBinding batchRelieveAclBinding 创建流控 Throttle createThrottle 删除流控 Throttle deleteThrottle 批量删除流控 Throttle batchDeleteThrottle 更新流控 Throttle updateThrottle 绑定流控 ThrottleBinding createThrottleBinding 解绑流控 ThrottleBinding relieveThrottleBinding 批量解绑流控 ThrottleBinding batchRelieveThrottleBinding 创建特殊流控 ThrottleSpecial createSpecialThrottle 删除特殊流控 ThrottleSpecial deleteSpecialThrottle 更新特殊流控 ThrottleSpecial updateSpecialThrottle 创建负载通道 Vpc createVpc 删除负载通道 Vpc deleteVpc 更新负载通道 Vpc updateVpc 增加负载通道成员 Vpc addVpcMember 删除负载通道成员 Vpc deleteVpcMember 导出单个API Swagger swaggerExportApi 批量导出API Swagger swaggerExportApiList 导出分组下所有API Swagger swaggerExportApiByGroup 导入API到新分组 Swagger swaggerImportApiToNewGroup 导入API到已有分组 Swagger swaggerImportApiToExistGroup 导出全部自定义后端 Swagger SwaggerExportLdApi 导入自定义后端 Swagger SwaggerImportLdApi 创建自定义认证 Authorizer createAuthorizer 删除自定义认证 Authorizer deleteAuthorizer 更新自定义认证 Authorizer updateAuthorizer 购买API分组 Market purchase 上架API分组 Market onsell 下架API分组 Market offsell 修改配额状态 Market changeStatus 锁定/解除锁定API分组 Market lockOrUnlock 冻结/解冻API分组 Market frozenOrUnfrozen 预订购API分组 Market reserve 退市 Market delist 退订 Market unsubscribe

APIG的API错误码说明 当调用API时，可能遇到下表中的错误码。如果遇到“APIGW”开头的错误码，请参见API网关错误码进行处理。 通过APIG接口管理API，发生错误时，产生的错误码请参考错误码。 使用APIG错误码时，请以错误码（如APIG.0101）为准，错误信息并非固定不变，有时会对错误信息进行优化修改。 表1 错误码 错误码 错误信息 HTTP状态码 语义 解决方案 APIG.0101 The API does not exist or has not been published in the environment. 404 API不存在或未发布到环境 检查调用API所使用的域名、请求方法、路径是否正确。 检查API是否发布。 检查域名解析是否正确。 检查API是否使用OPTIONS跨域请求，如果使用OPTIONS跨域请求，请在API中开启CORS。 具体操作请参见常见问题。 APIG.0101 The API does not exist. 404 API请求方法不存在 检查API请求方法是否与API定义的方法相同。 APIG.0103 The backend does not exist. 500 无法找到后端 联系技术支持。 APIG.0104 The plug-ins do not exist. 500 无法找到插件配置 联系技术支持。 APIG.0105 The backend configurations do not exist. 500 无法找到后端配置 联系技术支持。 APIG.0106 Orchestration error. 400 编排错误 检查API配置的前后端参数是否合理。 APIG.0107 The custom lua script encountered an unexpected error 500 Lua脚本发生未知错误 联系技术支持。 APIG.0201 API request error. 400 请求格式不合法 检查请求格式是否合法。 APIG.0201 Request entity too large. 413 请求body过大（大于12M） 减小请求body大小。 APIG.0201 Request URI too large. 414 请求URI过大（大于32K） 减小请求URI大小。 APIG.0201 Request headers too large. 494 请求头过大（单个请求头大于32K或所有请求头总长度大于128K） 减小请求头大小。 APIG.0201 Backend unavailable. 502 后端不可用 检查API配置的后端地址是否可用。 如果后端服务为E CS ，ECS配置的安全组规则是否拦截了API请求。 请求协议是否正确。 后端服务链接链路是否可通。 具体操作请参见常见问题。 APIG.0201 Backend timeout. 504 后端超时 编辑API增大超时时间，或缩小后端的处理时间。 APIG.0201 An unexpected error occurred 500 内部错误 联系技术支持。 APIG.0202 Backend unavailable 502 后端不可用 检查API配置的后端请求协议与后端服务请求协议是否一致。 APIG.0203 Backend timeout 504 后端超时 编辑API增大超时时间，或缩小后端的处理时间。 APIG.0204 SSL protocol is not supported: TLSv1.1 400 SSL协议版本不支持 使用支持的SSL协议版本，当前支持TLS1.1和TLS1.2，推荐使用TLS1.2。 APIG.0205 Verify client certificate failed 400 客户端证书校验失败 检查客户端证书是否正确。 APIG.0301 Incorrect IAM authentication information. 401 IAM认证信息错误 检查请求的方法、路径、查询参数、请求体和签名使用的方法、路径、查询参数、请求体是否一致；检查客户端机器时间是否正确。请参见常见问题。 APIG.0302 The IAM user is not authorized to access the API. 403 IAM用户不允许访问API 检查用户是否被黑白名单限制。 APIG.0303 Incorrect app authentication information. 401 APP认证信息错误 检查请求的方法、路径、查询参数、请求体和签名使用的方法、路径、查询参数、请求体是否一致；检查客户端机器时间是否正确。请参见常见问题。 APIG.0304 The app is not authorized to access the API. 403 APP不允许访问API 检查凭据是否绑定API，或API是否授权给凭据。 APIG.0305 Incorrect authentication information. 401 认证信息错误 检查认证信息是否正确。 APIG.0306 API access denied. 403 不允许访问API 检查是否授权访问API。 APIG.0307 The token must be updated. 401 token需要更新 重新从IAM获取token。 APIG.0308 The throttling threshold has been reached. 429 超出流控值限制 等待流控刷新后访问。如果触发调试域名的单日请求数上限，请绑定独立域名。 APIG.0310 The project is unavailable. 403 project不可使用 使用其他project访问。 APIG.0311 Incorrect debugging authentication information. 401 调试认证信息错误 联系技术支持。 APIG.0312 Incorrect third-party authentication information,auth fail 401 第三方认证信息错误，认证失败 检查身份信息是否正确。 APIG.0313 Incorrect third-party authentication information,identities error 401 第三方认证信息错误，身份错误 检查请求中身份信息与第三方认证插件中身份来源设置是否一致。 APIG.0314 Incorrect third-party authentication information,access deny 403 第三方认证信息错误，访问拒绝 联系技术支持确认请求来源是否为业务请求，如果是，则提高第三方认证插件的防爆力拦截阈值以解决。 APIG.0401 Unknown client IP address. 403 无法识别客户端IP地址 联系技术支持。 APIG.0402 The IP address is not authorized to access the API. 403 IP地址不允许访问 检查IP地址是否被API的访问控制限制。 APIG.0403 The IP address cannot be accessed. 403 IP地址不允许访问 检查IP地址是否被实例级访问控制限制。 APIG.0404 Access to the backend IP address has been denied. 403 后端IP不允许访问 后端IP地址或后端域名对应的IP地址不允许访问。 APIG.0405 The app is not accessed from a trusted IP address. 403 未从受信任的IP地址访问应用程序 检查源IP是否在访问控制策略中配置了允许或者拒绝。 APIG.0501 The app quota has been used up. 405 APP已经超出配额 或云市场调用次数用完 购买APP配额。 或重新购买云市场调用次数。 APIG.0502 The app has been frozen. 405 APP被冻结 余额不足。 APIG.0601 Internal server error. 500 内部错误 联系技术支持。 APIG.0602 Bad request. 400 非法请求 检查请求是否合法。 APIG.0605 Domain name resolution failed. 500 域名解析失败 检查域名拼写，以及域名是否绑定了正确的后端地址。 APIG.0606 Failed to load the API configurations. 500 未加载API配置 联系技术支持。 APIG.0607 The following protocol is supported: {xxx} 400 协议不被允许，允许的协议是xxx。 注意：xxx以实际响应中的内容为准。 改用支持的协议（HTTP/HTTPS）访问。 APIG.0608 Failed to obtain the admin token. 500 无法获取管理账户 联系技术支持。 APIG.0609 The VPC backend does not exist. 500 找不到负载后端 联系技术支持。 APIG.0610 No backend available. 502 没有可连接的后端 检查所有后端是否可用，如调用信息与实际配置是否一致。 APIG.0611 The backend port does not exist. 500 后端端口未找到 联系技术支持。 APIG.0612 An API cannot call itself. 500 API调用自身 修改API后端配置，递归调用层数不能超过10层。 APIG.0613 The IAM service is currently unavailable. 503 IAM服务暂时不可用 联系技术支持。 APIG.0615 Incorrect third-party authentication VPC information 500 获取第三方鉴权负载通道节点失败 检查第三方认证的负载通道配置是否正确。 APIG.0616 Incorrect third-party authentication request information 500 连接第三方鉴权服务失败 检查第三方认证服务是否正常。 APIG.0617 Incorrect third-party authentication response information 500 获取第三方鉴权服务响应失败 检查第三方认证服务是否正常。 APIG.0705 Backend signature calculation failed. 500 计算后端签名失败 联系技术支持。 APIG.0802 The IAM user is forbidden in the currently selected region 403 该IAM用户在当前region中被禁用 联系技术支持。 APIG.2102 PublicKey is null 400 签名密钥未找到 联系技术支持。 APIG.2201 Appkey or SecretKey is invalid 400 Appkey或SecretKey不合法 检查请求的Appkey或SecretKey是否正确。 APIG.2202 Refresh token is invalid 400 Refresh token不合法 检查Refresh token是否正确。 APIG.2203 Access token is invalid 400 Access token不合法 检查Access token是否正确。 APIG.2204 ContentType invalid 400 ContentType不合法 检查ContentType是否正确 APIG.2205 Auth parameter invalid 400 认证参数不合法 检查认证参数是否正确。 APIG.2206 Auth method invalid 400 认证方法不合法 检查认证方法是否正确。 APIG.2208 The length of through_data is out of range 400 through_data超长 through_data长度上限为300，根据实际情况调整through_data内容。 APIG.2209 The value of grant_type is not in enum List 400 grant_type的值不合法 grant_type只支持client_credentials、refresh_token，根据实际情况修改。 APIG.2210 Lack of grant_type 400 缺少授权类型 添加grant_type。 APIG.2211 Lack of client_id 400 缺少客户端ID 添加客户端ID。 APIG.2212 Lack of client_secret 400 缺少客户端密钥 添加客户端密钥。 APIG.2213 Lack of refresh_token 400 缺少refresh token 联系技术支持。 APIG.1001 Refresh token is expired 401 Refresh token过期 重新获取refresh token。 APIG.1002 Access token is expired 401 Access token过期 重新获取access token。 APIG.1003 App not match refresh token 401 App与refresh token不匹配 检查client_id是否正确。 APIG.1004 App not exist 401 App不存在 检查access token是否正确。 APIG.1009 AppKey or AppSecret is invalid 400 AppKey或AppSecret不合法 检查请求的AppKey或AppSecret是否与凭据的Key或Secret相同。 父主题： 调用API

x-apigateway-cors 含义：API网关定义的API请求是否支持跨域。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: x-apigateway-cors: true 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-cors 是 boolean 是否支持开启跨域请求的标识。 true：支持。 false：不支持。 开启跨域访问的API请求，响应会增加如下头域： 头域名称 头域值 描述 Access-Control-Max-Age 172800 预检响应最大缓存时间。 单位：s。 Access-Control-Allow-Origin * 允许任何域。 Access-Control-Allow-Headers X-Sdk-Date，X-Sdk-Nonce，X-Proxy-Signed-Headers，X-Sdk-Content-Sha256，X-Forwarded-For，Authorization，Content-Type，Accept，Accept-Ranges，Cache-Control，Range 正式请求允许的头域。 Access-Control-Allow-Methods GET，POST，PUT，DELETE，HEAD，OPTIONS，PATCH 正式请求允许的方法。 父主题： APIG的API设计文件扩展定义

x-apigateway-backend 含义：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" 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-backend 是 String API后端服务定义。 type 是 String 后端服务类型，支持HTTP、HTTP-VPC、FUNCTION、MOCK。 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类型后端服务定义。 父主题： APIG的API设计文件扩展定义

x-apigateway-sample 含义： 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: [] x-apigateway-pass-through: always x-apigateway-sample: 'test-sample' name: test in: query required: true 父主题： APIG的API设计文件扩展定义

x-apigateway-ratelimits.policy.special 含义：特殊流控策略定义。 作用域：x-apigateway-ratelimits.policy 示例： x-apigateway-ratelimits: customRatelimitName: api-limit: 200 app-limit: 200 user-limit: 200 ip-limit: 200 interval: 1 unit: MINUTE shared: false special: - type: USER limit: 100 instance: xxxxxxxx 表1 参数说明 参数 是否必选 类型 说明 type 是 String 特殊流控策略类型，支持APP、USER。 limit 是 Number API的访问次数。 instance 是 String 特殊APP或USER的对象标识。 父主题： APIG的API设计文件扩展定义

查看关键操作列表 通过云审计服务，您可以记录与API网关相关的操作事件，便于日后的查询、审计和回溯。API Gateway操作列表见下表： 表1 云审计服务支持的API Gateway操作列表 操作名称 资源类型 事件名称 创建API分组 ApiGroup createApiGroup 修改API分组 ApiGroup updateApiGroup 删除API分组 ApiGroup deleteApiGroup 校验API分组名称是否存在 Swagger CheckApiGroups 创建环境 Environment createEnvironment 修改环境 Environment updateEnvironment 删除环境 Environment deleteEnvironment 新建变量 EnvVariable CreateEnvironmentVariable 删除变量 EnvVariable DeleteEnvironmentVariable 修改变量 EnvVariable UpdateEnvironmentVariable 创建流控策略 Throttle CreateRequestThrottlingPolicy 修改流控策略 Throttle UpdateRequestThrottlingPolicy 删除流控策略 Throttle DeleteRequestThrottlingPolicy 创建API Api CreateApi 修改API Api UpdateApi 删除API Api DeleteApi 发布或下线API Api CreateOrDeletePublishRecordForApi 校验API定义 Api CheckApis 调试API Api DebugApi 批量发布/下线API Api BatchPublishOrOfflineApi 切换API版本 Api ChangeApiVersion 根据版本号下线API Api DeleteApiByVersionId 创建签名密钥 Signature CreateSignatureKey 修改签名密钥 Signature UpdateSignatureKey 删除签名密钥 Signature DeleteSignatureKey 绑定签名密钥 SignatureBinding AssociateSignatureKey 解除API与签名密钥的绑定关系 SignatureBinding DisassociateSignatureKey 绑定流控策略 ThrottleBinding AssociateRequestThrottlingPolicy 解除API与流控策略的绑定关系 ThrottleBinding DisassociateRequestThrottlingPolicy 批量解绑流控策略 ThrottleBinding BatchDisassociateThrottlingPolicy 创建特殊设置 ThrottleSpecial CreateSpecialThrottlingConfiguration 修改特殊流控 ThrottleSpecial UpdateSpecialThrottlingConfiguration 删除特殊流控 ThrottleSpecial DeleteSpecialThrottlingConfiguration APP授权 AppAuth CreateAuthorizingApps 解除授权 AppAuth CancelingAuthorization 绑定域名 ApiGroup AssociateDomain 绑定域名证书 ApiGroup AssociateCertificate 修改域名 ApiGroup UpdateDomain 解绑域名 ApiGroup DisassociateDomain 删除域名证书 ApiGroup DisassociateCertificate 创建ACL策略 Acl CreateAclStrategy 修改ACL策略 Acl UpdateAclStrategy 删除ACL策略 Acl DeleteAcl 批量删除ACL策略 Acl BatchDeleteAclV2 将API与ACL策略进行绑定 AclBinding CreateApiAclBinding 解除API与ACL策略的绑定 AclBinding DeleteApiAclBinding 批量解除API与ACL策略的绑定 AclBinding BatchDeleteApiAclBinding 创建自定义认证 Authorizer CreateCustomAuthorizer 修改自定义认证 Authorizer UpdateCustomAuthorizer 删除自定义认证 Authorizer DeleteCustomAuthorizer 导出API Swagger swaggerExportApiToGroup 导入API Swagger ImportApiDefinitions 创建VPC通道 Vpc CreateVpcChannel 更新VPC通道 Vpc UpdateVpcChannel 删除VPC通道 Vpc DeleteVpcChannel 添加或更新后端实例 Vpc AddingBackendInstances 更新后端实例 Vpc UpdateBackendInstances 删除后端实例 Vpc DeleteBackendInstance 批量修改后端服务器状态可用 Vpc BatchEnableMembers 批量修改后端服务器状态不可用 Vpc BatchDisableMembers 修改VPC通道健康检查 Vpc UpdateHealthCheck 添加或更新VPC通道后端服务器组 Vpc CreateMemberGroup 删除VPC通道后端服务器组 Vpc DeleteMemberGroup 更新VPC通道后端服务器组 Vpc UpdateMemberGroup 创建分组自定义响应 ApiGroup CreateGatewayResponse 修改分组自定义响应 ApiGroup UpdateGatewayResponse 删除分组自定义响应 ApiGroup DeleteGatewayResponse 修改分组下指定错误类型的自定义响应 ApiGroup UpdateGatewayResponseType 删除分组指定错误类型的自定义响应配置 ApiGroup DeleteGatewayResponseType 实例配置特性 Feature CreateFeatureV2 创建专享版实例（按需） Instance CreateInstance 更新专享版实例 Instance UpdateInstance 实例更新或绑定EIP Instance AddEip 实例解绑EIP Instance RemoveEip 开启实例公网出口 Instance AddEngressEip 更新实例出公网带宽 Instance UpdateEngressEip 关闭实例公网出口 Instance RemoveEngressEip 开启实例公网入口 Instance AddIngressEip 更新实例入公网带宽 Instance UpdateIngressEip 关闭实例公网入口 Instance RemoveIngressEip 删除专享版实例 Instance DeleteInstances 创建专享版实例（包周期） Instance CreateOrder 创建包周期规格变更订单 Instance CreatePrepayResize 按需规格变更 Instance CreatePostPayResizeOrder 接受或拒绝终端节点连接 vpc-endpoint AcceptOrRejectEndpointConnections 批量添加实例终端节点连接白名单 vpc-endpoint AddEndpointPermissions 批量删除实例终端节点连接白名单 vpc-endpoint DeleteEndpointPermissions 批量添加或删除单个实例的标签 Instance BatchCreateOrDeleteInstanceTags 导入微服务 Microservice ImportMicroservice 创建SSL证书 SslCertificate CreateCertificate 域名绑定SSL证书 ApiGroup BatchAssociateCerts 域名解绑SSL证书 ApiGroup BatchDisassociateCerts 删除SSL证书 SslCertificate DeleteCertificate 修改SSL证书 SslCertificate UpdateCertificate SSL证书绑定域名 Certificate BatchAssociateDomains SSL证书解绑域名 Certificate BatchDisassociateDomains 创建插件 Plugin CreatePlugin 修改插件 Plugin UpdatePlugin 删除插件 Plugin DeletePlugin 插件绑定API Plugin AttachApiToPlugin API绑定插件 Plugin AttachPluginToApi 解除绑定插件的API Plugin DetachApiFromPlugin 解除绑定API的插件 Plugin DetachPluginFromApi 创建APP App CreateAnApp 修改APP App UpdateApp 删除APP App DeleteAppV2 重置密钥 App ResettingAppSecret 校验APP App CheckApp 创建APP Code AppCode CreateAppCode 自动生成APP Code AppCode CreateAppCodeAuto 删除APP Code AppCode DeleteAppCode 设置APP的访问控制 AppAcl UpdateAppAcl 删除APP的访问控制 AppAcl DeleteAppAcl 创建凭据配额 AppQuota CreateAppQuota 修改凭据配额 AppQuota UpdateAppQuota 删除凭据配额 AppQuota DeleteAppQuota 凭据配额绑定凭据列表 AppQuotaBinding AssociateAppsForAppQuota 解除凭据配额和凭据的绑定 AppQuotaBinding DisassociateAppQuotaWithApp

脚本配置示例 { "response_headers": [ { "name": "test", "value": "test", "action": "append" }, { "name": "test1", "value": "test1", "action": "override" } ]}

x-apigateway-access-controls 含义：访问控制策略名称与关联策略映射。 作用域：Swagger Object 示例： x-apigateway-access-controls: customAccessControlName: acl-type: "DENY" entity-type: "IP" value: 127.0.0.1,192.168.0.1/16 表1 参数说明 参数 是否必选 类型 说明 customAccessControlName 否 x-apigateway-access-controls.policy 指定名称的访问控制策略。 如果使用该策略，需要将x-apigateway-access-control属性值引用为该策略名称。 父主题： APIG的API设计文件扩展定义

约束与限制 同一个环境中，一个API只能被一个HTTP响应头策略绑定，但一个HTTP响应头策略可以绑定多个API。 无法修改API网关增加的系统响应头（x-apig-*，x-request-id等），包括API网关提供的CORS功能增加的响应头。 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。 策略的绑定、解绑、更新会实时生效，不需要重新发布API。 API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。 如果策略与API有绑定关系，则策略无法执行删除操作。

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

x-apigateway-pass-through 含义：API的请求参数是否透传。always为是，never为否。 作用域： Operation Object(2.0)/Operation Object(3.0) 示例： paths: /: get: parameters: - maximum: 0 minimum: 0 maxLength: 0 minLength: 0 type: string x-apigateway-orchestrations: [] x-apigateway-pass-through: always x-apigateway-sample: '' name: test in: query required: true 父主题： APIG的API设计文件扩展定义

x-apigateway-is-send-fg-body-base64 含义：是否对与FunctionGraph交互场景的请求体进行Base64编码，boolean类型。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: "x-apigateway-is-send-fg-body-base64": true 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-is-send-fg-body-base64 否 boolean 是否对与FunctionGraph交互场景的请求体进行Base64编码。 true：编码。 false：不编码。 父主题： APIG的API设计文件扩展定义

x-apigateway-ratelimit 含义：引用流控策略。 作用域：Operation Object(2.0)/Operation Object(3.0) 示例： paths: '/path': get: x-apigateway-ratelimit: 'customRatelimitName' 表1 参数说明 参数 是否必选 类型 说明 x-apigateway-ratelimit 否 String 流控策略。 父主题： APIG的API设计文件扩展定义

调用API 本章节仅提供请求地址和认证参数的配置指导，客户端的其他参数配置需要用户自行调整，如超时配置、SSL配置等。如果客户端参数配置错误会导致业务受损，建议参考业界标准进行配置。 构造API请求，示例如下： POST https://{Address}/{Path}?{Query}{Header}{ {Body}} POST：请求方法，需替换为获取API的调用信息中获取的请求方法。 {Address}：请求地址，需替换为获取API的调用信息中获取的域名地址。 API调用场景 API请求参数配置 使用域名调用API 使用服务分配的调试域名或服务绑定的域名调用API，无需另外配置。 使用IP调用API 使用IP地址直接调用API，需要在请求消息中添加Header参数“host”。 {Path}：请求路径，需替换为获取API的调用信息中获取的请求路径。 {Query}：查询参数，可选，格式为“参数名=参数取值”，例如limit=10，多个查询参数之间使用“&”隔开。需根据获取API的调用信息中获取的请求参数进行设置。 {Header}：请求头参数，格式为“参数名: 参数取值”，例如Content-Type: application/json。需根据获取API的调用信息中获取的请求参数进行设置。 {Body}：请求消息体，JSON格式。需根据获取API的调用信息中获取的请求体内容描述进行设置。 为API请求添加认证信息。 API认证方式 API请求参数配置 APP认证（签名认证） 使用获取的SDK对API请求进行签名，具体请参考使用APP认证调用API。 APP认证（简易认证） 在API请求中添加Header参数“X-Apig-AppCode”，参数值为获取API的调用信息中获取到的AppCode。具体请参考快速入门。 IAM认证（Token认证） 先获取云服务平台的认证Token，然后在API请求中添加Header参数“X-Auth-Token”，参数值为认证Token，具体请参考Token认证。 IAM认证（AK/SK认证） 使用获取的SDK对API请求进行签名，具体请参考AK/SK认证。 自定义认证 根据自定义认证的定义，在API请求参数中携带相关认证信息进行认证。 无认证 无需认证，可直接调用API。

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

约束与限制 同一个环境中，一个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设计文件扩展定义

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

操作场景 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个变量。

操作场景 开放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。