Java 版 Cloud Endpoints Frameworks 使用入门

---

本页面介绍如何使用 Java 版 Cloud Endpoints Frameworks 配置和部署示例 API，并向该 API 发送请求。 Java 版 Endpoints Frameworks 集成了 App Engine 标准 Java 8 运行时环境。Endpoints Frameworks 具备各种工具、库和功能，可供您通过 App Engine 应用生成 API 和客户端库。

目标

学习本教程时，请使用以下概要任务列表。为确保请求成功发送到 API，您必须完成所有任务。

1. 设置 Google Cloud 项目。请参阅准备工作。
2. 安装所需的软件并创建 App Engine 应用。请参阅安装和配置所需的软件。
3. 下载示例代码。请参阅获取示例代码。
4. 生成 OpenAPI 配置文件。请参阅配置 Cloud Endpoints。
5. 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
6. 在计算机上运行该示例。请参阅在本地运行示例。
7. 创建后端，以提供 API 并部署 API。请参阅部署 API 后端。
8. 向 API 发送请求。请参阅向 API 发送请求。
9. 跟踪 API 活动。请参阅跟踪 API 活动。
10. 避免系统向您的 Google Cloud 账号收费。请参阅清理。

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

• Endpoints
• App Engine

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. 记下项目 ID，稍后需要用到。

安装和配置所需的软件

1. 如果您尚未安装 Java 8，请从 Oracle 网站下载 Java Development Kit (JDK) 并安装。由于 Java 版 Endpoints Frameworks 依赖于 App Engine 标准 Java 8 运行时环境，因此 Endpoints Frameworks 不支持任何其他版本的 Java。
2. 如果您没有 Maven 3.3.9 或更高版本，请下载并安装。

Windows 用户注意事项：如果要在 Windows 上安装 JDK 和 Maven，请将它们安装在路径不含空格的目录中。如需了解详情，请参阅 Windows 上的 Maven。

3. 您需要一个应用来向示例 API 发送请求。

   • Linux 和 macOS 用户：本教程提供了一个使用 curl 的示例，它通常已预装在您的操作系统中。如果您没有 curl，可以从 curl 版本和下载页面中下载。
   • Windows 用户：本教程提供了一个使用 Invoke-WebRequest 的示例，PowerShell 3.0 及更高版本支持该命令。
4. 安装并初始化 Google Cloud CLI。
5. 运行以下命令：
   1. 确保 gcloud CLI 有权访问您在 Google Cloud 上的数据和服务：

      gcloud auth login

   2. 使用应用默认凭据：

      gcloud auth application-default login

   3. 安装 Google Cloud SDK app-engine-java 组件：

      gcloud components install app-engine-java

   4. 更新为 Google Cloud SDK 和所有组件的最新版本：

      gcloud components update

6. 创建一个 App Engine 应用：
   1. 将默认项目设置为您的项目 ID。

      gcloud config set project YOUR_PROJECT_ID

      将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。如果您有其他 Google Cloud 项目，并且想使用 gcloud 管理它们，请参阅管理 gcloud CLI 配置。

   2. 选择要在其中创建 App Engine 应用的区域。运行以下命令以获取区域列表：

      gcloud app regions list

   3. 使用以下命令创建 App Engine 应用。将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID，并将 YOUR_REGION 替换为您要在其中创建 App Engine 应用的区域。

      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION

获取示例代码

要从 GitHub 克隆示例 API，请执行以下操作：

1. 将示例代码库克隆到本地计算机：

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples
   

2. 切换到包含示例代码的目录：

   cd java-docs-samples/appengine-java8/endpoints-v2-backend
   

配置 Endpoints

示例代码包含 Endpoints Frameworks 工具，该工具生成描述示例代码的 REST API 的 OpenAPI 配置文件。按照本部分中的步骤配置和构建示例 Maven 项目，以便生成 OpenAPI 配置文件。

将项目 ID 添加到示例 API 代码

您必须将创建项目时获得的项目 ID 添加到示例的 pom.xml 中，才能部署代码。

如需添加项目 ID，请执行以下操作：

1. 修改文件 java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml。

2. 搜索 <endpoints.project.id>，并将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。

   例如：

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. 保存更改。

构建示例项目

如需构建项目，请执行以下操作：

1. 确保您位于 java-docs-samples/appengine-java8/endpoints-v2-backend 目录中。

2. 运行以下命令：

   mvn clean package
   

3. 等待项目构建。项目成功完成后，您将看到类似下方内容的消息：

   [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 配置文件，请执行以下操作：

1. 使用以下命令调用 Endpoints Frameworks 工具：

   mvn endpoints-framework:openApiDocs
   

2. 等待配置规范构建完成。完成后，您将看到类似下方内容的消息：

   OpenAPI document written to target/openapi-docs/openapi.json
   

   忽略有关无法加载静态日志记录器类的任何消息。

部署 Endpoints 配置

要部署 Endpoints 配置，请使用 Service Infrastructure，这是 Google 的基础服务平台，供 Endpoints Frameworks 和其他服务用来创建和管理 API 和服务。

如需部署配置文件，请执行以下操作：

1. 确保您位于 java-docs-samples/appengine-java8/endpoints-v2-backend 目录中。

2. 部署在上一部分中生成的 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.com
gcloud 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 配置后，您可以在本地运行该示例。

1. 创建一个名为 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"
   

2. 获取新的用户凭据，以用于应用默认凭据：

   gcloud auth application-default login
   

3. 运行开发服务器：

   mvn appengine:run
   

   可以在 http://localhost:8080 上访问本地实例，如 mvn appengine:run 命令输出的日志所示：

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. 向本地实例发送请求：

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 后端，请执行以下操作：

1. 确保您位于 java-docs-samples/appengine-java8/endpoints-v2-backend 目录中

2. 使用 Maven 部署 API 实现代码：

    mvn appengine:deploy
   

   首次上传示例应用时，系统可能会提示您授权部署。请按照提示操作。当您看到包含代码的浏览器窗口时，将其复制到终端窗口。

3. 等待上传完成。

   建议您等待几分钟，在 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！

注意：如果您想告诉我们您对本教程的看法，请在本页底部提供反馈。您的反馈有助于我们改进这些教程。
如果您遇到错误，请加入 google-cloud-endpoints Google 群组，告诉我们您遇到的问题。在该论坛中，您会收到来自其他 Endpoints 用户和负责监控该论坛的 Google 工程师的回复。

跟踪 API 活动

1. 在 Google Cloud 控制台中查看 API 的活动图表，网址为： 端点 >服务页面。

   转到“Endpoints 服务”页面

   请求可能需要一些时间才能体现在图表中。

2. 在“日志浏览器”页面中查看 API 的请求日志。

   转到“日志浏览器”页面

为 API 创建开发者门户

您可以使用 Cloud Endpoints 门户来创建开发者门户，一个供您与示例 API 进行交互的网站。如需了解详情，请参阅 Cloud Endpoints 门户概览。

清除数据

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

注意：删除项目会产生以下影响：
• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

后续步骤

• 了解 Endpoints Frameworks 架构。
• 了解可用的 API 注释。
• 了解如何使用其他路径提供 API。
• 了解如何监控您的 API。
• 了解如何使用 API 密钥限制访问权限。
• 了解如何处理 API 版本控制。
• 了解社区支持选项。