Java 版 Cloud Endpoints Frameworks 使用入门

安装和配置所需的软件

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 服务部署。

检查所需服务

在大多数情况下，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. 向本地实例发送请求：

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

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 发送请求。

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

(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

API 会回显您向其发送的消息，并以如下内容作为响应：

{
 "message": "hello world"
}

如果未成功收到响应，请参阅排查响应错误。

您刚刚在 Endpoints Frameworks 中部署并测试了一个 API！

跟踪 API 活动

1. 在 Google Cloud 控制台中，依次前往 Endpoints > Service 页面，查看 API 的活动图表。

   转到“Endpoints 服务”页面

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

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

   转到“日志浏览器”页面

为 API 创建开发者门户

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