构建简单的 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

Apigee 可让您将后端服务快速公开为 API。您可以创建一个 API 代理，为您要公开的后端服务提供表层。您只需要提供后端服务的网络地址，以及 Apigee 用于创建向开发者公开的 API 代理的部分信息。

API 代理会将后端服务实现与开发者所用的 API 分隔开来。这样可以防止开发者日后对您的后端服务进行更改。在您更新后端服务时，开发者不受这些变更的影响，才能继续调用 API。

本主题提供有关各种类型的代理及其设置的信息。如需了解创建代理的分步说明，请参阅以下主题：

教程：构建您的第一个 API 代理
创建 API 代理

使用界面创建 API 代理

创建 API 代理的最简单方法是使用创建代理向导。

如需使用 Apigee 界面访问创建代理向导，请执行以下步骤：

登录 Apigee 界面。
在导航栏中，依次选择开发 > API 代理。
点击新建。

系统会显示创建代理向导，引导您完成生成相应功能并向 API 代理添加基础功能的步骤。

“创建代理”向导的第一页提示您选择反向代理、无目标或代理软件包来自定义向导流程。

您可以在该向导的第一页上从以下来源创建 API 代理：

类型	说明
反向代理（最常见）	用于将传入请求路由到现有 HTTP 后端服务的 API 代理。可以是 JSON 或 XML API。请参阅本部分后面的为 HTTP 服务创建反向代理。点击使用 OpenAPI 规范，通过有效的 OpenAPI 规范生成代理。如需详细了解此选项，请参阅本部分后面的使用 OpenAPI 规范生成代理。
无目标	没有 API 后端的 API 代理（“无目标”）。与上述为 HTTP 服务创建反向代理类似，但您在定义 API 代理详细信息时不会指定现有 API。点击使用 OpenAPI 规范，通过有效的 OpenAPI 规范生成代理。如需详细了解此选项，请参阅本部分后面的使用 OpenAPI 规范生成代理。
上传代理软件包	现有 API 代理软件包（例如 GitHub 上提供的一个示例 API 代理）。请参阅从 API 代理软件包导入 API 代理。

类型

说明

反向代理（最常见）

用于将传入请求路由到现有 HTTP 后端服务的 API 代理。可以是 JSON 或 XML API。请参阅本部分后面的为 HTTP 服务创建反向代理。

点击使用 OpenAPI 规范，通过有效的 OpenAPI 规范生成代理。如需详细了解此选项，请参阅本部分后面的使用 OpenAPI 规范生成代理。

无目标

没有 API 后端的 API 代理（“无目标”）。与上述为 HTTP 服务创建反向代理类似，但您在定义 API 代理详细信息时不会指定现有 API。

点击使用 OpenAPI 规范，通过有效的 OpenAPI 规范生成代理。如需详细了解此选项，请参阅本部分后面的使用 OpenAPI 规范生成代理。

上传代理软件包

现有 API 代理软件包（例如 GitHub 上提供的一个示例 API 代理）。请参阅从 API 代理软件包导入 API 代理。

以下各部分讨论了每种代理类型的详细信息。

为 HTTP 服务创建反向代理

Apigee 会根据以下信息生成反向代理：

后端服务的网址
唯一标识 API 代理将向使用方应用公开的 API 的 URI 路径。

后端服务网址通常表示您的组织拥有的启用服务的应用。它还可指向公开提供的 API。API 或服务可由您控管（例如，内部 HR 应用或 Cloud 中的 Rails 应用），也可以是第三方 API 或服务（例如 Twitter 或 Instagram）。

访问创建代理向导并选择代理类型后，将会提供以下代理详细信息：

字段	说明
名称	为您的 API 显示的名称。指定字母数字字符、短划线 (-) 或下划线 (_)。
基本路径	显示在 API 代理的 `http://[host]` 或 `https://[host]` 地址之后的 URI 片段。Apigee 使用基本路径 URI 来将传入的请求消息匹配并路由到适当的 API 代理。注意：API 代理基本路径默认为 `Name` 字段指定的值，且全部为小写。基本路径后是任何其他资源网址。客户端用于调用 API 代理的完整网址结构如下所示： `https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH` 注意：基本路径必须是唯一的，您无法部署具有相同基本路径的两个 API 代理。如果您修改已部署的 API 代理，并将基准路径设置为与其他 API 代理的基本路径相同的值，则 Apigee 会在您保存时自动取消部署该 API 代理。在重新部署 API 代理之前，必须修改基本路径以使其唯一。在基本路径中使用通配符在 API 代理基本路径中使用一个或多个 `//` 通配符，以使您的 API 代理可适应未来的需求。例如，`/team//members` 的基本路径允许客户端调用 `https://[host]/team/blue/members` 和 `https://[host]/team/green/members`，而无需创建新的 API 代理来支持新团队。请注意，不支持 `/**/`。
说明	（可选）API 的说明。
目标（现有 API）	此 API 代理调用的后端服务网址。

从 API 代理软件包导入 API 代理

通常，您将 API 代理定义为 XML 文件的集合以及其他任何其他支持文件。通过将 API 代理定义为 Apigee 外部的一组文件，您可以将它们保留在源控制系统中，然后导入到 Apigee 以进行测试和部署。

如需从 API 代理软件包导入 API 代理，请执行以下步骤：

按照本部分前面使用界面创建 API 代理所述，访问创建代理向导。
点击上传代理软件包。

在代理向导的上传代理软件包页面上，输入以下信息：

字段	说明
ZIP 软件包	包含 API 代理配置的 ZIP 文件。拖放或点击进入该文件。
名称	为您的 API 显示的名称。默认为不带扩展名的 ZIP 文件的名称。

点击下一步。
在摘要页面上，根据需要选择部署环境，然后点击创建和部署。

系统将显示确认消息，确认新 API 代理已成功创建。
点击修改代理，以显示 API 代理的详细信息页面。

创建 gRPC API 代理

除了 REST API 代理之外，Apigee 目前还支持 gRPC API 代理（仅提供直通式支持）。借助“直通式支持”，gRPC 载荷本身对于 Apigee 是不透明的，并且流量从 gRPC 客户端路由到目标配置中的预配置 gRPC 目标服务器。

目前，Apigee gRPC API 代理：

支持一元 gRPC 请求。
无法使用影响载荷的政策。
可用于未与 GraphQL 或 REST 代理关联的 API 产品。API 产品特定的配额和其他操作设置适用于产品中的所有代理。
在 Apigee Hybrid 中不受支持。
使用两个特定于 gRPC 的流变量：request.grpc.rpc.name 和 request.grpc.service.name。
可以使用以下 gRPC 特定 Apigee Analytics 变量进行监控：x_apigee_grpc_rpc_name、x_apigee_grpc_service_name 和 x_apigee_grpc_status。
返回 gRPC 状态代码。

您还必须配置负载均衡器以支持 gRPC。请参阅在您的应用中使用 gRPC 和使用 gcloud CLI 命令为 gRPC 创建路由。

如需创建 gRPC API 代理，请先定义 gRPC 目标服务器（请参阅创建 TargetServer），然后在创建新代理时指定该目标服务器。

使用 gcloud CLI 命令为 gRPC 创建路由

本部分展示了使用 gcloud CLI 为 gRPC 代理创建路由的示例命令。说明包括设置负载均衡器、目标服务器和 MIG。

本部分并非有关创建路由的综合指南。这些示例可能并不适用于所有使用场景。此外，这些说明假定您熟悉外部路由 (MIG) 和 Cloud 负载均衡器 gRPC 配置。

设置环境变量

这些环境变量用于子部分中的命令。

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

用于使用新负载均衡器为 gRPC 代理创建路由的示例 gcloud CLI 命令

本部分展示了使用 gcloud CLI 和新负载均衡器创建 gRPC 代理的示例命令。说明包括设置负载均衡器、目标服务器和 MIG。

创建实例模板

gcloud compute instance-templates create $MIG_NAME \
--project $PROJECT_ID \
--region $REGION \
--network $VPC_NAME \
--subnet $VPC_SUBNET \
--tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
--machine-type e2-medium --image-family debian-10 \
--image-project debian-cloud --boot-disk-size 20GB \
--no-address \
--metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

创建代管式实例组

gcloud compute instance-groups managed create $MIG_NAME \
--project $PROJECT_ID --base-instance-name apigee-mig \
--size 2 --template $MIG_NAME --region $REGION

配置自动扩缩

gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
--project $PROJECT_ID --region $REGION --max-num-replicas 50 \
--target-cpu-utilization 0.75 --cool-down-period 90

定义已命名端口

gcloud compute instance-groups managed set-named-ports $MIG_NAME \
--project $PROJECT_ID --region $REGION --named-ports https:443

为负载均衡器创建 Google 管理的 SSL 证书和密钥

gcloud compute ssl-certificates create $CERTIFICATE_NAME \
--domains=$DOMAIN_HOSTNAME \
--project $PROJECT_ID \
--global

验证证书是否已预配

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \
--global \
--format="get(name,managed.status, managed.Status)"

创建全局 Cloud 负载均衡器 (GCLB)

创建一项健康检查

gcloud compute health-checks create https hc-apigee-envoy-443 \
--project $PROJECT_ID --port 443 --global \
--request-path /healthz/ingress

为 http1 创建后端服务

gcloud compute backend-services create YOUR_BACKEND_1 \
--project $PROJECT_ID \
--protocol HTTPS \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

为 http2 创建后端服务

gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

将 MIG 添加到后端服务。在此示例中，我们重复使用 MIG，但您也可以创建一对新的 MIG。

gcloud compute backend-services add-backend YOUR_BACKEND_1 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

创建负载均衡网址映射。请先检查您是否已有网址映射。如果要添加，请务必根据以下要求修改该映射，而不是覆盖它。

使用此配置创建 YAML 文件或使用 /tmp/apigee-map.yaml 中的现有文件。请注意，网址映射 http1 后端是默认值。

defaultService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2
weight: 100

验证网址映射：

gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID

使用基于标头的路由创建网址映射：

gcloud compute url-maps import apigee-http1-http2 \
--source /tmp/apigee-map.yaml  \
--global --project $PROJECT_ID

创建负载均衡目标 HTTPS 代理

gcloud compute target-https-proxies create apigee-envoy-https-proxy \
--project $PROJECT_ID --url-map apigee-envoy-proxy-map \
--ssl-certificates $CERTIFICATE_NAME

预留 IPV4 外部 IP 并为负载均衡器创建防火墙规则

gcloud compute addresses create lb-ipv4-vip-1 \
--project $PROJECT_ID \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global

  gcloud compute addresses describe lb-ipv4-vip-1 \
--project $PROJECT_ID --format="get(address)" --global

  gcloud compute forwarding-rules create apigee-envoy-https-lb-rule \
--project $PROJECT_ID --address lb-ipv4-vip-1 --global \
--target-https-proxy apigee-envoy-https-proxy --ports 443

创建防火墙规则

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \
--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

用于为现有负载均衡器创建 gRPC 代理路由的 gcloud CLI 命令示例

本部分展示了使用 gcloud CLI 和现有负载均衡器创建 gRPC 代理的示例命令。说明包括设置负载均衡器、目标服务器和 MIG。

为 http2 创建另一个后端服务

# Create backend service for http2
    gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

将第二个后端服务连接到 MIG

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

列出现有 Apigee GCLB 的网址映射

gcloud compute url-maps list -project $PROJECT_ID

选择用于 Apigee 负载均衡的正确网址映射名称

gcloud compute url-maps export APIGEE_URL_MAP_NAME -project $PROJECT_ID

创建负载均衡网址映射 YAML 文件

如果您已有网址映射，请将此配置合并到其中。否则，请在 /tmp/apigee-map.yaml 中使用此配置创建一个 YAML 文件。

defaultService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2
weight: 100

为 gRPC 路由应用新的 YAML

gcloud compute url-maps import APIGEE_URL_MAP_NAME\
--source /tmp/apigee-map.yaml  \
--global -project $PROJECT_ID

添加安全措施

在创建代理向导的通用政策页面上，选择要添加的安全授权类型。下表汇总了可用的选项：

安全授权	说明
API 密钥	对您定义的 API 代理添加简单的 API 密钥验证。为进行响应，API 平台会将 VerifyAPIKey 政策和 AssignMessage 政策添加到您的 API 代理。VerifyAPIKey 政策会验证应用所请求的 API 密钥。AssignMessage 政策从 API 调用（作为查询参数）发送到 API 调用的请求中移除该 API 密钥。
OAuth 2.0	向您的 API 代理添加基于 OAuth 2.0 的身份验证。Apigee 会自动向您的 API 代理添加以下政策：一条政策用于验证访问令牌，另一条政策用于将访问令牌从消息中删除，然后再将消息转发到后端服务。如需了解如何获取访问令牌，请参阅 OAuth。
经过（无授权）	无需授权。请求将传递给后端，而无需对 Apigee 进行任何安全检查。

添加对 CORS 的支持

跨域资源共享 (CORS) 是一种标准机制，可让网络浏览器直接将请求发送到其他网域。CORS 标准定义了一组网络浏览器和服务器用其来实现跨域通信的 HTTP 标头。

您可以通过执行以下任一操作来添加对 CORS 的支持：

将 CORS 政策添加到 ProxyEndpoint 的请求 PreFlow
在创建代理向导的通用政策页面上选择添加 CORS 标头

如需详细了解 CORS 支持（包括向代理添加 CORS 预检支持），请参阅向 API 代理添加 CORS 支持。

添加配额

配额可用于在配额下保护后端服务免遭高流量访问。参见配额。（如果选择了直通式授权，则不会显示。）

使用 OpenAPI 规范生成代理

本部分介绍您可以使用的 OpenAPI 选项，您可以通过 OpenAPI 规范生成以下类型的 API 代理：反向或无目标。

什么是 OpenAPI 规范？

Open API 计划徽标 “Open API 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需了解详情，请参阅 OpenAPI 计划。

OpenAPI 规范使用标准格式来描述 RESTful API。OpenAPI 规范采用 JSON 或 YAML 机器可读格式编写，但便于人类阅读和理解。该规范将 API 元素描述为基本路径、路径和动词、标头、查询参数、操作、内容类型、响应描述等。此外，OpenAPI 规范通常用于生成 API 文档。

OpenAPI 规范中的以下片段介绍了 Apigee 的模拟目标服务，请参阅 http://mocktarget.apigee.net。如需了解详情，请参阅用于 helloworld 示例的 OpenAPI 规范。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

通过创建代理向导，您可以导入 OpenAPI 规范并使用它来生成 API 代理。生成代理后，可以使用 Apigee 界面通过添加政策、实现自定义代码等来进一步开发代理，就像任何 Apigee 代理一样。

根据 OpenAPI 规范创建 API 代理

根据 OpenAPI 规范创建 API 代理。您只需点击几下，便可使用包含路径、参数、条件流和目标端点自动生成的 API 代理。然后，您可以添加 OAuth 安全机制、速率限制和缓存等功能。

在创建代理向导中，点击使用 OpenAPI 规范，然后按照向导从 OpenAPI 规范创建反向或无目标代理。如需了解详情，请参阅通过 OpenAPI 规范创建 API 代理。

创建 API 代理的新修订版本

创建 API 代理的新修订版本，如下所述。

如需创建 API 代理的新修订版本，请执行以下步骤：

登录 Apigee 界面。
在导航栏中，依次选择开发 > API 代理。
点击要复制的列表中的 API 代理。
点击开发标签页。
选择保存按钮，然后选择另存为新修订版本。

备份 API 代理

您可以将现有 API 代理作为 API 代理软件包中的一组 XML 文件进行备份。将 API 代理导出到软件包后，您可以按照本部分前面从 API 代理软件包导入 API 代理所述，将 API 代理导入新代理。如需了解详情，请参阅下载 API 代理。

使用 API 创建 API 代理

如需使用 API 创建 API 代理，请参阅创建 API 代理。