添加 API 管理

Cloud Endpoints Frameworks 提供的 API 管理功能可与 Extensible Service Proxy (ESP) 为 Cloud Endpoints 提供的功能相媲美。Endpoints Frameworks 包括 内置 API 网关 会拦截所有请求并执行任何必要的检查，例如 身份验证，然后再将请求转发到 API 后端。当后端响应时，Endpoints Frameworks 会收集遥测数据并进行报告。您可以在 Google Cloud 控制台中的 Endpoints > Services 页面上查看 API 的指标。

Endpoints Frameworks 中提供了以下 API 管理功能：

要将您的 API 交给 Endpoints 来管理，您必须根据 2.0 版 OpenAPI 规范部署一个用于描述您的 API 的 OpenAPI 文档。 本页面介绍如何生成和部署 OpenAPI 文档，以借助 Endpoints 来管理您的 API。

如果您不添加 API 管理，您的 API 仍会处理请求， 端点上没有显示此 API。Services 页面中的 Google Cloud 控制台提供的功能 Cloud Endpoints（例如日志记录、监控和设置配额） 可用。

要为您的 API 添加 API 管理功能，请执行以下操作：

  1. 按照配置构件文件中的说明来设置 Maven pom.xml 文件或 Gradle build.gradle 文件。

  2. 确保您在构建文件中设置 Google Cloud 项目 ID。

    Maven

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

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

    <endpoints.project.id>YOUR_PROJECT_ID</endpoints.project.id>

    Gradle

    1. 搜索 def projectId，并将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如：

      def projectId = 'example-project-12345'

    2. 请确保您的 build.gradle 文件包含 replaceProjectId 任务，该任务会在 appengine-web.xml 和 web.xml 文件中设置项目 ID。 

      task replaceProjectId(type: Copy) {
    from 'src/main/webapp/WEB-INF/'
    include '*.xml'
    into "build/exploded-${archivesBaseName}/WEB-INF"
    expand(endpoints:[project:[id:projectId]])
    filteringCharset = 'UTF-8'
}

  3. 在 API 项目的 web.xml 文件中，添加 API 管理 Servlet 过滤器配置：

    <!-- Add a filter that fetches the service config from service management. -->
<filter>
    <filter-name>endpoints-api-configuration</filter-name>
    <filter-class>com.google.api.control.ServiceManagementConfigFilter</filter-class>
</filter>

<!-- Add a filter that performs Endpoints logging and monitoring. -->
<filter>
    <filter-name>endpoints-api-controller</filter-name>
    <filter-class>com.google.api.control.extensions.appengine.GoogleAppEngineControlFilter</filter-class>
    <init-param>
        <param-name>endpoints.projectId</param-name>
        <param-value>${endpoints.project.id}</param-value>
    </init-param>
    <init-param>
        <param-name>endpoints.serviceName</param-name>
        <param-value>${endpoints.project.id}.appspot.com</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>endpoints-api-configuration</filter-name>
    <servlet-name>EndpointsServlet</servlet-name>
</filter-mapping>

<filter-mapping>
    <filter-name>endpoints-api-controller</filter-name>
    <servlet-name>EndpointsServlet</servlet-name>
</filter-mapping>

  4. 修改 API 项目的构建配置：

    Maven

    1. 添加 API 管理依赖项：

      <dependency>
  <groupId>com.google.endpoints</groupId>
  <artifactId>endpoints-management-control-appengine-all</artifactId>
  <version>1.0.14</version>
</dependency>

    2. 添加可用于生成客户端库和 OpenAPI 文档 openapi.json 的插件：

      <plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>endpoints-framework-maven-plugin</artifactId>
  <version>2.1.0</version>
  <configuration>
    <!-- plugin configuration -->
    <hostname>${endpoints.project.id}.appspot.com</hostname>
  </configuration>
</plugin>

    Gradle

    1. 添加 API 管理依赖项：

      compile 'com.google.endpoints:endpoints-management-control-appengine:1.0.14'
compile 'com.google.endpoints:endpoints-framework-auth:1.0.14'

    2. 声明外部依赖项，以便从 Maven Central 检索插件：

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'

    3. 使用服务器端 Endpoints Frameworks Gradle 插件以生成 OpenAPI 文档：

      apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

    4. 配置 Endpoints 服务的名称：

      endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "${projectId}.appspot.com"
}

  5. 修改依赖项后，清理项目并构建您的 API：

    Maven

        mvn clean
    mvn package

    Gradle

        gradle clean
    gradle build

  6. 生成 OpenAPI 文档 openapi.json：

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs

  7. 部署 OpenAPI 文档：

     gcloud endpoints services deploy openapi.json

    第一次部署 openapi.json 时，系统会创建名为 YOUR_PROJECT_ID.appspot.com 的新 Endpoints 服务。成功完成后，您会看到如下所示的行，其中显示服务配置 ID 和服务名称：

    Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com

    在上面的示例中，2017-02-13r0 是服务配置 ID。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您再次部署 openapi.json，则服务配置 ID 中的修订版本号将递增。

    如果您需要再次显示服务配置 ID，请运行以下命令，但需将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目的 ID：

    gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com

    您可以自定义 OpenAPI 文档并进行部署，而不使用生成的文档。只需将上述 openapi.json 替换为 OpenAPI 文档的路径即可。如需详细了解如何编写 OpenAPI 文档，请参阅 OpenAPI 概览。

  8. 修改您的 appengine-web.xml 文件以设置环境变量的值：

    <env-variables>
    <env-var name="ENDPOINTS_SERVICE_NAME" value="${endpoints.project.id}.appspot.com" />
</env-variables>

    将 ${endpoints.project.id} 替换为您的 Google Cloud 项目 ID。 例如：

    <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project-12345.appspot.com" />

  9. 重新部署您的应用。

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

  10. 向您的 API 发出一些请求以进行测试。

  11. 如需查看 API 指标，请在 Google Cloud 控制台中打开项目的 Endpoints > Services 页面：

    转到“Endpoints 服务”页面