本页面适用于 Apigee,但不适用于 Apigee Hybrid。
查看 Apigee Edge 文档。
步骤摘要
本文档介绍如何通过命令行安装和配置 Apigee 评估组织。评估组织会在 60 天后过期,并且可能还存在其他限制。另请参阅比较评估组织和付费组织。
预配步骤如下:
- 第 1 步:定义环境变量:设置
gcloud
并定义环境变量。Google Cloud CLI 可管理身份验证、本地配置、开发者工作流以及与 Google Cloud API 的交互。 - 第 2 步:启用 API:Apigee 要求您启用多个 Google Cloud API。
- 第 3 步:配置服务网络:服务网络可在您的网络与 Apigee 之间自动执行专用连接设置(使用 VPC 网络对等互连)。
- 第 4 步:创建组织:Apigee 组织(有时称为组织)是 Apigee 中的顶层容器。它包括所有环境和环境组、用户、API 代理以及相关资源。
- 第 5 步:配置路由:允许对 API 进行外部访问或仅限内部访问。
- 第 6 步:调用示例 API 代理:通过部署和调用 API 代理来测试预配。
第 1 步:定义环境变量
设置 gcloud
并定义环境变量,以供后续步骤使用:
- 请确保您已完成前提条件中列出的要求。
- 您必须已安装 gcloud CLI。如果您需要安装它,请参阅安装 gcloud CLI。
- 初始化 gcloud CLI(详见初始化 gcloud CLI);或者,如果 CLI 已初始化,请确保您在前提条件中创建的 Google Cloud 项目是 gcloud 的默认项目。
- 定义以下环境变量:
AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
PROJECT_ID="YOUR_PROJECT_ID"
RUNTIME_LOCATION="YOUR_RUNTIME_LOCATION"
ANALYTICS_REGION="YOUR_ANALYTICS_REGION"
其中:
- AUTH 使用不记名令牌定义
Authentication
标头。调用 Apigee API 时需使用此标头。请注意,令牌会在一段时间后过期,并且在令牌过期后,您可以使用同一命令重新生成令牌。如需了解详情,请参阅 print-access-token 命令参考页面。 - PROJECT_ID 是您在前提条件中创建的 Cloud 项目 ID。
RUNTIME_LOCATION 是 Apigee 实例所在的物理位置。如需查看可用运行时位置的列表,请参阅 Apigee 位置。
-
ANALYTICS_REGION 是存储 Apigee 分析数据的物理位置。如需查看可用的 Apigee API Analytics 区域列表,请参阅 Apigee 位置。
RUNTIME_LOCATION 和 ANALYTICS_REGION 可以位于同一区域,但这不是必须的。不过,如果两者相同,则可能会获得性能优势。
- AUTH 使用不记名令牌定义
- (可选)通过回送您刚刚设置的值来检查您的工作。请注意,要在命令中使用变量,请在变量名称前面加上美元符号 ($)。
echo $AUTH
echo $PROJECT_ID
echo $RUNTIME_LOCATION
echo $ANALYTICS_REGION
echo
命令的响应应如下所示:Authorization: Bearer ya29.a123456678940B63hPSAMPLEsampleKKYVsample0f3pWDWZDuH2-hENkNa TvgZ1PD977TMvv6edBQPJezdHw040880Ol_LoD5ZDkt-i-knizia_KhA9L20sSvztL81-SAMPLE42ELPMASk2_ 1CxN my-cloud-project us-west1 us-west1
第 2 步:启用 API
-
Apigee 要求您启用多个 Google Cloud API。执行
services enable
命令来启用它们:gcloud services enable apigee.googleapis.com \ servicenetworking.googleapis.com compute.googleapis.com \ cloudkms.googleapis.com --project=$PROJECT_ID
(可选)如需查看您的工作,请使用
services list
命令显示所有已启用的 API:gcloud services list
该响应会显示所有已启用的服务,包括您刚刚启用的 API(Apigee、Service Networking、Cloud KMS 和 Compute Engine)。
第 3 步:配置服务网络
- 创建以下环境变量:
RANGE_NAME=YOUR_RANGE_NAME
NETWORK_NAME=YOUR_NETWORK_NAME
其中:
RANGE_NAME
是您正在创建的 IP 地址范围的名称。您可以随意为范围命名。 例如:google-svcs
NETWORK_NAME
是应在其中预留地址的网络资源的名称。Google 会为每个新项目创建一个默认网络(名为default
),以便您使用该网络。但是,Google 不建议将默认网络用于测试以外的其他用途。
- 创建 CIDR 长度为 /22 的 IP 地址范围:
gcloud compute addresses create $RANGE_NAME \ --global \ --prefix-length=22 \ --description="Peering range for Apigee services" \ --network=$NETWORK_NAME \ --purpose=VPC_PEERING \ --addresses=OPTIONAL_ADDRESSES \ --project=$PROJECT_ID
其中,
--addresses
可让您选择为前缀长度/22
指定一个或多个地址 IP。例如,如需分配 CIDR 地址块192.168.0.0/22
,请将地址指定为192.168.0.0
,并将前缀长度指定为22
。另请参阅创建 IP 地址分配。如果您未提供
--addresses
参数,则 gcloud 会为您选择一个可用地址范围。成功后,
gcloud
会返回以下内容:Created [https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/global/addresses/google-svcs].
创建 IP 地址范围后,地址便会与项目关联,直到您将地址释放。
- 创建 CIDR 长度为 /28 的 IP 地址范围。此范围供 Apigee 用于问题排查,不能自定义或更改。
gcloud compute addresses create google-managed-services-support-1 \ --global \ --prefix-length=28 \ --description="Peering range for supporting Apigee services" \ --network=$NETWORK_NAME \ --purpose=VPC_PEERING \ --addresses=OPTIONAL_ADDRESSES \ --project=$PROJECT_ID
其中,
--addresses
可让您选择为前缀长度/28
指定一个或多个地址 IP。例如,如需分配 CIDR 地址块192.168.0.0/28
,请将地址指定为192.168.0.0
,并将前缀长度指定为28
。另请参阅创建 IP 地址分配。如果您未提供
--addresses
参数,则 gcloud 会为您选择一个可用地址范围。 - 使用以下命令将您的服务连接到网络:
gcloud services vpc-peerings connect \ --service=servicenetworking.googleapis.com \ --network=$NETWORK_NAME \ --ranges=$RANGE_NAME,google-managed-services-support-1 \ --project=$PROJECT_ID
此操作可能需要几分钟才能完成。成功后,
gcloud
会返回以下内容:Operation "operations/OPERATION_ID" finished successfully.
其中,OPERATION_ID 是 LROLRO(长时间运行的操作)的 UUID。
Apigee 在您的网络与 Google 服务之间建立连接;具体而言,Apigee 通过 VPC 对等互连将您的项目连接到 Service Networking API。Apigee 还会将 IP 地址与您的项目关联。
第 4 步:创建组织
组织是 Apigee 中的顶层容器。它包含您的所有 API 代理及相关资源。如需了解详情,请参阅了解组织。
- 使用 gcloud alpha apigee organizations 命令创建新的 eval 组织:
gcloud alpha apigee organizations provision \ --runtime-location=$RUNTIME_LOCATION \ --analytics-region=$ANALYTICS_REGION \ --authorized-network=$NETWORK_NAME \ --project=$PROJECT_ID
其中,
--authorized-network
是自定义对等互连网络的名称。例如:default
。 -
当您执行
provision
命令时,Google 会启动 LRO 以创建评估组织。此操作最多需要 40 分钟才能完成。在此期间,gcloud
会显示以下内容:Provisioning organization...
创建评估组织及其关联的运行时实例时,
gcloud
会返回以下内容:Provisioning organization...done.
-
如果您执行以下命令:
gcloud alpha apigee operations list --organization=$PROJECT_ID
您应该会看到所有 UUID 都处于
FINISHED
状态。例如:UUID ORGANIZATION STATE 00bab06f-c60c-41a5-4242-7SAMPLE7f my-org FINISHED 429790a7-3151-4642-4343-7SAMPLE7f my-org FINISHED d00a92a9-9b83-4642-4343-7SAMPLE7f my-org FINISHED f48a00ff-7daa-4c4a-4444-7SAMPLE7f my-org FINISHED
第 5 步:配置路由
决定是允许外部访问还是仅限内部访问:
访问类型 | 配置和部署过程的说明 |
---|---|
内部 |
仅允许从内部访问 API 代理。 您必须在网络内创建新虚拟机并与其连接。在新虚拟机中,您可以向 Apigee API 代理发送请求。 |
外部 |
允许从外部访问 API 代理。 使用 Private Service Connect (PSC) 可以在服务提供方 (Apigee) 和服务使用方(对等互连 VPC 项目和/或您控制的一个或多个其他 Cloud 项目)之间启用专用连接。使用此方法,请求会通过全球外部负载均衡器传递到单个连接点(称为服务连接)。此配置可让您从任何启用了网络的机器发送 Apigee API 代理请求。 |
在以下说明的标签页上介绍了每种路由方法。
内部路由
如果您使用命令行为仅允许内部访问设置 API 代理,则在此步骤中您无需执行任何任务。 您可以跳至第 6 步:调用示例 API 代理,您将在该步骤向 API 代理发送请求。
外部路由
本部分介绍了如何使用 Private Service Connect (PSC) 配置外部路由,以允许在 Apigee 和您控制的 VPC 之间进行通信。您必须先执行此操作,然后才能将请求从外部客户端发送到 Apigee 运行时实例。
外部配置步骤包括:
第 5a 步:创建网络端点组 (NEG)
第 5b 步:配置负载均衡器
后续几个部分将介绍其中每个步骤。
第 5a 步:创建网络端点组 (NEG)
- 获取 Apigee 实例的服务连接:
curl -i -X GET -H "$AUTH" \ "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances"
在以下示例输出中,
serviceAttachment
值以粗体显示:{ "instances": [ { "name": "eval-instance", "location": "us-west1", "host": "10.72.100.2", "port": "443", "createdAt": "1657832463500", "lastModifiedAt": "1657833920670", "state": "ACTIVE", "peeringCidrRange": "SLASH_22", "runtimeVersion": "1-8-0-apigee-18", "ipRange": "10.74.100.0/28,10.74.100.16/28", "consumerAcceptList": [ "apigee-eval-test" ], "serviceAttachment": "projects/s8da1b0111eb33765-tp/regions/us-west1/serviceAttachments/apigee-us-west1-icza" } ] }
创建一个 Private Service Connect 网络端点组 (NEG),指向您在上一步中从实例响应正文获取的服务连接。
gcloud compute network-endpoint-groups create NEG_NAME \ --network-endpoint-type=private-service-connect \ --psc-target-service=TARGET_SERVICE \ --region=$RUNTIME_LOCATION \ --network=$NETWORK_NAME \ --subnet=SUBNET_NAME \ --project=$PROJECT_ID
请替换以下内容:
- NEG_NAME:网络端点组的名称。
- TARGET_SERVICE:要建立的服务连接。例如
projects/bfac7497a40c32a12p-tp/regions/us-west1/serviceAttachments/apigee-us-west1-crw7
- SUBNET_NAME:用于与提供方建立专用连接的子网的名称。子网不必很大:PSC NEG 只需要子网中的一个 IP。对于 Apigee,每个区域只需要一个 PSC NEG。子网可以由虚拟机或其他实体共享和使用。如果未指定子网,网络端点可能属于创建网络端点组的区域中的任何子网。
第 5b 步:配置负载均衡器
配置全球外部 HTTP(S) 负载均衡器(负载均衡方案设置为 EXTERNAL_MANAGED
)。
虽然 Private Service Connect NEG 是区域性的,但此配置中的所有其他负载均衡组件都是全球性的。
- 为负载均衡器预留全球外部 IPv4 地址。
gcloud compute addresses create ADDRESS_NAME \ --ip-version=IPV4 --global --project=$PROJECT_ID
将 ADDRESS_NAME 替换为 IP 地址资源的名称。
运行以下命令以查看预留的 IP 地址:
gcloud compute addresses describe ADDRESS_NAME \ --format="get(address)" --global --project=$PROJECT_ID
- 为 NEG 创建后端服务。
gcloud compute backend-services create BACKEND_SERVICE_NAME \ --load-balancing-scheme=EXTERNAL_MANAGED \ --protocol=HTTPS \ --global --project=$PROJECT_ID
- 将 NEG 添加到后端服务:
gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \ --network-endpoint-group=NEG_NAME \ --network-endpoint-group-region=$RUNTIME_LOCATION \ --global --project=$PROJECT_ID
替换以下内容:
- BACKEND_SERVICE_NAME:后端服务的名称。
- NEG_NAME:网络端点组的名称。
为负载均衡器创建网址映射。
网址映射必须引用默认后端服务。将刚刚创建的后端服务设置为默认后端服务。
gcloud compute url-maps create URL_MAP_NAME \ --default-service=DEFAULT_BACKEND_SERVICE_NAME \ --global --project=$PROJECT_ID
替换以下内容:
- URL_MAP_NAME:网址映射的名称。
- DEFAULT_BACKEND_SERVICE_NAME:负载均衡器的默认后端服务的名称。当没有主机规则与请求的主机名匹配时,系统会使用默认后端服务。
为 HTTPS 目标代理创建 SSL 证书。
如需创建 HTTPS 负载均衡器,您必须拥有要在 HTTPS 目标代理中使用的 SSL 证书资源。您可以使用 Google 管理的 SSL 证书或自行管理的 SSL 证书创建 SSL 证书资源。
使用此命令创建 Google 管理的 SSL 证书资源:
gcloud compute ssl-certificates create CERTIFICATE \ --domains DOMAIN --project=$PROJECT_ID
替换以下内容:
- CERTIFICATE:证书的名称。
- DOMAIN:您将用于外部负载均衡器的域名。
如需创建自行管理的 SSL 证书,您需要本地私钥文件和本地证书文件。如果您需要创建这些文件,请参阅使用自行管理的 SSL 证书。
gcloud compute ssl-certificates create CERTIFICATE \ --certificate LB_CERT \ --private-key LB_PRIVATE_KEY --project=$PROJECT_ID
请替换以下内容:
- CERTIFICATE:证书的名称。
- LB_CERT:指向自行管理证书的 PEM 格式的证书文件的路径。
- LB_PRIVATE_KEY:指向自行管理证书的 PEM 格式的私钥文件的路径。
-
证书最多可能需要一个小时才能完成预配。如需检查预配的状态,请执行以下命令:
gcloud compute ssl-certificates describe CERTIFICATE \ --global \ --format="get(name,managed.status, managed.Status)"
- 将网域添加到为您创建的 Apigee 环境组中。环境组的名称为
eval-group
:curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/eval-group" \ -H "$AUTH" \ -X PATCH \ -H "Content-Type:application/json" \ -d '{ "hostnames":["'"DOMAIN"'"] }'
- 检查环境组操作的状态:
curl -H "$AUTH" \ "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/eval-group/attachments"
-
使用 SSL 证书资源创建目标 HTTPS 代理。
gcloud compute target-https-proxies create PROXY_NAME \ --url-map=URL_MAP_NAME \ --ssl-certificates=CERTIFICATE --project=$PROJECT_ID
替换以下内容:
- PROXY_NAME:目标 HTTPS 代理的名称。
- URL_MAP_NAME:网址映射的名称。
- CERTIFICATE:证书资源的名称。
- 创建转发规则。
gcloud compute forwarding-rules create FWD_RULE \ --load-balancing-scheme=EXTERNAL_MANAGED \ --network-tier=PREMIUM \ --address=ADDRESS_NAME \ --target-https-proxy=PROXY_NAME \ --ports=443 \ --global --project=$PROJECT_ID
替换以下内容:
- FWD_RULE:转发规则的名称。
- ADDRESS_NAME:您预留用于转发规则的 IP 地址资源。
- PROXY_NAME:目标 HTTPS 代理的名称。
将 BACKEND_SERVICE_NAME 替换为后端服务的名称。
Apigee 预配完成。
第 6 步:调用示例 API 代理
系统在预配期间为您创建并部署了一个名为 hello-world
的 API 代理。在这一步中,您将通过调用此代理来测试新的评估组织。
使用内部路由调用代理
如果您在第 5 步选择了内部路由选项,请按照调用仅限内部访问的 API 代理中的步骤操作。
使用外部路由调用代理
如果您在第 5 步中选择了外部路由选项,请按照本部分中的步骤操作。
- 为您的网域设置 DNS 条目。您可以通过两种方式完成此任务:
- 在您的注册商处,创建一条指向您的网域的 A 记录。例如,如果您的网域为
sales.example.com
,IP 地址为 10.23.0.2,则将sales.example.com
的记录指向地址10.23.0.2
。运行以下命令以查看预留的 IP 地址:
gcloud compute addresses describe ADDRESS_NAME \ --format="get(address)" --global --project=$PROJECT_ID
- 使用 Google Cloud DNS 将网址映射到 IP 地址。
- 在您的注册商处,创建一条指向您的网域的 A 记录。例如,如果您的网域为
- 确认
hello-world
代理已部署:curl -i -H "$AUTH" \ "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/eval/apis/hello-world/revisions/1/deployments"
- 调用 API 代理:
通过执行以下命令,从任何已启用网络的计算机向 API 代理发送请求:
curl -i -H "Host: DOMAIN" \ https://DOMAIN/hello-world
其中 DOMAIN 是您放入证书并添加到环境组的网域,如第 5 步:配置路由中所述。如果需要,您可以使用此 API 从环境组获取
DOMAIN
值:curl -i -H "$AUTH" \ "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups"
成功后,示例 API 代理会返回响应:
Hello, Guest!
问题排查提示:
如果您收到握手错误,请检查 SSL 证书的状态。如需了解如何对自行管理的证书和 Google 管理的证书进行问题排查,请参阅对 SSL 证书进行问题排查。
确保您的注册网域具有指向第 5 步中创建的全球外部 IPv4 地址的 A 记录。运行以下命令以查看预留的 IP 地址:
gcloud compute addresses describe ADDRESS_NAME \ --format="get(address)" --global --project=$PROJECT_ID
如果您无法解析网域配置,请尝试使用此命令调用代理:
curl -H Host:DOMAIN --resolve \ DOMAIN:443:EXTERNAL_IP_ADDRESS \ https://DOMAIN:443/hello-world -k
下一步:如需详细了解构建和部署 API 代理,请参阅构建第一个 API 代理概览。