本页面介绍如何使用 Java 版 Cloud Endpoints Frameworks 配置和部署示例 API,并向该 API 发送请求。 Java 版 Endpoints Frameworks 集成了 App Engine 标准 Java 8 运行时环境。Endpoints Frameworks 具备各种工具、库和功能,可供您通过 App Engine 应用生成 API 和客户端库。
目标
学习本教程时,请使用以下概要任务列表。为确保请求成功发送到 API,您必须完成所有任务。
- 设置 Google Cloud 项目。请参阅准备工作。
- 安装所需的软件并创建 App Engine 应用。请参阅安装和配置所需的软件。
- 下载示例代码。请参阅获取示例代码。
- 生成 OpenAPI 配置文件。请参阅配置 Cloud Endpoints。
- 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
- 在计算机上运行该示例。请参阅在本地运行示例。
- 创建后端,以提供 API 并部署 API。请参阅部署 API 后端。
- 向 API 发送请求。请参阅向 API 发送请求。
- 跟踪 API 活动。请参阅跟踪 API 活动。
- 避免系统向您的 Google Cloud 账号收费。请参阅清理。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
您可使用价格计算器根据您的预计使用情况来估算费用。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
准备工作
- 登录您的 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.
- 记下项目 ID,稍后需要用到。
安装和配置所需的软件
- 如果您尚未安装 Java 8,请从 Oracle 网站下载 Java Development Kit (JDK) 并安装。由于 Java 版 Endpoints Frameworks 依赖于 App Engine 标准 Java 8 运行时环境,因此 Endpoints Frameworks 不支持任何其他版本的 Java。
- 如果您没有 Maven 3.3.9 或更高版本,请下载并安装。
-
您需要一个应用来向示例 API 发送请求。
- Linux 和 macOS 用户:本教程提供了一个使用
curl
的示例,它通常已预装在您的操作系统中。如果您没有curl
,可以从curl
版本和下载页面中下载。 - Windows 用户:本教程提供了一个使用
Invoke-WebRequest
的示例,PowerShell 3.0 及更高版本支持该命令。
- Linux 和 macOS 用户:本教程提供了一个使用
- 安装并初始化 Google Cloud CLI。
- 运行以下命令:
- 确保 gcloud CLI 有权访问您在 Google Cloud 上的数据和服务:
gcloud auth login
- 使用应用默认凭据:
gcloud auth application-default login
- 安装 Google Cloud SDK
app-engine-java
组件:gcloud components install app-engine-java
- 更新为 Google Cloud SDK 和所有组件的最新版本:
gcloud components update
- 确保 gcloud CLI 有权访问您在 Google Cloud 上的数据和服务:
- 创建一个 App Engine 应用:
-
将默认项目设置为您的项目 ID。
gcloud config set project YOUR_PROJECT_ID
将
YOUR_PROJECT_ID
替换为您的 Google Cloud 项目 ID。如果您有其他 Google Cloud 项目,并且想使用gcloud
管理它们,请参阅管理 gcloud CLI 配置。 - 选择要在其中创建 App Engine 应用的区域。运行以下命令以获取区域列表:
gcloud app regions list
- 使用以下命令创建 App Engine 应用。将
YOUR_PROJECT_ID
替换为您的 Google Cloud 项目 ID,并将YOUR_REGION
替换为您要在其中创建 App Engine 应用的区域。gcloud app create \ --project=YOUR_PROJECT_ID \ --region=YOUR_REGION
-
将默认项目设置为您的项目 ID。
Windows 用户注意事项:如果要在 Windows 上安装 JDK 和 Maven,请将它们安装在路径不含空格的目录中。如需了解详情,请参阅 Windows 上的 Maven。
获取示例代码
要从 GitHub 克隆示例 API,请执行以下操作:
将示例代码库克隆到本地计算机:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
切换到包含示例代码的目录:
cd java-docs-samples/appengine-java8/endpoints-v2-backend
配置 Endpoints
示例代码包含 Endpoints Frameworks 工具,该工具生成描述示例代码的 REST API 的 OpenAPI 配置文件。按照本部分中的步骤配置和构建示例 Maven 项目,以便生成 OpenAPI 配置文件。
将项目 ID 添加到示例 API 代码
您必须将创建项目时获得的项目 ID 添加到示例的 pom.xml
中,才能部署代码。
如需添加项目 ID,请执行以下操作:
修改文件
java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml
。搜索
<endpoints.project.id>
,并将YOUR_PROJECT_ID
替换为您的 Google Cloud 项目 ID。例如:
<endpoints.project.id>example-project</endpoints.project.id>
保存更改。
构建示例项目
如需构建项目,请执行以下操作:
确保您位于
java-docs-samples/appengine-java8/endpoints-v2-backend
目录中。运行以下命令:
mvn clean package
等待项目构建。项目成功完成后,您将看到类似下方内容的消息:
[INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 14.846s [INFO] Finished at: Wed April 13 09:43:09 PDT 2016 [INFO] Final Memory: 24M/331M
生成 OpenAPI 配置文件
您可以使用 Endpoints Frameworks 库中的工具生成名为 openapi.json
的 OpenAPI 文档。此文件描述了示例代码的 REST API。
要生成 OpenAPI 配置文件,请执行以下操作:
使用以下命令调用 Endpoints Frameworks 工具:
mvn endpoints-framework:openApiDocs
等待配置规范构建完成。完成后,您将看到类似下方内容的消息:
OpenAPI document written to target/openapi-docs/openapi.json
忽略有关无法加载静态日志记录器类的任何消息。
部署 Endpoints 配置
要部署 Endpoints 配置,请使用 Service Infrastructure,这是 Google 的基础服务平台,供 Endpoints Frameworks 和其他服务用来创建和管理 API 和服务。
如需部署配置文件,请执行以下操作:
确保您位于
java-docs-samples/appengine-java8/endpoints-v2-backend
目录中。部署在上一部分中生成的 OpenAPI 配置文件:
gcloud endpoints services deploy target/openapi-docs/openapi.json
这将创建一个新的 Endpoints 服务,其名称格式为 YOUR_PROJECT_ID.appspot.com
。此名称在 pom.xml
和示例中包含的其他配置文件中配置。请注意,在 App Engine 上部署 API 时,系统会使用名称格式 YOUR_PROJECT_ID.appspot.com
创建一条 DNS 记录,该记录是您向 API 发送请求时使用的完全限定域名 (FQDN)。
在创建和配置服务时,Service Management 会向终端输出信息。您尽可忽略有关 openapi.json
中的路径未要求 API 密钥的警告。成功完成后,您会看到如下所示的行,其中显示服务配置 ID 和服务名称:
Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]
在上面的示例中,2017-02-13-r2
是服务配置 ID,example-project-12345.appspot.com
是服务名称。
如需了解详情,请参阅 gcloud
Endpoints 服务部署。
检查所需服务
要提供 API 管理功能,Endpoints Frameworks 需要以下服务:名称 | 标题 |
---|---|
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_SERVICE_NAME 列表。
对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的
host
字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的name
字段中指定的值。
如需详细了解 gcloud
命令,请参阅 gcloud
服务。
在本地运行示例
部署 Endpoints 配置后,您可以在本地运行该示例。
创建一个名为
ENDPOINTS_SERVICE_NAME
的环境变量,该变量在示例的appengine-web.xml
文件中用于设置主机名。在以下命令中,将YOUR_PROJECT_ID
替换为您的 Google Cloud 项目 ID。在 Linux 或 Mac OS 中:
export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
在 Windows PowerShell 中:
$Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
获取新的用户凭据,以用于应用默认凭据:
gcloud auth application-default login
运行开发服务器:
mvn appengine:run
可以在
http://localhost:8080
上访问本地实例,如mvn appengine:run
命令输出的日志所示:[INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
向本地实例发送请求:
Linux 或 Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
在上面的 curl
中:
--data
选项用于指定要发布到 API 的数据。--header
选项用于指定数据采用 JSON 格式。
PowerShell
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").Content
在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 要了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest。
API 会回显您向其发送的消息,并以如下内容作为响应:
{
"message": "hello world"
}
部署 API 后端
到目前为止,您已将 OpenAPI 配置部署到 Service Management,但尚未部署将用于提供 API 后端的代码。此部分将引导您将示例 API 部署到 App Engine。
如需部署 API 后端,请执行以下操作:
确保您位于
java-docs-samples/appengine-java8/endpoints-v2-backend
目录中使用 Maven 部署 API 实现代码:
mvn appengine:deploy
首次上传示例应用时,系统可能会提示您授权部署。请按照提示操作。当您看到包含代码的浏览器窗口时,将其复制到终端窗口。
等待上传完成。
建议您等待几分钟,在 App Engine 完全初始化后向 API 发送请求。
向 API 发送请求
部署 API 及其配置文件后,您可以向 API 发送请求。
Linux 或 Mac OS
使用 curl
发送 HTTP 请求。将 [YOUR_PROJECT_ID]
替换为您的 Google Cloud 项目 ID:
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
在上面的 curl
中:
--data
选项用于指定要发布到 API 的数据。--header
选项用于指定数据采用 JSON 格式。
PowerShell
使用 Invoke-WebRequest
发送 HTTP 请求。将 [YOUR_PROJECT_ID]
替换为您的 Google Cloud 项目 ID:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest。
第三方应用
您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:
- 选择
POST
作为 HTTP 谓词。 - 对于标头,请选择键
content-type
和值application/json
。 - 对于正文,请输入以下内容:
{"message":"hello world"}
-
输入示例应用的网址。例如:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo
API 会回显您向其发送的消息,并以如下内容作为响应:
{
"message": "hello world"
}
如果未成功收到响应,请参阅排查响应错误。
您刚刚在 Endpoints Frameworks 中部署并测试了一个 API!
跟踪 API 活动
在 Google Cloud 控制台中查看 API 的活动图表,网址为: 端点 >服务页面。
请求可能需要一些时间才能体现在图表中。
在“日志浏览器”页面中查看 API 的请求日志。
为 API 创建开发者门户
您可以使用 Cloud Endpoints 门户来创建开发者门户,一个供您与示例 API 进行交互的网站。如需了解详情,请参阅 Cloud Endpoints 门户概览。
清除数据
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
后续步骤
- 了解 Endpoints Frameworks 架构。
- 了解可用的 API 注释。
- 了解如何使用其他路径提供 API。
- 了解如何监控您的 API。
- 了解如何使用 API 密钥限制访问权限。
- 了解如何处理 API 版本控制。
- 了解社区支持选项。