添加 API 管理

Cloud Endpoints Frameworks 提供的 API 管理功能与 Extensible Service Proxy (ESP) 为 Cloud Endpoints 提供的功能相近。Endpoints Frameworks 内置了一个 API 网关,该网关会拦截所有请求并执行所有必要的检查(例如身份验证),然后将请求转发到 API 后端。当后端响应时,Endpoints Frameworks 会收集遥测数据并进行报告。您可以在 Google Cloud Console 中的 Endpoints > 服务页面上查看 API 的指标。

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

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

如果您未添加 API 管理功能,您的 API 仍会处理请求,但它不会显示在 Cloud Console 的 Endpoints > 服务页面上,并且 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.xmlweb.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.13</version>
      </dependency>
    2. 添加可用于生成客户端库和 OpenAPI 文档 openapi.json 的插件:

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>endpoints-framework-maven-plugin</artifactId>
        <version>2.0.1</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.12'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.12'
    2. 声明外部依赖项,以便从 Maven Central 检索插件:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.0.1'
    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 指标,请在 Cloud Console 中打开项目的 Endpoints > 服务页面:

    转到“Endpoints 服务”页面