本教程介绍如何在非 Google Cloud 环境中运行的 Kubernetes 集群中配置和部署示例 API 和 Extensible Service Proxy V2 (ESPv2)。如果您想使用 Google Kubernetes Engine (GKE),请参阅 GKE 上的 Endpoints 使用入门。
示例代码的 REST API 是使用 OpenAPI 规范描述的。 此外,本教程还介绍了如何创建 API 密钥以向 API 发送请求。
本教程使用了示例代码和 ESPv2 的预构建容器映像,这些映像存储在 Container Registry 中。如果您不熟悉容器,请参阅以下内容了解详情:
如需大致了解 Cloud Endpoints,请参阅 Endpoints 简介和 Endpoints 架构。
目标
学习本教程时,请使用以下概要任务列表。为了向 API 成功发送请求,您必须完成第 1 部分中的所有任务。
第 1 部分
- 设置 Google Cloud 项目。请参阅准备工作。
- 安装并配置本教程中使用的软件。请参阅安装和配置所需的软件。
- 根据需要下载示例代码。请参阅获取示例代码。
- 下载 Kubernetes 配置文件。请参阅获取 Kubernetes 配置文件。
- 配置
openapi.yaml
文件,该文件用于配置 Endpoints。请参阅配置 Endpoints。 - 部署 Endpoints 配置以创建 Cloud Endpoints 服务。请参阅部署 Endpoints 配置。
- 为您的 Endpoints 服务创建凭据。请参阅为您的服务创建凭据。
- 将 API 和 ESPv2 部署到集群。请参阅部署 API 后端。
- 获取服务的外部 IP 地址。请参阅获取外部 IP 地址。
- 使用 IP 地址向 API 发送请求。请参阅使用 IP 地址发送请求。
- 跟踪 API 活动。请参阅跟踪 API 活动。
第 2 部分
- 为示例 API 配置 DNS 记录。请参阅为 Endpoints 配置 DNS。
- 使用域名向 API 发送请求。请参阅使用 FQDN 发送请求。
清理
完成后,请参阅清理,以避免您的 Google Cloud 账号产生费用。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
您可使用价格计算器根据您的预计使用情况来估算费用。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
准备工作
本教程假设您已经设置了 Minikube 或 Kubernetes 集群。如需了解详情,请参阅 Kubernetes 文档。
- 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- 记下 Google Cloud 项目 ID,因为以后需要它。
安装和配置所需的软件
在本教程中,您将安装 Google Cloud CLI,以使用 gcloud CLI 管理您的项目。您使用的是 kubectl
、
命令行界面,用于对 Kubernetes 集群运行命令。此外,您还需要一种用于测试 API 的方法。
在以下过程中,如果您已安装所需的软件,请继续执行下一步。
要安装和配置所需的软件,请执行以下操作:
-
您需要一个应用来向示例 API 发送请求。
- Linux 和 macOS 用户:本教程提供了一个使用
curl
的示例,它通常已预装在您的操作系统中。如果您没有curl
,可以从curl
版本和下载页面中下载。 - Windows 用户:本教程提供了一个使用
Invoke-WebRequest
的示例,PowerShell 3.0 及更高版本支持该命令。
- Linux 和 macOS 用户:本教程提供了一个使用
- 安装并初始化 gcloud CLI。
-
更新 gcloud CLI 并安装 Endpoints 组件:
gcloud components update
-
确保 Google Cloud CLI (
gcloud
) 有权访问您在 Google Cloud 上的数据和服务: 在浏览器打开的新标签页中,选择一个账号。gcloud auth login
- 将默认项目设置为您的项目 ID:
gcloud config set project YOUR_PROJECT_ID
将 YOUR_PROJECT_ID 替换为项目 ID。如果您有其他 Google Cloud 项目,并且想使用
gcloud
请参阅管理 gcloud CLI 配置。 - 安装
kubectl
:gcloud components install kubectl
-
获取将作为应用默认凭据的新用户凭据。用户凭据的作用是向
kubectl
授权。gcloud auth application-default login
- 在浏览器打开的新标签页中,选择一个账号。
- 运行以下命令,确保 Kubernetes 客户端已正确配置:
kubectl version
您应该会看到类似如下所示的输出:
Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4", GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean", BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc", Platform:"linux/amd64"} Server Version: version.Info{Major:"1", Minor:"7+", GitVersion:"v1.7.8-gke.0", GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean", BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc", Platform:"linux/amd64"}
下载示例代码
根据需要下载示例代码。在本教程中,您将部署预构建的容器映像,因此您不必使用示例代码构建容器。但是,您不妨下载示例代码,它是以多种语言提供的,可以帮助您了解示例 API 的工作原理。
要下载示例代码,请执行以下操作:
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd java-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd python-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 确保已设置
GOPATH
环境变量。 - 将示例应用代码库克隆到本地机器:
go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
- 转到包含示例代码的目录:
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd php-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 转到包含示例代码的目录:
cd ruby-docs-samples/endpoints/getting-started
如需克隆或下载示例 API,请执行以下操作:
- 将示例应用代码库克隆到本地机器:
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
或者,下载该示例的 zip 文件并将其解压缩。
- 切换到包含示例代码的目录:
cd nodejs-docs-samples/endpoints/getting-started
获取 Kubernetes 配置文件
将包含本教程中使用的
yaml
文件的 GitHub 代码库克隆到您的本地机器:git clone https://github.com/googlecloudplatform/endpoints-samples
或者,下载该示例的 zip 文件并将其解压缩。
转到包含此配置文件的目录:
cd endpoints-samples/kubernetes
配置 Endpoints
示例代码包括 OpenAPI 配置文件 openapi.yaml
,该文件基于 OpenAPI 规范 v2.0。
要配置 Endpoints,请执行以下操作:
- 在示例代码目录中,打开
openapi.yaml
配置文件。请注意以下事项:
- 配置示例显示了
host
字段附近的几行内容,您需要修改这些内容。如需将openapi.yaml
文件部署到 Endpoints,您需要完整的 OpenAPI 文档。 - 示例
openapi.yaml
文件包含用于配置身份验证的部分(本教程不需要)。您无需使用 YOUR-SERVICE-ACCOUNT-EMAIL 和 YOUR-CLIENT-ID 配置这些行。 - OpenAPI 是一种与语言无关的规范。为方便起见,每种语言的 GitHub 存储库中的
getting-started
示例均包含相同的openapi.yaml
文件。
- 配置示例显示了
- 将
host
字段中的文本替换为 Endpoints 服务名称,该名称应采用以下格式:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如:
host: "echo-api.endpoints.example-project-12345.cloud.goog"
请注意,echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
是 Endpoints 服务名称。该名称不是您用于向 API 发送请求的完全限定域名 (FQDN)。
如需了解 OpenAPI 文档中 Endpoints 所需的字段,请参阅配置 Endpoints。
完成以下所有配置步骤后,您可以
使用 IP 地址成功向示例 API 发送请求,请参阅
为 Endpoints 配置 DNS
以了解如何配置
echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
设为 FQDN。
部署 Endpoints 配置
如需部署 Endpoints 配置,请使用 gcloud endpoints
services deploy
命令。此命令使用 Service Management 创建一项托管式服务。
如需部署 Endpoints 配置,请执行以下操作:
- 确保您位于
endpoints-samples/kubernetes
目录中。 - 上传配置并创建托管式服务:
gcloud endpoints services deploy openapi.yaml
然后,gcloud
命令会调用 Service Management API,以便使用您在 openapi.yaml
文件的 host
字段中指定的名称创建托管式服务。Service Management 会根据 openapi.yaml
文件中的设置来配置服务。如果您对 openapi.yaml
做出更改,则必须重新部署该文件才能更新 Endpoints 服务。
在创建和配置服务时,Service Management 会向终端输出信息。您尽可忽略有关 openapi.yaml
文件中的路径未要求使用 API 密钥的警告。完成服务配置后,Service Management 将显示如下所示的消息,其中包含服务配置 ID 和服务名称:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
在上面的示例中,2017-02-13r0
是服务配置 ID,echo-api.endpoints.example-project-12345.cloud.goog
是 Endpoints 服务。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi.yaml
文件,服务配置 ID 中的修订版本号将递增。您可以在 Google Cloud 控制台中的 Endpoints > Services 页面上查看 Endpoints 服务配置。
如果您收到错误消息,请参阅排查 Endpoints 配置部署问题。
检查所需服务
Endpoints 和 ESP 至少需要启用以下 Google 服务:姓名 | 标题 |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
endpoints.googleapis.com |
Google Cloud Endpoints |
在大多数情况下,gcloud endpoints services deploy
命令会启用这些必需的服务。但在以下情况下,gcloud
命令会成功完成,但不启用必需的服务:
您使用了 Terraform 之类的第三方应用,但未添加这些服务。
您将 Endpoints 配置部署到已明确停用这些服务的现有 Google Cloud 项目。
使用以下命令确认必需服务是否已启用:
gcloud services list
如果您没有看到列出的必需服务,请启用它们:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
同时启用 Endpoints 服务:
gcloud services enable ENDPOINTS_SERVICE_NAME
要确定 ENDPOINTS_SERVICE_NAME,您可以执行以下任一操作:
部署 Endpoints 配置后,前往 Cloud 控制台中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。
对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的
host
字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的name
字段中指定的值。
如需详细了解 gcloud
命令,请参阅 gcloud
服务。
为您的服务创建凭据
为了管理您的 API,ESP 和 ESPv2 都需要使用 Service Infrastructure 中的服务。为了调用这些服务,ESP 和 ESPv2 必须使用访问令牌。当您将 ESP 或 ESPv2 部署到 Google Cloud 环境(例如 GKE、Compute Engine 或 App Engine 柔性环境)时,ESP 和 ESPv2 会通过 Google Cloud 元数据服务为您获取访问令牌。
将 ESP 或 ESPv2 部署到非 Google Cloud 环境时, 例如本地桌面、本地 Kubernetes 集群 提供商,则必须提供服务账号 JSON 文件 包含私钥的网址。ESP 和 ESPv2 使用 服务账号 生成访问令牌,以调用管理 API 所需的服务。
您可以使用 Google Cloud 控制台或 Google Cloud CLI 创建服务账号和私钥文件:
控制台
- 在 Google Cloud 控制台中,打开服务账号页面。
- 点击选择项目。
- 选择在其中创建了 API 的项目,并点击打开。
- 点击 + 创建服务账号。
- 在服务账号名称字段中,输入您的服务账号的名称。
- 点击创建。
- 点击继续。
- 点击完成。
- 点击新创建的服务账号的电子邮件地址。
- 点击密钥。
- 依次点击添加密钥和创建新密钥。
点击创建。JSON 密钥文件将下载到您的计算机上。
务必要安全存储密钥文件,因为它能够以服务账号的身份进行身份验证。您可以根据需要移动并重命名此文件。
点击关闭。
gcloud
输入以下命令,以显示 Google Cloud 项目的 ID:
gcloud projects list
替换以下命令中的 PROJECT_ID,以将默认项目设置为您的 API 所属的项目:
gcloud config set project PROJECT_ID
确保 Google Cloud CLI (
gcloud
) 有权访问您在 Google Cloud 上的数据和服务:gcloud auth login
如果您有多个账号,请务必选择 API 所属的 Google Cloud 项目中的账号。如果运行
gcloud auth list
,则您选择的账号将显示为该项目的活跃账号。如需创建服务账号,请运行以下命令,并将 SERVICE_ACCOUNT_NAME 和
My Service Account
分别替换为您要使用的名称和显示名:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
该命令将采用以下格式指定服务账号的电子邮件地址:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
后续命令会用到此电子邮件地址。
创建服务账号密钥文件:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
添加所需的 IAM 角色:
本部分介绍 ESP 和 ESPv2 使用的 IAM 资源,以及关联的服务账号访问这些资源所需的 IAM 角色。
端点服务配置
ESP 和 ESPv2 调用使用端点服务配置的 Service Control。端点服务配置是 IAM 资源,ESP 和 ESPv2 需要 Service Controller 角色才能访问它。
IAM 角色属于端点服务配置,而非项目。一个项目可能有多个端点服务配置。
使用以下 gcloud 命令将角色添加到端点服务配置的关联服务账号。
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
其中
* SERVICE_NAME
是端点服务名称
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
是关联的服务账号。
Cloud Trace
ESP 和 ESPv2 调用 Cloud Trace 服务以将 Trace 导出到项目。此项目称为跟踪项目。在 ESP 中,跟踪项目和拥有端点服务配置的项目是相同的。在 ESPv2 中,跟踪项目可通过 --tracing_project_id
标志指定,默认为部署项目。
ESP 和 ESPv2 需要 Cloud Trace Agent 角色才能启用 Cloud Trace。
使用以下 gcloud 命令将该角色添加到关联的服务账号:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
其中
* TRACING_PROJECT_ID 是跟踪项目 ID
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com是关联的服务账号。有关详情,请参见
什么是角色和权限?
如需详细了解这些命令,请参阅 gcloud iam service-accounts
。
部署 API 后端
到目前为止,您已将 OpenAPI 文档部署到 Service Management,但尚未部署为 API 后端提供服务的代码。本部分逐步介绍如何将示例 API 和 ESPv2 的预构建容器部署到 Kubernetes。
检查所需权限
向与集群关联的服务账号授予所需的权限:
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceController
如需了解详情,请参阅什么是角色和权限?
为 ESPv2 提供服务凭据
ESPv2 在容器内部运行,并且需要访问存储在本地 service-account-creds.json
文件中的凭据。为了提供
ESPv2 可以访问这些凭据,您需要创建一个
Kubernetes Secret
并将 Kubernetes Secret 作为
Kubernetes 卷。
要创建 Kubernetes 密钥并装载卷,请执行以下操作:
- 务必将 JSON 文件重命名为
service-account-creds.json
,并将其复制到endpoints-samples/kubernetes
(如果此文件之前是下载到其他目录)。这样,该名称就与echo.yaml
部署清单文件中指定的选项匹配。 - 确保您位于
endpoints-samples/kubernetes
目录中。 使用以下命令通过服务账号凭据创建 Kubernetes Secret:
kubectl create secret generic service-account-creds \ --from-file=service-account-creds.json
成功后,系统会显示以下消息:
secret "service-account-creds" created
用于将 API 和 ESPv2 部署到 Kubernetes 的部署清单文件已包含 Secret 卷,如该文件的以下两个部分所示:
配置服务名称并启动服务
ESPv2 需要知道您的服务名称,才能找到您之前使用 gcloud endpoints services deploy
命令部署的配置。
要配置服务名称并启动服务,请执行以下操作:
打开部署清单文件
echo.yaml
,并将 ESPv2 启动选项中的 SERVICE_NAME 替换为您的服务的名称。该名称与您在 OpenAPI 文档的host
字段中配置的名称相同。例如:"--service=echo-api.endpoints.example-project-12345.cloud.goog"
"--rollout_strategy=managed"
选项 将 ESPv2 配置为使用最新部署的服务配置。如果指定此选项,则 ESPv2 会在您部署新服务配置后的一分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项,而不是提供特定配置 ID 供 ESPv2 使用。如需了解所使用的其他 ESPv2 选项,请参阅 ESPv2 启动选项。使用以下命令启动服务,以在 Kubernetes 上部署 Endpoints 服务:
kubectl create -f echo.yaml
如果您看到类似以下内容的错误消息:
The connection to the server localhost:8080 was refused - did you specify the right host or port?
这表示未正确配置
kubectl
。请参阅 配置 kubectl 。 如需了解详情,请参阅在 Kubernetes 上部署 Endpoints。
获取服务的外部 IP 地址
如果您使用的是 Minikube,请跳到使用 IP 地址发送请求。 在容器中启动服务后,外部 IP 地址可能需要过几分钟才可以使用。
要查看服务的外部 IP 地址,请执行以下操作:
运行以下命令:
kubectl get service
请记下 EXTERNAL-IP 的值。在向示例 API 发送请求时,您需要使用该 IP 地址。
使用 IP 地址发送请求
在容器集群中运行示例 API 之后,您可以向 API 发送请求。
创建 API 密钥并设置环境变量
示例代码需要 API 密钥。为简化请求,请为 API 密钥设置环境变量。
在您用于 API 的同一 Google Cloud 项目中,在 API 凭据页面上创建 API 密钥。如果要在其他 Google Cloud 项目中创建 API 密钥,请参阅在 Google Cloud 项目中启用 API。
- 点击创建凭据,然后选择 API 密钥。
- 将密钥复制到剪贴板。
- 点击关闭。
- 在本地计算机上,粘贴 API 密钥以将其分配给环境变量:
- 在 Linux 或 macOS 中:
export ENDPOINTS_KEY=AIza...
- 在 Windows PowerShell 中:
$Env:ENDPOINTS_KEY="AIza..."
- 在 Linux 或 macOS 中:
将请求发送到 minikube
以下命令使用您先前设置的 ENDPOINTS_KEY 环境变量。
Linux 或 macOS
NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
--header "content-type:application/json" \
--data '{"message":"hello world"}' \
${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}
PowerShell
$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content
将请求发送到其他 Kubernetes 集群
Linux 或 macOS
通过 curl
使用之前设置的 ENDPOINTS_KEY 环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"
在上面的 curl
中:
--data
选项用于指定要发布到 API 的数据。--header
选项用于指定数据采用 JSON 格式。
PowerShell
通过 Invoke-WebRequest
使用之前设置的 ENDPOINTS_KEY
环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' ` -Headers @{"content-type"="application/json"} ` -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content
在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest。
第三方应用
您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:
- 选择
POST
作为 HTTP 谓词。 - 对于标头,请选择键
content-type
和值application/json
。 - 对于正文,请输入以下内容:
{"message":"hello world"}
-
在网址中,使用实际的 API 密钥,而非环境变量。例如:
http://192.0.2.0:80/echo?key=AIza...
API 会回显您发送的消息,并以如下内容作为响应:
{
"message": "hello world"
}
如果未成功收到响应,请参阅排查响应错误。
您刚刚在 Endpoints 中部署并测试了一个 API!
跟踪 API 活动
要跟踪 API 活动,请执行以下操作:
在 Endpoints > 服务页面中查看您的 API 的活动图表。
请求可能需要一些时间才能体现在图表中。在“日志浏览器”页面中查看 API 的请求日志。
为 Endpoints 配置 DNS
由于 API 的 Endpoints 服务名称在 .endpoints.YOUR_PROJECT_ID.cloud.goog
域名中,因此您在 openapi.yaml
文件中稍微更改一下配置,即可将该名称用作完全限定的域名 (FQDN)。这样,您就可使用 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
(而非 IP 地址)向示例 API 发送请求。
如需配置 Endpoints DNS,请执行以下操作:
- 打开 OpenAPI 配置文件
openapi.yaml
,并在该文件的顶层添加x-google-endpoints
属性(请勿使用缩进或嵌套结构),如以下代码段所示:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" target: "IP_ADDRESS"
- 在
name
属性中,将 YOUR_PROJECT_ID 替换为您的项目 ID。 - 在
target
属性中,将 IP_ADDRESS 替换为您向示例 API 发送请求时使用的 IP 地址。 - 将更新后的 OpenAPI 配置文件部署到 Service Management:
gcloud endpoints services deploy openapi.yaml
例如,假设 openapi.yaml
文件进行了以下配置:
host: "echo-api.endpoints.example-project-12345.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.example-project-12345.cloud.goog" target: "192.0.2.1"
使用上述 gcloud
命令部署 openapi.yaml
文件时,Service Management 会创建一条 DNS A 记录 echo-api.endpoints.my-project-id.cloud.goog
,该记录将解析为目标 IP 地址 192.0.2.1
。新 DNS 配置可能需要几分钟的时间才能传播。
配置 SSL
如需详细了解如何配置 DNS 和 SSL,请参阅为 Endpoints 启用 SSL。
向 FQDN 发送请求
在为示例 API 配置 DNS 记录后,请使用 FQDN(将 YOUR_PROJECT_ID 替换为您的项目 ID)和先前设置的 ENDPOINTS_KEY 环境变量向该 API 发送请求:- 在 Linux 或 Mac OS 中:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
- 在 Windows PowerShell 中:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content
为 API 创建开发者门户
您可以使用 Cloud Endpoints 门户来创建开发者门户,一个供您与示例 API 进行交互的网站。如需了解详情,请参阅 Cloud Endpoints 门户概览。
清除数据
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。
- 删除 Kubernetes 服务和部署:
kubectl delete -f echo.yaml
请参阅 删除 API 和 API 实例 了解有关停止本教程使用的服务的信息。