华为云API网关APIG完全对接指南：从实例创建到生产级API托管

apphuang2026年06月17日 10:01:279

引言：为什么需要API网关

在现代微服务架构中，API网关已经成为系统间通信的核心枢纽。华为云API网关APIG（API Gateway）是一款全托管的API托管服务，帮助开发者轻松构建、管理和部署任意规模的API。无论是内部系统解耦、业务能力开放，还是API商业化变现，APIG都能提供高性能、高可用、高安全的支撑。

然而，对于初次接触APIG的开发者来说，从实例创建到API开放，再到客户端调用，整个链路涉及IAM权限、VPC网络、API分组、域名绑定、认证鉴权、流量控制等多个环节，容易让人感到困惑。本文将以生产实践为导向，系统梳理华为云APIG的完整对接流程，力求做到每一步都有据可依、每一行代码都可运行。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

一、APIG版本选型：专享版与共享版

在开始对接之前，首先需要明确APIG的版本选择。华为云API网关当前提供专享版和共享版两种服务方式。共享版API即开即用，无需购买实例，但需要特别注意的是：共享版功能已下线，不支持新用户使用，当前仅存量用户可以使用。对于新用户而言，唯一的选择就是专享版。

专享版API网关需要购买专享版实例，并在实例中管理API。实例是一个独立的资源空间，所有的操作都是在实例内进行，不同实例间的资源相互隔离。专享版的核心优势在于：常用于企业内部系统解耦，各服务部署在云上的VPC内，服务之间以RESTful API方式通信，通信链路在VPC内部进行，网络安全得到进一步保障。每个专享版实例都拥有独立的公网入口IP和公网出口IP，以及VPC内的入口私有IP和多个出口私有IP。

因此，本文后续的所有内容均以APIG专享版为基础进行展开。

二、对接前的准备工作

2.1 IAM权限配置

在使用APIG之前，需要通过IAM（统一身份认证）服务创建用户并授权使用API网关。如果系统预置的APIG权限不满足授权要求，也可以创建自定义策略。

具体权限要求如下：如果使用系统角色相关权限，需要同时拥有APIG Administrator和VPC Administrator权限才能创建实例；如果使用系统策略，则拥有APIG FullAccess权限即可。对于需要精细管理云上资源的场景，建议使用IAM服务创建IAM用户及用户组，并授权，以使得IAM用户获得具体的操作权限。

2.2 网络环境准备

APIG实例必须部署在VPC（虚拟私有云）中。在创建APIG实例前，需要确保已存在可用的VPC和子网。APIG实例可以使用当前账号下已创建的VPC和子网，也可以使用新创建的VPC和子网。需要注意的是：创建的VPC与APIG实例必须在相同的区域。

此外，还需要准备安全组。APIG实例可以使用当前账号下已创建的安全组，也可以使用新创建的安全组。在安全组配置方面，入方向需要放开当前实例所关联的VPC网段的1026（TCP）端口。值得注意的是，除墨西哥城一、北京一区域外，在其他区域创建实例后安全组不生效，如需禁用部分IP请使用访问控制策略。

2.3 账户准备

在创建APIG实例前，需要确保账户有足够金额。如果账户余额不足，需要先进行充值。同时，需要完成华为云的注册和实名认证。

三、创建APIG专享版实例

准备工作完成后，即可进入APIG控制台创建专享版实例。实例是APIG的核心资源载体，只有创建了实例，才能开放API并对外提供服务。

创建实例时需要配置以下核心参数：

计费模式：专享版支持按需计费（后付费，按实际使用时长计费，秒级计费，按小时结算）和包年包月两种模式
规格选择：根据实际业务需求选择实例规格，不同规格对应不同的性能指标
网络配置：选择已准备的VPC和子网

实例创建完成后，还可以进行以下扩展配置：配置实例参数调整组件的相关功能、配置APIG实例标签分组标记实例资源、配置APIG的终端节点信息连接终端节点服务。

四、开放API的核心流程

实例创建完成后，就可以开始开放API了。开放API是APIG最核心的功能，将成熟的业务能力（如服务、数据等）作为后端服务，在API网关中开放API，提供给API调用者使用。

4.1 创建API分组

每个API都归属到某一个API分组下，在创建API前应提前创建API分组。API分组是API的逻辑集合，便于统一管理和授权。在APIG控制台的左侧导航栏选择"API管理 > API分组"，即可创建新的分组。

4.2 绑定独立域名

在开放API前，需要为API分组绑定一个独立域名，供API调用者访问API使用。在绑定独立域名前，可以使用系统为API分配的默认子域名进行API调试，但每天最多可以访问默认子域名1000次。

如果API的前端定义中的请求协议支持HTTPS，则API所属分组在绑定独立域名后，还需为独立域名添加SSL证书。SSL证书是进行数据传输加密和身份证明的证书。

4.3 创建API

创建API是将已有后端服务封装为标准RESTful API并对外开放的过程。在APIG控制台的左侧导航栏选择"API管理 > API列表"，单击"创建API"进入配置页面。

创建API主要分为两大步骤：

第一步：前端配置

前端配置包括：

基本信息：API名称、所属分组、版本等
前端定义：请求方法（默认GET）、请求协议（默认HTTPS）、请求路径等
安全配置：选择安全认证方式

APIG支持多种安全认证方式：

APP认证：使用凭据的Key和Secret进行API请求的安全认证
IAM认证：使用华为云IAM服务的Token进行认证
自定义认证：借助函数工作流服务实现自己的认证系统
无认证：不进行认证（不推荐用于生产环境）

此外，还支持双重认证，即APP认证或IAM认证与自定义认证结合使用。

第二步：后端配置

后端配置包括：

默认后端：设置后端服务类型（如HTTP、HTTPS、Mock、FunctionGraph等）
策略后端：通过不同的策略条件，将API请求转发到不同的后端服务中

后端服务类型支持多种选择：

Mock类型：用于调试，直接返回预设的Mock结果
HTTP/HTTPS：对接传统的HTTP后端服务
FunctionGraph：对接华为云函数工作流，实现Serverless架构
gRPC：支持gRPC服务的路由转发
WebSocket：支持WebSocket API，实现全双工通信

4.4 调试API

API创建完成后，在发布之前应该先进行调试，验证API服务的功能是否正常可用。APIG控制台提供了在线调试功能，可以模拟API请求并查看返回结果，帮助开发者快速定位配置问题。

4.5 发布API

调试通过后，需要将API发布到环境中，API只有在发布到环境后，才支持被调用。APIG支持多环境管理（如开发、测试、生产），可以根据需要将API发布到不同的环境。

五、调用API的完整流程

API发布后，API调用者就可以开始调用API了。调用API的流程与API的认证方式密切相关。

5.1 获取API信息

调用者首先需要获取API的请求信息，包括访问域名、请求协议、请求方法、请求路径以及认证方式等。

5.2 APP认证方式

对于使用APP认证的API，调用者需要在API网关中创建一个凭据，以生成密钥对（Key、Secret）。Key唯一且不可重置，支持重置Secret。将创建的凭据绑定API后，即可使用APP认证调用API。

APP认证支持两种调用方式：

密钥认证：使用凭据的Key和Secret对请求进行签名
简易认证：使用凭据的AppCode进行认证，仅支持HTTPS或GRPCS方式调用API

以简易认证为例，快速调用流程如下：创建一个凭据，并添加一个AppCode作为调用API的凭证，然后使用接口测试工具，通过校验AppCode来实现对API的调用。

5.3 IAM认证方式

对于使用IAM认证的API，调用者需要使用华为云IAM服务的Token进行认证。Token的获取需要提供AK/SK（访问密钥），调用云服务API时需要增加请求消息头参数X-ProjectId。

5.4 自定义认证方式

自定义认证需要借助函数工作流服务实现。用户在函数工作流中创建自定义认证函数，APIG调用该函数，实现自定义认证。具体步骤为：

在FunctionGraph中编写自定义认证函数，定义所需的认证信息
在APIG中创建一个自定义认证，将函数服务接入APIG
在API的前端设置中选择自定义认证

自定义认证分为前端自定义认证和后端自定义认证两类。前端自定义认证指APIG利用校验函数对收到的API请求进行安全认证；后端自定义认证则用于后端服务对API网关的身份验证。

六、签名认证的代码实现

签名认证是APIG调用中最核心的技术环节之一。无论是APP认证还是IAM认证（AK/SK认证），其签名生成的方式是相同的：用AK代替APP认证中的AppKey，SK替换APP认证中的AppSecret，即可完成签名和请求。

华为云APIG支持多种编程语言的签名SDK，包括Java、Go、Python、C#、JavaScript、PHP、C++、C、Android等。签名算法推荐使用V11算法。客户端需要注意本地时间与时钟服务器的同步，避免请求消息头X-Sdk-Date的值出现较大误差——API网关会校验该时间值与网关收到请求的时间差，如果时间差大于15分钟，API网关将拒绝请求。

6.1 Python签名认证示例

以下是一个使用Python进行AK/SK签名认证的完整示例：

import requests
import time
import hashlib
import hmac
from datetime import datetime

# 配置AK/SK
AK = "your-access-key-id"
SK = "your-secret-access-key"

# 请求信息
method = "GET"
url = "https://your-api-gateway-domain.com/api/path"
headers = {}
query_params = {}
body = ""

def sign_request(method, url, headers, query_params, body, ak, sk):
    # 构建待签名字符串
    now = datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
    headers["X-Sdk-Date"] = now
    
    # 构建规范请求
    canonical_uri = "/" + "/".join(url.split("/")[3:])
    canonical_query = "&".join([f"{k}={v}" for k, v in sorted(query_params.items())])
    canonical_headers = f"host:{url.split('//')[1].split('/')[0]}\n" + f"x-sdk-date:{now}\n"
    signed_headers = "host;x-sdk-date"
    
    if body:
        payload_hash = hashlib.sha256(body.encode('utf-8')).hexdigest()
    else:
        payload_hash = hashlib.sha256("".encode('utf-8')).hexdigest()
    
    canonical_request = f"{method}\n{canonical_uri}\n{canonical_query}\n{canonical_headers}\n{signed_headers}\n{payload_hash}"
    
    # 构建待签名字符串
    algorithm = "SDK-HMAC-SHA256"
    credential_scope = now[:8] + "/" + "region" + "/" + "service" + "/sdk_request"
    string_to_sign = f"{algorithm}\n{now}\n{credential_scope}\n{hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()}"
    
    # 计算签名
    signing_key = hmac.new(sk.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest()
    
    # 构建Authorization头
    headers["Authorization"] = f"{algorithm} Access={ak}, SignedHeaders={signed_headers}, Signature={signing_key}"
    
    return headers

# 执行签名并发送请求
signed_headers = sign_request(method, url, headers, query_params, body, AK, SK)
response = requests.get(url, headers=signed_headers, params=query_params)
print(response.status_code)
print(response.text)

6.2 Java签名认证示例

Java开发者可以通过导入APIG的Java SDK来实现签名认证。核心步骤如下：

下载API网关签名工具和Java SDK
创建Java工程，将解压出来的JAR引用到依赖路径中
创建用于签名的请求com.cloud.sdk.DefaultRequest

SDK中提供了多个Demo示例，包括WebSocketDemoV11.java、OkHttpDemoV11.java、LargeFileUploadDemoV11.java、HttpClientDemoV11.java等。

七、插件策略与高级配置

APIG提供了丰富的插件策略，帮助开发者对API进行精细化管理。

7.1 流量控制2.0

流量控制可限制单位时间内API的被调用次数，保护后端服务。APIG在传统流量控制策略的基础上提供了插件策略（流量控制2.0），通过制定更加精细的方案来进行流控。

流量控制2.0支持三种流控维度：

基础流控：可以对API、用户、凭据、源IP进行多维度流控
参数流控：针对某一请求参数进行流控
特殊流控：基于基础流控的特殊流控

配置流量控制2.0策略的流程为：创建策略 → 配置基础流控 → 配置参数流控 → 配置特殊流控 → 绑定API。需要注意的是，同一个环境中，一个API只能被一个流量控制2.0策略绑定，但一个流量控制2.0策略可以绑定多个API。如果API未绑定流量控制2.0策略，流控限制值为实例配置参数中ratelimit_api_limits的参数运行值。

7.2 签名密钥

签名密钥用于后端服务验证API网关的身份，在API网关请求后端服务时，保障后端服务的安全。签名密钥由一对Key和Secret组成，需要绑定到API才能生效。

使用流程为：

在控制台创建签名密钥
将签名密钥绑定到已发布的API上
API网关将签名后的请求发送到后端服务，Authorization头中包含签名信息
后端服务使用同样的方式进行签名，比对签名结果和API网关传过来的Authorization头中签名是否一致来校验API的合法性

不同签名密钥可以绑定到不同环境下的同一个API，但同一环境下一个API只能绑定一个签名密钥。

7.3 访问控制

访问控制策略可以通过设置IP地址或账户的黑白名单来拒绝或允许某个IP地址或账户访问API。这为API的安全防护提供了额外的保障层。

7.4 JWT认证

API网关的JWT认证策略支持从Header、Query、Cookie多种位置设置Token，通过校验Token实现身份认证。用户还可以通过设置JWKS_URI远程服务地址，通过定期更换该地址返回的公钥，实现无缝密钥轮转。

八、常见问题与排错

在实际对接和使用APIG的过程中，开发者经常会遇到一些典型问题，以下汇总了常见错误及排查思路。

8.1 后端超时（APIG.0201）

错误信息：Backend timeout。API网关请求维持50秒后未收到返回结果，会返回此错误信息。排查思路：

检查后端服务是否正常运行
检查数据服务访问日志，确认是否有数据返回
优化后端处理逻辑，缩短处理时间
适当增大超时时间配置

8.2 API不存在或未发布（APIG.0101）

错误信息：The API does not exist or has not been published in the environment。排查思路：

检查调用API所使用的域名、请求方法、路径是否正确
确认API是否已发布到对应的环境
检查URL中是否缺少project_id等必要参数

8.3 APP认证信息错误（401）

错误信息：APP认证信息错误。排查思路：

检查请求的方法、路径、查询参数、请求体和签名使用的方法、路径、查询参数、请求体是否一致
检查客户端机器时间是否正确（时间差应小于15分钟）
参考APP认证调用API的文档检查签名代码的问题

8.4 Token解密失败（APIG.0301）

错误信息：Incorrect IAM authentication information: decrypt token fail。排查思路：

检查Token是否过期
检查获取Token的方法和请求体信息是否正确完整
检查获取Token的环境与调用的环境是否一致，是否跨区
检查账号权限，是否欠费或被冻结

8.5 后端IP不允许访问（403）

错误信息：后端IP不允许访问。排查思路：检查后端IP地址或后端域名对应的IP地址是否被黑/白名单限制，或检查对应后端IP是否存在。

九、生产环境最佳实践

基于APIG的常见应用场景，以下是一些生产环境的最佳实践建议：

安全最佳实践：企业为了保护APIG及后端服务器免受恶意攻击，可在APIG和外部网络之间部署WAF。当用户在公网中调用APIG上公开的业务API时，会存在DDoS攻击风险，为防范DDoS攻击，华为云提供了DDoS防护服务。此外，APIG专享版实例中如果存在API安全认证为"无认证"，则视为不合规。

网络规划：当用户后端服务器所在的VPC与创建实例所选择的VPC处于不同的场景时，需要通过跨VPC对接开放后端服务。使用专享版API网关可以为本地数据中心搭建一条与API网关所绑定的华为云VPC之间的专线。

混合架构：APIG支持与云容器引擎CCE中的工作负载以及微服务集成，通过API网关将服务能力以API形式对外开放。同时，APIG也支持对接FunctionGraph函数作为后端服务，实现高效集成。

协议升级：当用户的API采用HTTP协议访问时，由于HTTP没有传输安全与认证安全保障，可以使用API网关的重定向功能将API升级为安全的HTTPS协议访问，同时兼容已有的HTTP协议。

共享版迁移：对于仍在使用APIG共享版的老用户，由于共享版即将退市，需要将共享版上已有资源迁移到专享版上继续使用。迁移时需要注意公网出入口和内网出入口的变化，及时修改相关的网络安全策略。

十、总结

华为云API网关APIG是一个功能强大的API托管服务平台。从实例创建到API开放，从签名认证到流量控制，APIG提供了完整的API生命周期管理能力。本文系统梳理了APIG的对接使用全流程，涵盖了IAM权限配置、VPC网络规划、实例创建、API分组与域名绑定、API前端后端配置、调试发布、多种认证方式的调用、签名认证的代码实现、插件策略配置以及常见问题排错等核心环节。

掌握APIG的对接使用，不仅能够帮助企业快速实现内部系统集成和业务能力开放，更能为API的商业化变现奠定坚实的技术基础。希望本文能够成为开发者对接华为云APIG的实用参考。

常见问题解答

问1：APIG专享版和共享版有什么区别？新用户应该选择哪个？

答：共享版API即开即用，无需购买实例，但功能已下线，不支持新用户使用。专享版需要购买实例，资源隔离、安全性更高，支持VPC内部通信。新用户只能选择专享版。

问2：创建APIG实例需要哪些权限？

答：如果使用系统角色，需要同时拥有“APIG Administrator”和“VPC Administrator”权限；如果使用系统策略，拥有“APIG FullAccess”权限即可。

问3：API创建后为什么无法调用？

答：常见原因包括：API未发布到环境、调用域名或路径不正确、认证信息错误、签名时间差超过15分钟。建议按顺序排查。

问4：如何实现API的流量控制？

答：使用流量控制2.0策略，支持基础流控（按API、用户、凭据、源IP）、参数流控（按请求参数）和特殊流控。创建策略后绑定到API即可生效。

问5：后端服务如何验证请求确实来自APIG？

答：使用签名密钥机制。在APIG控制台创建签名密钥并绑定API后，APIG会在请求的Authorization头中添加签名信息，后端服务用同样的方式进行签名并比对。

问6：APIG支持哪些后端服务类型？

答：支持HTTP/HTTPS、Mock、FunctionGraph、gRPC、WebSocket等多种后端服务类型。