新增 API 管理

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

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

如要讓 Endpoints 管理您的 API,您必須部署 OpenAPI 文件,且該文件應使用 OpenAPI 規範 2.0 版描述您的 API。本頁說明如何產生及部署 OpenAPI 文件,並以此文件來啟用 Endpoints 以管理您的 API。

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

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

  1. 在 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>
  2. 修改 API 專案的建構設定:

    Maven

    1. 新增 API 管理相依項目:

      <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-management-control-appengine-all</artifactId>
        <version>1.0.11</version>
      </dependency>
    2. 納入可用來產生用戶端程式庫和 OpenAPI 文件 (openapi.json) 的外掛程式:

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>endpoints-framework-maven-plugin</artifactId>
        <version>1.0.2</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.5'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.5'
    2. 宣告外部相依項目,以便系統可從 Maven Central 擷取外掛程式:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
    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"
      }
  3. 修改相依項目之後,清除專案並建構 API:

    Maven

        mvn clean
        mvn package

    Gradle

        gradle clean
        gradle build
  4. 產生 OpenAPI 文件 openapi.json

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs
  5. 部署 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 替換成您的 GCP 專案 ID:

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

    除了使用已產生的文件,您也可以建立自己的 OpenAPI 文件並進行部署。只需將上面的 openapi.json 替換為 OpenAPI 文件的路徑即可。如要進一步瞭解如何撰寫 OpenAPI 文件,請參閱 OpenAPI 總覽

  6. 編輯 appengine-web.xml 檔案來設定環境變數的值:

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

    ${endpoints.project.id} 替換為您的 GCP 專案 ID,例如:

    <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project-12345.appspot.com" />
    
  7. 重新部署應用程式。

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

  8. 向 API 提出幾個要求來進行測試。

  9. 如要檢視 API 指標,請在 GCP 主控台中開啟您專案的「Endpoints」>「Services」(服務) 頁面:

    前往 Endpoints 的「Services」(服務) 頁面

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁