開始使用 Java 適用的 Cloud 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 帳戶收取相關費用。請參閱清除所用資源一節。

費用

本教學課程使用下列 Google Cloud Platform 計費元件：

• 端點
• App Engine

您可以使用 Pricing Calculator 根據預測用量估算費用。初次使用 GCP 的使用者可能符合免費試用資格。

完成此教學課程後，您可刪除已建立的資源以免繼續計費。詳情請參閱清除所用資源一節。

事前準備

1. 登入您的 Google 帳戶。

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

2. 在 GCP Console 的專案選擇器頁面中，選取或建立 GCP 專案。

   注意：如果您不打算保留您在這個程序中建立的資源，請建立新的 GCP 專案，而不是選取現有的 GCP 專案。因此您在完成這些步驟之後，就可以刪除專案，並移除與該專案相關聯的所有資源。

   前往專案選取器頁面

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 以上版本，請先下載並安裝。

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 專案 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
   

設定端點

程式碼範例包含能產生 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 設定；服務基礎架構是 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
endpoints.googleapis.com	Google Cloud Endpoints

在大多數情況下，gcloud endpoints services deploy 指令會啟用這些必要服務。不過在以下情況中，即便您成功執行 gcloud 指令，還是無法啟用必要服務：

• 您使用 Terraform 之類的第三方應用程式，而其中未包含這些服務。

• 您已將 Endpoints 設定部署至現有 GCP 專案，但在專案中已明確停用這些服務。

如要確認必要服務已啟用，請執行：

gcloud services list

如果必要的服務並未列出，請執行下列指令加以啟用：

gcloud services enable SERVICE_NAME

將 SERVICE_NAME 改為要啟用的服務名稱。

如要進一步瞭解 gcloud 指令，請參閱 服務。

在本機執行範例

部署 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 了！

注意事項：如想告訴我們您對這個教學課程的想法，歡迎在本頁面底端提供意見回饋。您的意見回饋可協助我們改善教學課程。
如果您在過程中看見錯誤訊息，不妨加入 google-cloud-endpoints Google 群組，告知我們何處發生問題。其他 Endpoints 使用者和負責管理群組的 Google 工程師都可以在這個群組中發表回應。

追蹤 API 活動

1. 在 GCP Console 的「Endpoints」>「Service」(服務) 頁面上，檢視您 API 的活動圖表。

   前往 Endpoints 服務頁面

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

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

   前往記錄檢視器頁面

建立 API 開發人員入口網站

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

清除所用資源

如何避免系統向您的 Google Cloud Platform 帳戶收取在本教學課程中使用資源的相關費用：

注意：刪除專案會造成以下結果：
• 專案中的所有內容都會遭到刪除。 如果您之前使用現有的專案來進行本教學課程，當您刪除該專案時，也會一併刪除您在該專案中完成的所有其他工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。
1. 前往 GCP Console 中的「Manage resources」(管理資源) 頁面。

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

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

後續步驟

• 瞭解如何利用 JavaScript 用戶端進行驗證呼叫。
• 瞭解 Endpoints Frameworks 架構。
• 瞭解可用的 API 註解。
• 瞭解如何透過不同的路徑提供 API。
• 瞭解如何監控您的 API。
• 瞭解如何使用 API 金鑰限制存取權限。
• 瞭解如何處理 API 版本管理。
• 瞭解社群支援選項。