新增 API 管理

Cloud Endpoints Frameworks 提供 API 管理功能，這些功能相當於可擴充服務 Proxy (ESP) 為 Cloud Endpoints 提供的功能。Endpoints Frameworks 包含內建 API 閘道，可攔截所有要求並執行所有必要的檢查 (例如驗證)，然後再將要求轉送至 API 後端。當後端回應時，Endpoints Frameworks 會收集並回報遙測資料。您可以在Google Cloud console 中，依序前往「Endpoints」>「Services」(服務) 頁面查看 API 的指標。

Endpoints Frameworks 提供的 API 管理功能包含：

如要讓 Endpoints 管理您的 API，您必須部署 OpenAPI 文件，且此文件應使用 OpenAPI 規範 2.0 版說明 API。 本頁說明如何產生及部署可讓 Endpoints 管理您 API 的 OpenAPI 文件。

如果您不新增 API 管理設定，API 仍然會處理要求，但不會出現在Google Cloud console 的「Endpoints」>「Services」(服務) 頁面上，且您無法使用 Endpoints 提供的功能，例如記錄、監控和設定配額。

如何將 API 管理功能新增到 API：

  1. 按照「設定建構檔案」一文的說明，設定 Maven pom.xml 檔案或 Gradle build.gradle 檔案。

  2. 請務必在建構檔案中設定專案 ID。 Google Cloud

    Maven

    搜尋 <endpoints.project.id>，然後將 YOUR_PROJECT_ID 替換為您的專案 ID。 Google Cloud 例如：

    <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 替換為您的專案 ID。 Google Cloud 例如：

      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} 替換為專案 ID。 Google Cloud 例如：

    <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 服務頁面