開始使用 Java 適用的 Endpoints Frameworks

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

工作清單

在逐步進行本教學課程時，請使用以下的高階工作清單。您必須完成所有工作，才能將要求成功傳送至 API。

  1. 設定 Google Cloud Platform (GCP) 專案。請參閱事前準備一節。
  2. 安裝所需的軟體，並建立一個 App Engine 應用程式。請參閱安裝並設定所需的軟體一節。
  3. 下載程式碼範例。請參閱取得程式碼範例一節。
  4. 產生一個 OpenAPI 設定檔。請參閱設定 Cloud Endpoints 一節。
  5. 部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
  6. 在您的電腦上執行範例。請參閱在本機執行範例一節。
  7. 建立後端以提供及部署 API。請參閱部署 API 後端一節。
  8. 傳送要求至 API。請參閱傳送要求至 API 一節。
  9. 追蹤 API 活動。請參閱追蹤 API 活動一節。
  10. 避免系統向您的 GCP 帳戶收取相關費用。請參閱清除一節。

事前準備

  1. 登入您的 Google 帳戶。

    如果您沒有帳戶，請申請新帳戶。

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

  4. 記下專案 ID，以便在稍後使用。

安裝並設定所需的軟體

  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. 下載並且初始化 Cloud SDK。
  5. 執行下列指令：
    1. 確認 Cloud SDK 已取得授權，可存取您在 GCP 上的資料與服務：
      gcloud auth login
    2. 使用應用程式預設憑證：
      gcloud auth application-default login
    3. 安裝 Cloud SDK app-engine-java 元件：
      gcloud components install app-engine-java
    4. 將 Cloud SDK 以及所有元件更新至最新版本：
      gcloud components update
  6. 建立 App Engine 應用程式：
    1. 將預設專案設為您的專案 ID。
      gcloud config set project [YOUR_PROJECT_ID]

      請將 [YOUR_PROJECT_ID] 替換成您的 GCP 專案 ID。如果您有其他 GCP 專案，而且想要使用 gcloud 來管理這些專案，請參閱管理 Cloud SDK 設定。

    2. 選取您要在其中建立 App Engine 應用程式的地區。請執行以下指令來取得區域清單：
      gcloud app regions list
    3. 使用下列指令來建立 App Engine 應用程式。請將 [YOUR_PROJECT_ID] 替換成您的 {[gcp_name_short}} 專案 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 替換成您的 GCP 專案 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 服務部署。

在本機執行範例

部署 Endpoints 設定之後，您便可以在本機執行範例。

  1. 建立名為 ENDPOINTS_SERVICE_NAME 的環境變數，您會在範例的 appengine-web.xml 檔案中使用該變數來設定主機名稱。請將以下指令中的 [YOUR_PROJECT_ID] 替換成您的 GCP 專案 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] 替換成您的 GCP 專案 ID：

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] 替換成您的 GCP 專案 ID：

(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. 在 GCP 主控台的「Endpoints」>「Service」(服務) 頁面上，檢視您 API 的活動圖表。

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

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

  2. 在「Logs Viewer」(記錄檢視器) 頁面中，查看您的 API 要求記錄。

    前往「Logs Viewer」(記錄檢視器) 頁面

建立 API 開發人員入口網站

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

清除

如何避免系統向您的 GCP 帳戶收取您在本快速入門中所用資源的相關費用：

  1. 前往 GCP 主控台的「Projects」(專案) 頁面。

    前往專案頁面

  2. 在專案清單中選取要刪除的專案，然後按一下 [Delete] (刪除)。
  3. 在對話方塊中輸入專案 ID，按一下 [Shut down] (關閉) 即可刪除專案。

後續步驟

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

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

這個網頁
文件意見
App Engine 適用的 Cloud Endpoints Frameworks
產品意見
需要協助嗎？請前往我們的支援網頁。