GSP842

總覽

透過 Google Cloud 的 Apigee API 平台，您可以在現有 API 中加入新功能，讓應用程式煥然一新。

在本實驗室中，您會在 Cloud Run 上部署後端服務。這項後端服務會實作 REST API，在 Firestore 資料庫中儲存及擷取銀行資料 (客戶、帳戶、ATM 和交易)。您建立的 Apigee API Proxy 會代理後端服務。您也會建立共用流程，從外部服務擷取及快取內容。接著，您從 API Proxy 呼叫共用流程，並使用 JavaScript 程式碼修改 API 回應。

目標

在本實驗室中，您將瞭解如何執行下列工作：

• 在 Cloud Run 上部署後端服務
• 使用 Apigee X Proxy 代理後端服務
• 建立共用流程，供多個 Proxy 使用
• 將設定資料儲存在屬性集中
• 使用服務呼叫政策從服務擷取內容
• 使用快取政策來快取可重複使用的資訊
• 使用 JavaScript 程式碼修改回應酬載

設定

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

啟動 Cloud Shell

Cloud Shell 是搭載多項開發工具的虛擬機器，提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權，方便您使用 Google Cloud 資源。

1. 點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示 。

2. 系統顯示視窗時，請按照下列步驟操作：

   • 繼續操作 Cloud Shell 視窗。
   • 授權 Cloud Shell 使用您的憑證發出 Google Cloud API 呼叫。

連線建立完成即代表已通過驗證，而且專案已設為您的 Project_ID：。輸出內容中有一行文字，宣告本工作階段的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的指令列工具，已預先安裝於 Cloud Shell，並支援 Tab 鍵自動完成功能。

3. (選用) 您可以執行下列指令來列出使用中的帳戶：

gcloud auth list

4. 點按「授權」。

輸出內容：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (選用) 您可以使用下列指令來列出專案 ID：

gcloud config list project

輸出內容：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需 gcloud 的完整說明，請前往 Google Cloud 參閱 gcloud CLI 總覽指南。

工作 1：在 Cloud Run 上部署後端服務

在這項工作中，您會在 Cloud Run 上部署後端服務。

這項服務會為 SimpleBank 導入一個 API。這個 API 提供簡單的銀行資料展示系統，包括客戶、帳戶、交易和自動提款機。SimpleBank 服務是使用 Node.js 建構而成，資料則儲存在 Firestore 中。程式碼會封裝在 Docker 容器中，並部署至 Cloud Run。

複製程式碼存放區

1. 如要複製包含 SimpleBank 服務程式碼的存放區，請在 Cloud Shell 中執行下列指令：

   git clone --depth 1 https://github.com/GoogleCloudPlatform/training-data-analyst

2. 建立工作目錄的軟連結：

   ln -s ~/training-data-analyst/quests/develop-apis-apigee ~/develop-apis-apigee

3. 如要切換至包含 REST 後端的目錄，請執行下列指令：

   cd ~/develop-apis-apigee/rest-backend

4. 如要在設定檔中更新區域，請執行下列指令：

   sed -i "s/us-west1/{{{ project_0.default_region | "REGION" }}}/g" config.sh

初始化專案

專案初始化指令碼 init-project.sh 會在專案中啟用 API。部署 Cloud Run 服務時，必須啟用這些 API。

服務的資料庫將是原生模式的 Firestore。專案只能以原生模式或 Datastore 模式代管單一 Firestore 資料庫。這個指令碼會建立原生模式的 Firestore 資料庫。

1. 如要查看 init-project.sh 執行的指令，請輸入下列指令：

   cat init-project.sh

   指令碼會啟用 API，並建立原生模式的 Firestore 資料庫。

2. 如要執行指令碼，請輸入下列指令：

   ./init-project.sh

按一下「Check my progress」，確認目標已達成。 啟用 Cloud Run API 並建立 Firestore 資料庫

初始化服務

服務初始化指令碼 init-service.sh 會建立服務帳戶 simplebank-rest。這個服務帳戶代表 Cloud Run 服務。服務帳戶會獲得 roles/datastore.user 角色，可讀取及更新 Firestore 中的資料。

最佳做法是為您的服務建立服務帳戶，並使用最小權限原則授予帳戶權限。根據這項原則，帳戶應只具備執行其獨特功能所需的必要權限。

1. 如要查看 init-service.sh 執行的指令，請輸入下列指令：

   cat init-service.sh

   指令碼會建立服務使用的服務帳戶，並將角色新增至服務帳戶。

2. 如要執行指令碼，請輸入下列指令：

   ./init-service.sh

部署後端服務

部署指令碼 deploy.sh 會使用目前目錄中的程式碼建構 simplebank 服務應用程式，並使用 simplebank-rest 服務帳戶將服務部署至 Cloud Run。每次更新應用程式程式碼時，部署指令碼都會執行。

服務的部署設定為僅允許經過驗證的存取，因此必須提供有效的 OpenID Connect 身分識別權杖，才能呼叫服務。

1. 在 Cloud Shell 中，如要查看 deploy.sh 指令碼執行的內容，請輸入下列指令：

   cat deploy.sh

   這個指令碼會建構 simplebank-grpc 服務，並部署至 Cloud Run。

注意：部署指令碼會使用 max-instances 參數，將 Cloud Run 叢集中的執行個體數量限制設為 1。如果是實際正式環境服務，不建議指定這麼低的限制。

2. 如要將指令碼部署至 Cloud Run，請輸入下列指令：

   ./deploy.sh

按一下「Check my progress」，確認目標已達成。 部署後端服務

測試服務

1. 如要確認服務正在執行，請發出 curl 要求來呼叫服務：

   export RESTHOST=$(gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)') echo "export RESTHOST=${RESTHOST}" >> ~/.bashrc curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/_status"

   設定 RESTHOST 變數的指令，會使用 gcloud 擷取 simplebank-rest Cloud Run 服務的主機名稱。接著，變數會新增至 .bashrc 檔案，如果 Cloud Shell 重新啟動，系統就會重新載入 RESTHOST 變數。

   GET /_status 指令只會傳回 JSON 回應，指出 API 正常運作。您在這項呼叫中使用了 gcloud auth print-identity-token，為登入 Cloud Shell 的使用者取得 OpenID Connect 身分識別權杖。您以專案擁有者角色身分登入，專案擁有者具備非常廣泛的權限。

2. 如要確認服務可以寫入 Firestore，請發出會建立客戶的 curl 要求：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -H "Content-Type: application/json" -X POST "${RESTHOST}/customers" -d '{"lastName": "Diallo", "firstName": "Temeka", "email": "temeka@example.com"}'

   POST /customers 指令會建立客戶。lastName、firstName 和 email 參數皆為必填項目。電子郵件地址不得重複，且會做為客戶的 ID。客戶記錄會儲存在 Firestore 中。

   注意：如果收到「AlreadyExist」錯誤，可能表示您尚未成功建立 Firestore 資料庫。執行 init-project.sh 指令碼即可建立資料庫。

3. 如要確認服務可以從 Firestore 讀取資料，請發出 curl 要求，擷取您剛建立的客戶：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/customers/temeka@example.com"

   GET /customers/ 指令會從 Firestore 擷取客戶記錄。

4. 如要將一些額外範例資料載入 Firestore，請輸入下列指令：

   gcloud firestore import gs://spls/shared/firestore-simplebank-data/firestore/example-data

   這項 gcloud 指令會使用 Firestore 匯入/匯出功能，將客戶、帳戶和 ATM 匯入資料庫。

5. 如要擷取 ATM 清單，請執行下列 curl 指令：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms"

6. 如要擷取單一 ATM，請執行下列 curl 指令：

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms/spruce-goose"

   這項要求會依名稱擷取 ATM，而回應會包含 ATM 的經緯度，但不包含地址：

   {"name":"spruce-goose","longitude":-118.408207,"description":"","latitude":33.977601}

   在後續工作中，您將使用 Apigee 和 Geocoding API，在擷取特定 ATM 時將地址新增至傳回的回應。

工作 2：使用 Apigee API Proxy 將要求轉傳到後端服務

在這項工作中，您會建立 Apigee API Proxy，做為後端服務的門面元件。API Proxy 會透過服務帳戶，提供 OpenID Connect 身分識別權杖給 Cloud Run 服務。

為 Apigee API Proxy 建立服務帳戶

1. 如要建立 Apigee API 代理可使用的服務帳戶，請輸入下列指令：

   gcloud iam service-accounts create apigee-internal-access \ --display-name="Service account for internal access by Apigee proxies" \ --project=${GOOGLE_CLOUD_PROJECT}

   gcloud 指令會建立服務帳戶 apigee-internal-access，Apigee Proxy 呼叫後端服務時將使用這個帳戶。

2. 如要授予可存取服務的角色，請輸入下列指令：

   gcloud run services add-iam-policy-binding simplebank-rest \ --member="serviceAccount:apigee-internal-access@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --role=roles/run.invoker --region={{{project_0.default_region |REGION}}} \ --project=${GOOGLE_CLOUD_PROJECT}

   這項 gcloud 指令會將服務帳戶 roles/run.invoker 角色授予 simplebank-rest Cloud Run 服務，允許服務帳戶叫用服務。

3. 如要擷取後端服務的網址，請使用下列指令：

   gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)'

   請儲存這個網址，建立 API Proxy 時會用到。

按一下「Check my progress」，確認目標已達成。系統可能需要一段時間才會偵測到授予的角色。 為 Apigee API Proxy 建立服務帳戶

開啟 Apigee 控制台

如要開啟 Apigee 控制台，請按照下列指示操作：

• 在 Google Cloud 控制台的「搜尋」欄位輸入 Apigee，然後點選搜尋結果中的「Apigee API 管理平台」。

Apigee 控制台隨即開啟，到達網頁會顯示常用位置的快速連結。

• 依序點選導覽選單圖示 ()，以及「Apigee」旁的圖釘圖示 ()。

這樣 Apigee 就會固定至導覽選單。

建立 Apigee Proxy

1. 在導覽選單中，依序選取「Proxy 開發」>「API Proxy」。

2. 如要使用 Proxy 精靈建立新的 Proxy，請按一下「+Create」。

   您將為後端服務建立反向 Proxy。

3. 針對「Proxy template」，選取「General template」>「Reverse proxyy (Most common)」。

   注意：請勿在「OpenAPI spec template」部分選取「Reverse proxy (Most common」。

4. 指定「Proxy details」的下列項目：

   屬性	值
   Proxy 名稱	bank-v1
   基本路徑	/bank/v1
   目標 (現有 API)	後端網址

   注意：請確認基本路徑為「/bank/v1」，而非「/bank-v1」。

   目標應為先前在這項工作中擷取的後端網址，看起來應如下所示：

   https://simplebank-rest-mtdtzt7yzq-ue.a.run.app

5. 點選「下一步」。

6. 保留「部署 (選用)」設定的預設值，然後點選「建立」。

確認執行階段執行個體是否可用

1. 在 Cloud Shell 貼上並執行下列這組指令：

   export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***";

   這一連串指令會使用 Apigee API，判斷 Apigee 執行階段執行個體是否建立完畢、eval 環境是否已附加。

2. 等待執行個體準備就緒。

   畫面上顯示「***ORG IS READY TO USE***」字樣時，表示執行個體準備就緒。Apigee 組織 (簡稱「組織」) 或許在實驗室啟動前就已建立，因此可能不必等待這個執行個體建立完畢。

   等待組織準備就緒期間，歡迎進一步瞭解 Apigee、探索 Apigee X 架構，或學習 API 和 API Proxy 相關內容。

部署 API Proxy

1. 在導覽選單中，依序選取「Proxy 開發」>「API Proxy」，然後點選「bank-v1」。

2. 按一下「部署」。

3. 在「環境」部分，選取「評估」。

4. 在「服務帳戶」部分，指定服務帳戶的電子郵件地址：

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. 依序按一下「部署」>「確認」。

6. 等待「評估」部署作業狀態顯示 Proxy 部署完畢。

測試 API Proxy

您可使用主機名稱 eval.example.com 呼叫 Apigee 組織的 eval 環境。這個主機名稱的 DNS 項目已在專案中建立，會解析為 Apigee 執行階段執行個體的 IP 位址。這個 DNS 項目是在私人可用區建立，只會顯示於內部網路。

Cloud Shell 不位於內部網路，因此無法使用 Cloud Shell 指令解析這個 DNS 項目。專案中的虛擬機器 (VM) 可存取私人可用區 DNS。系統已自動建立虛擬機器 apigeex-test-vm，可用來呼叫 API Proxy。

1. 在 Cloud Shell 開啟連至測試 VM 的 SSH 連線：

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   第一個 gcloud 指令會擷取測試 VM 的可用區，第二個指令則會開啟與 VM 的 SSH 連線。

2. 如果系統要求您授權，請點按「授權」。

   對於 Cloud Shell 中顯示的每個問題，按下 Enter 或 Return 鍵使用預設輸入內容。

   您是以專案擁有者的身分登入，因此能透過 SSH 連至這個機器。

   Cloud Shell 工作階段現在會在 VM 內執行。

3. 在「評估」環境呼叫部署的 bank-v1 API Proxy：

   curl -i -k "https://eval.example.com/bank/v1/_status"

   -k 選項會告知 curl 略過 TLS 憑證驗證。本實驗室的 Apigee 執行階段使用的憑證為自行簽署，而非由信任的憑證授權單位 (CA) 建立。

   注意：請勿使用 -k 選項，在正式環境中略過憑證驗證。

   系統會傳回 403 Forbidden 狀態碼，並顯示錯誤訊息，指出您的用戶端無權取得網址。由於用戶端未在要求中提供必要權杖，因此後端服務拒絕了要求。API Proxy 是以正確的身分執行，但您仍需強制將 OpenId Connect 身分權杖隨要求一起傳送。

4. 返回 bank-v1 Proxy，然後按一下「開發」分頁。

5. 在 Proxy 的左選單中，在「目標端點」>「預設」部分按一下「PreFlow」。

6. 找出下列程式碼 (不同於您的網址)：

   <HTTPTargetConnection> <Properties/> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection> 注意：如果沒有看到 HTTPTargetConnection 部分，請確認點選的是「目標端點」部分中的 PreFlow，而非「Proxy 端點」部分。

7. 在 HTTPTargetConnection 部分中，於網址下方新增「驗證」部分，如下所示：

   <Authentication> <GoogleIDToken> <Audience>AUDIENCE</Audience> </GoogleIDToken> </Authentication>

8. 將 AUDIENCE 替換為 HTTPTargetConnection 部分中已有的網址值。程式碼現在看起來應會如下方所示，只是 URL 和 Audience 元素要替換成實際網址：

   <TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <Properties/> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> <Authentication> <GoogleIDToken> <Audience>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>

9. 依序點選「儲存」和「另存為新的修訂版本」。

10. 按一下「部署」。

11. 在「環境」部分，選擇「評估」。

12. 在「服務帳戶」部分，指定服務帳戶的電子郵件地址：

    apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

13. 依序按一下「部署」>「確認」。

14. 按一下「總覽」分頁，並等待「評估」部署狀態顯示已部署新修訂版本。

按一下「Check my progress」，確認目標已達成。 建立 Apigee Proxy

14. 如果 SSH 登入逾時，請在 Cloud Shell 中執行下列指令，重新建立連線：

    TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

15. 在 VM 內重新執行狀態指令：

    curl -i -k "https://eval.example.com/bank/v1/_status"

    您應會看到類似下方內容的成功 (200) 回應：

    HTTP/2 200 x-powered-by: Express content-type: application/json; charset=utf-8 etag: W/"41-x4uozCo6q/yN+kzizriXxryNZvc" x-cloud-trace-context: 5c810a7faa3353bcc085473fd58805b7 date: Thu, 11 Nov 2021 22:54:35 GMT server: Google Frontend content-length: 65 x-request-id: cf109193-6d6f-49a1-b323-7f66f63c5e28 via: 1.1 google {"serviceName":"simplebank-rest","status":"API up","ver":"1.0.0"}

    這項回應表示 API Proxy 成功呼叫後端服務。

16. 輸入 exit 指令，離開 SSH 工作階段並返回 Cloud Shell。

工作 3：啟用 Google Cloud Geocoding API

在這項工作中，您將啟用 Geocoding API。從 SimpleBank 服務擷取 ATM 時，可以在 API Proxy 中使用這項 API 將地址資訊新增至回應。

1. 執行下列指令，在 Cloud Shell 啟用 Geocoding API：

   gcloud services enable geocoding-backend.googleapis.com

   接著，您將建立可存取 Geocoding API 的 API 金鑰。

2. 如要建立 API 金鑰，請執行下列指令：

   API_KEY=$(gcloud alpha services api-keys create --project=${GOOGLE_CLOUD_PROJECT} --display-name="Geocoding API key for Apigee" --api-target=service=geocoding_backend --format "value(response.keyString)") echo "export API_KEY=${API_KEY}" >> ~/.bashrc echo "API_KEY=${API_KEY}" 注意：如果收到錯誤訊息，指出專案屬性設為空字串，請務必結束 VM SSH 工作階段，並返回 Cloud Shell。

   gcloud 指令會建立 API 金鑰，以便傳送要求至 Geocoding API。提供 --format 參數，即可選取回應中的 keyString 欄位，並儲存在 API_KEY 殼層變數中。接著，API_KEY 變數會儲存在 Cloud Shell 的 .bashrc 檔案中。

按一下「Check my progress」，確認目標已達成。 啟用 Google Cloud Geocoding API

3. 如要擷取特定經緯度的地理編碼資訊，請執行下列 curl 指令：

   curl "https://maps.googleapis.com/maps/api/geocode/json?key=${API_KEY}&latlng=37.404934,-122.021411"

   這項指令會呼叫 Geocoding API，並提供 API 金鑰和所需的經緯度。回應會包含結果陣列，每項結果都有格式化地址。在 API Proxy 中，您將使用第一項結果的格式化地址，在擷取單一 ATM 的詳細資料時，將地址新增至 API 回應。

工作 4：建立共用流程來呼叫 Geocoding API

在這項工作中，您會建立共用流程，用於呼叫 Google Geocoding API。透過共用流程，您可以將政策和資源組合成單一流程，供多個 API Proxy 或其他共用流程使用。

共用流程會使用以下模式：

資料庫中的 ATM 數量有限，且 ATM 的經緯度不會變。為避免過度呼叫 Geocoding API，系統會使用經緯度做為快取金鑰，以快取擷取的地址。如果指定經緯度的地址不在快取中，系統會呼叫 Geocoding API，並將傳回的地址儲存在快取中。

建立共用流程

1. 在導覽選單中，依序選取「Apigee」>「Proxy 開發」>「共用流程」。
2. 點選「+建立」。
3. 將「名稱」設為 get-address-for-location，然後按一下「建立」。
4. 按一下「開發」分頁。

新增 LookupCache 政策

如果先前已快取地址，LookupCache 政策就會擷取地址。

1. 在共用流程的左選單中，按一下「共用流程」部分中的「預設」。

2. 在 sharedflows/default.xml 窗格中，按一下「新增政策步驟」圖示 ()。

3. 選取「建立新政策」。

4. 在「選取政策」 中，依序選取「流量管理」>「查詢快取」。

5. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	LC-LookupAddress
   顯示名稱	LC-LookupAddress

6. 依序按一下「新增」和「LC-LookupAddress」。

   政策會新增至流程，且政策的設定 XML 會顯示在流程下方的窗格中。

7. 確認窗格中是否有 LookupCache 設定，然後將該設定替換為以下內容：

   <LookupCache continueOnError="false" enabled="true" name="LC-LookupAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <AssignTo>geocoding.address</AssignTo> </LookupCache>

   這項政策會在 AddressesCache 中尋找符合指定經緯度的項目，並將找到的值指派給變數地址。

新增服務呼叫政策

服務呼叫政策會呼叫 Google Geocoding API。

1. 在共用流程的左選單中，按一下「共用流程」部分中的「預設」。

2. 在 sharedflows/default.xml 窗格中，按一下「新增政策步驟」圖示 ()。

3. 選取「建立新政策」。

4. 在「選取政策」中，依序選取「擴充功能」>「服務呼叫」。

5. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	SC-GoogleGeocode
   顯示名稱	SC-GoogleGeocode

6. 「HTTP 目標」欄位維持不變，依序按一下「新增」和「SC-GoogleGeocode」。

7. 確認窗格中是否有 ServiceCallout 設定，然後將該設定替換為以下內容：

   <ServiceCallout continueOnError="false" enabled="true" name="SC-GoogleGeocode"> <Request> <Set> <QueryParams> <QueryParam name="latlng">{geocoding.latitude},{geocoding.longitude}</QueryParam> <QueryParam name="key">{geocoding.apikey}</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> </Request> <Response>calloutResponse</Response> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>

   這項政策會使用 geocoding.latitude、geocoding.longitude 和 geocoding.apikey 變數，來呼叫 Geocoding API。API 呼叫回應會儲存在 calloutResponse 變數中。

新增 ExtractVariables 政策

ExtractVariables 政策會從 Google Geocoding API 回應中擷取格式化地址。

1. 在共用流程的左選單中，按一下「共用流程」部分中的「預設」。

2. 在 sharedflows/default.xml 窗格中，按一下「新增政策步驟」圖示 ()。

3. 選取「建立新政策」。

4. 在「選取政策」中，依序選取「調節」>「擷取變數」。

5. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	EV-ExtractAddress
   顯示名稱	EV-ExtractAddress

6. 依序按一下「新增」和「EV-ExtractAddress」。

7. 確認窗格中是否有 ExtractVariables 設定，然後將該設定替換以下內容：

   <ExtractVariables continueOnError="false" enabled="true" name="EV-ExtractAddress"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <JSONPayload> <Variable name="address"> <JSONPath>$.results[0].formatted_address</JSONPath> </Variable> </JSONPayload> <Source clearPayload="false">calloutResponse.content</Source> <VariablePrefix>geocoding</VariablePrefix> </ExtractVariables>

   這項政策會使用 JSONPath，從 calloutResponse 訊息 JSON 酬載的第一個結果中，擷取 formatted_address。地址會儲存在 geocoding.address 變數中。

新增 PopulateCache 政策

PopulateCache 政策會將地址儲存在快取中。

1. 在共用流程的左選單中，按一下「共用流程」部分中的「預設」。

2. 在 sharedflows/default.xml 窗格中，按一下「新增政策步驟」圖示 ()。

3. 選取「建立新政策」。

4. 在「選取政策」中，依序選取「流量管理」>「PopulateCache」。

5. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	PC-StoreAddress
   顯示名稱	PC-StoreAddress

6. 依序按一下「新增」和「PC-StoreAddress」。

7. 確認窗格中是否有 PopulateCache 設定，然後將該設定替換為以下內容：

   <PopulateCache continueOnError="false" enabled="true" name="PC-StoreAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <Source>geocoding.address</Source> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <ExpirySettings> <TimeoutInSec>3600</TimeoutInSec> </ExpirySettings> </PopulateCache>

   這項政策會使用與 LookupCache 政策相同的經緯度金鑰片段，以相同順序將 address 變數中的值儲存至 AddressesCache。ExpirySettings/TimeoutInSec 設定指定儲存的資料將快取 3600 秒，也就是 1 小時。

在特定條件下略過政策

如果系統在特定經緯度的快取中找到地址 (快取命中)，則不需要 ServiceCallout、ExtractVariables 和 PopulateCache 政策，應予以略過。

1. 在共用流程的左選單中，按一下「共用流程」部分中的「預設」。

   「程式碼」窗格包含「預設流程」，其中列出已附加的四項政策：

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Name>EV-ExtractAddress</Name> </Step> <Step> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

   每個 Step 都會指定已附加的政策，Name 則用於指定附加政策的名稱。您還可以新增 Condition 元素，指定用於決定政策是否應執行的布林值條件。

   回顧工作一開始的共用流程模式。如果地址查詢成功，就不需要呼叫服務或將資料存回快取。在這種情況下，請略過政策步驟 2 到 4。

   LookupCache 政策會設定變數，指出項目是否在快取中找到。如果變數 lookupcache.{policyName}.cachehit 為 false，表示系統找不到項目。僅在沒有快取命中時，才應執行第 2 步到第 4 步的政策。

2. 從第 2 步到第 4 步，在 Step 元素內加入下列條件：

   <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition>

   全部新增完畢後，共用流程應如下所示：

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>EV-ExtractAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

3. 按一下「儲存」。

4. 按一下「部署」。

5. 在「環境」部分，選擇「評估」。

6. 將「服務帳戶」留白，然後依序按一下「部署」和「確認」。

   共用流程會使用 API 金鑰呼叫 Geocoding API，因此不需要服務帳戶。

   如要測試共用流程，只能從 API Proxy 呼叫。

按一下「Check my progress」，確認目標已達成。 建立共用流程來呼叫 Geocoding API

工作 5：擷取單一 ATM 時，新增 ATM 地址

在這項工作中，您會將 FlowCallout 政策新增至 API Proxy，以呼叫剛建立的共用流程。擷取特定 ATM 時，API Proxy 必須從 Cloud Run 服務回應中擷取經緯度，並呼叫共用流程來擷取對應地址。接著，JavaScript 政策會將地址新增至 API 回應。

為 API 金鑰新增屬性集

屬性集可用於儲存不會過期的資料，這份資料能輕鬆自 API Proxy 存取。屬性集值會保留 API 金鑰。

1. 在左側導覽選單中，依序選取「Proxy 開發」>「API Proxy」。

2. 按一下「bank-v1」，然後選取「Develop」分頁。

3. 在 Proxy 的左選單中，按一下「資源」部分中的「新增資源」 ()。

4. 在「資源類型」下拉式選單中，選取「屬性集」。

5. 在「資源名稱」中指定 geocoding.properties，然後按一下「新增」。

6. 在 geocoding.properties 窗格中，新增下列屬性：

   apikey=<APIKEY>

7. 將 <APIKEY> 替換為您在工作 3 中建立的 API_KEY。

8. 您可以在 Cloud Shell 中使用下列指令擷取 API_KEY：

   echo ${API_KEY}

   您的 geocoding.properties 檔案應大致如下所示：

   apikey=AIzaSyC8-B6nt7M240wwZtsxR2O5sb0xznuhQWc

建立條件式流程

1. 在 Proxy 的左選單中，按一下「Proxy 端點」部分中的「預設」。

2. 在 proxy-endpoints/default.xml 窗格中，按一下「Proxy 端點：預設」旁的「新增條件式流程」 ()。

3. 在「新增條件式流程」對話方塊中，指定下列值：

   屬性	值
   流程名稱	GetATM
   說明	擷取單一 ATM
   條件類型	選取「路徑和動詞」
   路徑	/atms/{name}
   動詞	選取 GET

   將「目標網址」留空。

4. 按一下「新增」。

   API Proxy 由許多流程組成，每個流程都有提供以步驟形式附加政策的位置。以下是 API Proxy 的圖表：

   

   只有在條件為 true 時，系統才會執行條件式流程設定。在這個條件式流程中，proxy.pathsuffix 變數必須符合 /atms/{name} 格式，且 request.verb 變數必須為 GET。

   請將一些政策附加至 GetATM 條件式流程，即可只針對 GET /atms/{name} 要求執行政策。政策必須在呼叫後端服務後執行，因此必須附加至「Proxy 端點回應」條件式流程。

擷取經緯度

1. 在「Proxy 端點：預設」流程的「回應」部分，按一下「GetATM」右側的「新增流程步驟」 ()。

   注意：請務必將步驟新增至「回應」端，而非「要求」端。

2. 選取「建立新政策」。

3. 在「選取政策」中，依序選取「調節」>「擷取變數」。

4. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	EV-ExtractLatLng
   顯示名稱	EV-ExtractLatLng

5. 依序按一下「新增」和「EV-ExtractLatLng」。

6. 確認窗格中是否有 ExtractVariables 設定，然後將該設定替換以下內容：

   <ExtractVariables name="EV-ExtractLatLng"> <Source>response</Source> <JSONPayload> <Variable name="latitude"> <JSONPath>$.latitude</JSONPath> </Variable> <Variable name="longitude"> <JSONPath>$.longitude</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

   這項政策會從後端服務的 GET /atms/{name} JSON 回應中，擷取「經度」和「經度」。IgnoreUnresolvedVariables 元素設為 true，表示即使在回應中找不到緯度和經度，系統仍會繼續處理。

呼叫共用流程

1. 在「Proxy 端點：預設」流程的「回應」部分，按一下「GetATM」右側的「新增流程步驟」 ()。

2. 選取「建立新政策」。

3. 在「選取政策」部分，依序選取「擴充功能」>「流程呼叫」。

4. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	FC-GetAddress
   顯示名稱	FC-GetAddress
   共用流程	選取 get-address-for-location
   條件	latitude != null AND longitude != null

   如果系統未擷取 ATM 的經緯度，就無法判斷地址，因此會略過政策步驟。

5. 依序按一下「新增」和「FC-GetAddress」。

6. 確認窗格中是否有 FlowCallout 設定，然後將該設定替換為以下內容：

   <FlowCallout continueOnError="false" enabled="true" name="FC-GetAddress"> <Parameters> <Parameter name="geocoding.latitude">{latitude}</Parameter> <Parameter name="geocoding.longitude">{longitude}</Parameter> <Parameter name="geocoding.apikey">{propertyset.geocoding.apikey}</Parameter> </Parameters> <SharedFlowBundle>get-address-for-location</SharedFlowBundle> </FlowCallout>

   這項政策會將經緯度和 apikey 變數設為共用流程參數，並呼叫共用流程。共用流程會設定 geocoding.address 變數。

新增地址

1. 在「Proxy 端點：預設」流程的「回應」部分，按一下「GetATM」右側的「新增流程步驟」 ()。

2. 選取「建立新政策」。

3. 在「選取政策」部分，選取「擴充功能」>「JavaScript」。

4. 在「詳細資料」部分中，設定以下項目：

   屬性	值
   名稱	JS-AddAddress
   顯示名稱	JS-AddAddress
   JavaScript 檔案	選取「建立新資源」

5. 在「新增資源」部分，指定下列項目：

   屬性	值
   來源	選取「建立新檔案」
   資源名稱	addAddress.js

6. 依序按一下「新增」和「addAddress.js」。

7. 將「條件」指定為 latitude != null AND longitude != null。

8. 依序按一下「新增」和「JS-AddAddress」。

9. 在 Proxy 的左選單中，按一下「資源 > jsc」部分中的「addAddress.js」。

   addAddress.js 程式碼的窗格為空白。

10. 新增下列 JavaScript 程式碼，將地址加入回應：

    // get the flow variable 'geocoding.address' var address = context.getVariable('geocoding.address'); // parse the response payload into the responsePayload object var responsePayload = JSON.parse(context.getVariable('response.content')); try { // add address to the response responsePayload.address = address; // convert the response object back into JSON context.setVariable('response.content', JSON.stringify(responsePayload)); } catch(e) { // catch any exception print('Error occurred when trying to add the address to the response.'); }

    這段程式碼會將 JSON 回應酬載剖析為物件、在物件中新增地址欄位、將物件轉換回 JSON 字串，然後儲存在回應中。

    使用 try/catch 模塊，避免例外狀況從 JavaScript 政策中擲回。如果未捕捉到例外狀況，系統會引發錯誤，導致 API Proxy 處理作業取消。

驗證政策是否會在特定條件下略過

1. 在 Proxy 的左選單中，按一下「Proxy 端點 > 預設」部分中的「GetATM」。

   「程式碼」窗格包含 Get ATM 流程，其中列出已附加的三項政策，以及第二和第三項政策的條件：

   <Flow name="GetATM"> <Description>retrieve a single ATM</Description> <Request/> <Response> <Step> <Name>EV-ExtractLatLng</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>FC-GetAddress</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>JS-AddAddress</Name> </Step> </Response> <Condition>(proxy.pathsuffix MatchesPath "/atms/{name}") and (request.verb = "GET")</Condition> </Flow>

2. 依序點選「儲存」和「另存為新的修訂版本」。

3. 按一下「部署」。

4. 在「環境」部分，選擇「評估」。

5. 在「服務帳戶」部分，指定服務帳戶的電子郵件地址：

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

6. 依序按一下「部署」>「確認」。

7. 按一下「總覽」分頁，並等待「評估」部署狀態顯示已部署新修訂版本。

按一下「Check my progress」，確認目標已達成。 擷取單一 ATM 時，新增 ATM 地址

測試更新後的 API Proxy

1. 在 Cloud Shell 開啟連至測試 VM 的 SSH 連線：

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. 使用下列指令呼叫 bank-v1 Proxy，並擷取所有 ATM：

   curl -i -k "https://eval.example.com/bank/v1/atms"

   由於要求未使用 GET /atms/{name} 流程，因此回應不含地址。

3. 擷取單一 ATM：

   curl -i -k "https://eval.example.com/bank/v1/atms/spruce-goose"

   回應現在包含 API Proxy 中新增的地址：

   {"longitude":-118.408207,"latitude":33.977601,"description":"","name":"spruce-goose","address":"5865 S Campus Center Dr, Los Angeles, CA 90094, USA"}

恭喜！

在本實驗室中，您已成功在 Cloud Run 上部署後端服務，並建立 Apigee API Proxy 將要求轉傳到後端服務。您建立的共用流程會從外部服務擷取內容並快取。接著，您從 API Proxy 呼叫共用流程，並使用 JavaScript 程式碼修改 API 回應。

後續步驟/瞭解詳情

• 什麼是 Apigee？
• Apigee X 架構
• API 和 API Proxy

使用手冊上次更新日期：2024 年 7 月 16 日

實驗室上次測試日期：2024 年 7 月 16 日

Copyright 2025 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。