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

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

• Endpoints
• App Engine

您可以使用 Pricing Calculator 根據預測用量產生預估費用。 新 Google Cloud 使用者可能符合申請免費試用的資格。

完成本文件所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱「清除所用資源」。

事前準備

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. 記下專案 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. 下載並初始化 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」頁面。Service name 欄下方會列出可能的 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] 替換為您的Google Cloud 專案 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] 替換為您的 Google Cloud 專案 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. 在 Google Cloud 主控台的「Endpoints」 >「Service」頁面上，查看 API 的活動圖表。

   前往 Endpoints 服務頁面

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

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

   前往「Logs Explorer」頁面

建立 API 開發人員入口網站

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

注意：刪除專案會造成以下結果：
• 專案中的所有內容都會遭到刪除。 如果您使用現有專案來進行本文中的工作，刪除專案時，也會一併刪除您在該專案中完成的所有其他工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

後續步驟

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