Java 版 Cloud Endpoints Frameworks 使用入门

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

安装和配置所需的软件

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

在大多数情况下，gcloud endpoints services deploy 命令会启用这些必需的服务。但在以下情况下，gcloud 命令会成功完成，但不启用必需的服务：

• 您使用了 Terraform 之类的第三方应用，但未添加这些服务。

• 您将 Endpoints 配置部署到已明确停用这些服务的现有Google Cloud 项目。

使用以下命令确认必需服务是否已启用：

gcloud services list

如果您没有看到列出的必需服务，请启用它们：

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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 服务。

在本地运行示例

部署 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 控制台的 Endpoints > 服务页面上查看 API 的活动图表。

   转到“Endpoints 服务”页面

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

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

   转到“日志浏览器”页面

为 API 创建开发者门户

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