本頁說明如何利用 Java 適用的 Cloud Endpoints Frameworks 來設定、部署要求，以及將要求傳送至範例 API。Java 適用的 Endpoints Frameworks 已經與 App Engine 標準 Java 8 執行階段環境整合。Endpoints Frameworks 的工具、程式庫以及功能，可讓您從 App Engine 應用程式產生 API 和用戶端程式庫。
目標
在逐步進行本教學課程時，請使用以下概略工作清單。您必須完成所有工作才能成功傳送要求至 API。
- 設定 Google Cloud Platform (GCP) 專案。請參閱事前準備一節。
- 安裝所需的軟體，並建立一個 App Engine 應用程式。請參閱安裝並設定所需的軟體一節。
- 下載程式碼範例。請參閱取得程式碼範例一節。
- 產生一個 OpenAPI 設定檔。請參閱設定 Cloud Endpoints 一節。
- 部署 Endpoints 設定以建立 Endpoints 服務。請參閱部署 Endpoints 設定一節。
- 在您的電腦上執行範例。請參閱在本機執行範例一節。
- 建立後端以提供及部署 API。請參閱部署 API 後端一節。
- 傳送要求至 API。請參閱傳送要求至 API 一節。
- 追蹤 API 活動。請參閱追蹤 API 活動一節。
- 避免系統向您的 GCP 帳戶收取相關費用。請參閱清除所用資源一節。
費用
本教學課程使用下列 Google Cloud Platform 計費元件：
您可以使用 Pricing Calculator，根據您的預測使用量來產生預估費用。 初次使用 GCP 的使用者可能符合申請免費試用的資格。
完成此教學課程後，您可刪除已建立的資源以免繼續計費。詳情請參閱清除所用資源一節。
事前準備
安裝並設定所需的軟體
- 如果您還沒有安裝 Java 8，請從 Oracle 下載 Java Development Kit (JDK)，然後安裝該套件。Java 專用的 Endpoints Frameworks 需要 App Engine 標準 Java 8 執行階段環境，因此 Endpoints Frameworks 不支援任何其他版本的 Java。
- 如果您沒有 Maven 3.3.9 以上版本，請先下載並安裝。
-
您需要一個可以將要求傳送至範例 API 的應用程式。
- Linux 和 macOS 使用者：本教學課程提供了一個使用
curl的範例，該工具通常已預先安裝在您的作業系統中。如果您沒有curl，請前往curl的版本與下載頁面下載需要的檔案。 - Windows 使用者：本教學課程提供使用
Invoke-WebRequest的範例，而 PowerShell 3.0 以上版本均支援該工具。
- Linux 和 macOS 使用者：本教學課程提供了一個使用
- 下載並且初始化 Cloud SDK。
- 執行下列指令：
- 確認 Cloud SDK 已取得授權，可存取您在 GCP 上的資料與服務：
gcloud auth login
- 使用應用程式預設憑證：
gcloud auth application-default login
- 安裝 Cloud SDK
app-engine-java元件：gcloud components install app-engine-java
- 將 Cloud SDK 以及所有元件更新至最新版本：
gcloud components update
- 確認 Cloud SDK 已取得授權，可存取您在 GCP 上的資料與服務：
- 建立 App Engine 應用程式：
- 將預設專案設為您的專案 ID。
gcloud config set project YOUR_PROJECT_ID
請將
YOUR_PROJECT_ID替換成您的 GCP 專案 ID。如果您有其他 GCP 專案，而且想以gcloud管理這些專案，請參閱「管理 Cloud SDK 設定」一文。 - 選取您要在其中建立 App Engine 應用程式的地區。請執行以下指令來取得區域清單：
gcloud app regions list
- 使用下列指令建立 App Engine 應用程式。請將
YOUR_PROJECT_ID替換成您的 GCP 專案 ID，YOUR_REGION則替換為您建立 App Engine 應用程式的地區。gcloud app create \ --project=YOUR_PROJECT_ID \ --region=YOUR_REGION
- 將預設專案設為您的專案 ID。
Windows 使用者請注意：如果您要在 Windows 上安裝 JDK 和 Maven，請將它們安裝在路徑中不含空格的目錄中。詳情請參閱 Maven on Windows。
取得程式碼範例
從 Github 複製範例 API：
將範例存放區複製到本機電腦中。
git clone https://github.com/GoogleCloudPlatform/java-docs-samples變更為包含程式碼範例的目錄：
cd java-docs-samples/appengine-java8/endpoints-v2-backend
設定 Endpoints
程式碼範例包含能產生 OpenAPI 設定檔的 Endpoints Frameworks 工具，而該設定檔可描述程式碼範例的 REST API。請按照本節中的步驟設定及建構範例 Maven 專案，方便您稍後產生 OpenAPI 設定檔。
將專案 ID 新增到 API 程式碼範例
您必須先將在建立專案時取得的專案 ID 新增到範例的 pom.xml 中，才能部署程式碼。
如何新增專案 ID：
編輯
java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml檔案。搜尋
<endpoints.project.id>，然後將YOUR_PROJECT_ID替換成您的 GCP 專案 ID。例如：
<endpoints.project.id>example-project</endpoints.project.id>儲存變更。
建立範例專案
建立專案：
請確認您位於
java-docs-samples/appengine-java8/endpoints-v2-backend目錄。執行下列指令：
mvn clean package等待專案建構完成。當專案成功完成時，您會看到類似以下內容的訊息：
[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 設定檔：
用下列指令來呼叫 Endpoints Frameworks 工具：
mvn endpoints-framework:openApiDocs等待設定規範建構完成。當完成之後您會看見類似以下的訊息：
OpenAPI document written to target/openapi-docs/openapi.json請忽略任何有關無法載入靜態記錄器類別的訊息。
部署 Endpoints 設定
您可以使用服務基礎架構來部署 Endpoints 設定；服務基礎架構是 Google 的基礎服務平台，Endpoints Frameworks 和其他服務可使用此架構來建立及管理 API 和服務。
如何部署設定檔：
請確認您位於
java-docs-samples/appengine-java8/endpoints-v2-backend目錄。部署您在上一節產生的 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 服務部署。
檢查必要服務
如要提供 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 指令，請參閱 gcloud 服務。
在本機執行範例
部署 Endpoints 設定之後，您便可以在本機執行範例。
建立名為
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"
取得新的使用者憑證，以便用於應用程式預設憑證：
gcloud auth application-default login執行開發伺服器：
mvn appengine:run您可以在
http://localhost:8080存取本機執行個體，如同mvn appengine:run中所顯示的記錄檔一般：[INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/將要求傳送到本機執行個體：
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 後端：
請確認您位於
java-docs-samples/appengine-java8/endpoints-v2-backend目錄。使用 Maven 來部署 API 建置程式碼：
mvn appengine:deploy第一次上傳範例應用程式時，系統可能會提示您授權這項部署作業。請依照系統的提示操作。當您看到內含程式碼的瀏覽器視窗時，請將此程式碼複製到終端視窗。
等待上傳工作完成。
我們建議您等待幾分鐘，然後在 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 活動
在 GCP 主控台的「Endpoints」>「Service」(服務) 頁面上，檢視您 API 的活動圖表。
前往 Endpoints 的「Services」(服務) 頁面
要求可能需要一些時間才能反映在圖表中。
在「Logs Viewer」(記錄檢視器) 頁面中，查看您的 API 要求記錄。
建立 API 開發人員入口網站
您可以透過 Cloud Endpoints 入口網站建立開發人員入口網站，並將該網站用於與範例 API 進行互動。詳情請參閱 Cloud Endpoints 入口網站總覽。
清除所用資源
如要避免系統向您的 Google Cloud Platform 帳戶收取您在本教學課程中使用資源的相關費用：
- 前往 GCP 主控台的「Projects」(專案) 頁面。
- 在專案清單中選取要刪除的專案，然後按一下 [Delete] (刪除)。
- 在對話方塊中輸入專案 ID，按一下 [Shut down] (關閉) 即可刪除專案。
後續步驟
- 瞭解如何利用 JavaScript 用戶端進行驗證呼叫。
- 瞭解 Endpoints Frameworks 架構。
- 瞭解可用的 API 註解。
- 瞭解如何透過不同的路徑提供 API。
- 瞭解如何監控您的 API。
- 瞭解如何使用 API 金鑰限制存取權限。
- 瞭解如何處理 API 版本管理。
- 瞭解社群支援選項。
需要協助嗎？請前往我們的