開始使用 Java 適用的 Cloud Endpoints Frameworks

本頁說明如何利用 Java 適用的 Cloud Endpoints Frameworks 來設定、部署要求，以及將要求傳送至範例 API。 Java 適用的 Endpoints Frameworks 已經與 App Engine 標準 Java 8 執行階段環境整合。Endpoints Frameworks 的工具、程式庫以及功能，可讓您從 App Engine 應用程式產生 API 和用戶端程式庫。

安裝並設定所需的軟體

  1. 如果您還沒有安裝 Java 8，請從 Oracle 下載 Java Development Kit (JDK)，然後安裝該套件。Java 專用的 Endpoints Frameworks 需要 App Engine 標準 Java 8 執行階段環境，因此 Endpoints Frameworks 不支援任何其他版本的 Java。
  2. 如果您沒有 Maven 3.3.9 以上版本，請先下載並安裝。

    3. Windows 使用者請注意：如果您要在 Windows 上安裝 JDK 和 Maven，請將它們安裝在路徑中不含空格的目錄中。詳情請參閱 Maven on Windows。

  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

程式碼範例包含能產生 OpenAPI 設定檔的 Endpoints Frameworks 工具，而該設定檔可描述程式碼範例的 REST API。請按照本節中的步驟設定及建構範例 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 設定；服務基礎架構是 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 服務部署一文。

檢查必要服務

如要提供 API 管理，Endpoints Frameworks 需要使用以下服務：
名稱 標題
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

在大多數情況下，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. 將要求傳送到本機執行個體：

Linux 或 Mac OS

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

在上方的 curl 中：

  • --data 選項會指定要發布至 API 的資料。
  • --header 選項會指定資料採用 JSON 格式。

PowerShell

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

在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。 如要瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。

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 發送要求。

Linux 或 Mac OS

請利用 curl 傳送 HTTP 要求，將 [YOUR_PROJECT_ID] 替換為您的專案 ID：Google Cloud 

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

在上方的 curl 中：

  • --data 選項會指定要發布至 API 的資料。
  • --header 選項會指定資料採用 JSON 格式。

PowerShell

請利用 Invoke-WebRequest 傳送 HTTP 要求，將 [YOUR_PROJECT_ID] 替換為您的專案 ID： Google Cloud 

(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

在上述範例中，前兩行的結尾為倒引號。當您將範例貼到 PowerShell 中時，請確保倒引號後面沒有空格。 如要瞭解範例要求中使用的選項，請參閱 Microsoft 說明文件中的 Invoke-WebRequest。

第三方應用程式

您可以使用諸如 Chrome 瀏覽器擴充功能 Postman 等第三方應用程式，傳送要求：

  • 選取 POST 做為 HTTP 動詞。
  • 選取 content-type 鍵和 application/json 值做為標頭。
  • 輸入以下內文：
    {"message":"hello world"}
  • 請輸入範例應用程式的網址，例如：
    https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

API 會回應您傳送給它的訊息，並回覆以下內容：

{
 "message": "hello world"
}

如果您沒有收到成功的回應，請參閱排解回應錯誤一文。

您已成功在 Endpoints Frameworks 中部署並測試 API 了！

追蹤 API 活動

  1. 在 Google Cloud 主控台的「Endpoints」 >「Service」(服務) 頁面上，檢視您 API 的活動圖表。

    前往 Endpoints 服務頁面

    要求可能需要一些時間才能反映在圖表中。

  2. 在「Logs Explorer」(記錄檔探索工具) 頁面中查看您的 API 要求記錄。

    前往「Logs Explorer」(記錄檔探索工具) 頁面

建立 API 開發人員入口網站

您可以透過 Cloud Endpoints 入口網站建立開發人員入口網站，並將該網站用於與範例 API 進行互動。詳情請參閱 Cloud Endpoints 入口網站總覽。