GSP363

總覽

在挑戰研究室中，您會在特定情境下完成一系列任務。挑戰研究室不會提供逐步說明，您將運用從課程研究室學到的技巧，自行找出方法完成任務！自動評分系統 (如本頁所示) 將根據您是否正確完成任務來提供意見回饋。

在您完成任務的期間，挑戰研究室不會介紹新的 Google Cloud 概念。您須靈活運用所學技巧，例如變更預設值或詳讀並研究錯誤訊息，解決遇到的問題。

若想滿分達標，就必須在時限內成功完成所有任務！

本實驗室適合已完成「透過 Apigee X 開發及保護 API」課程實驗室的學員。準備好迎接挑戰了嗎？

設定

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

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

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

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

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

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

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

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

挑戰情境

您是國際零售商 Cymbal Shops 的雲端工程師。Cymbal Shop 將經營重心放在全球銷售，認為翻譯服務是拓展國際業務的關鍵工具。您的職責是建立翻譯 API 的初始版本。

公司期望您已具備相關技能與知識，因此不會提供逐步指南。

您的挑戰

您將在專案的 Apigee 組織中，建立新的 Apigee API Proxy 和其他資源。請詳閱每個工作說明，然後建立必要功能。

儲存錯誤

儲存 API Proxy 的變更時，可能會顯示錯誤訊息：Could not save new revision。如果點按「儲存」下拉式選單按鈕 ()，然後選取「另存為新的修訂版本」，應會看到錯誤訊息指出哪裡無效。

工作 1：為 Cloud Translation API 建立 Proxy

Cymbal Shops 決定使用 Google Cloud 的 Translation API 做為 API Proxy 的後端服務。

必要操作：

1. 前往 Google Cloud 控制台，確認已在 API 程式庫啟用「Cloud Translation API」。
2. 為 API Proxy「apigee-proxy」建立服務帳戶，然後在「Logging」授予「記錄寫入者」角色。
3. 在 Google Cloud 控制台導覽選單中選取「Apigee」，開啟 Apigee 使用者介面並建立 API Proxy。
4. API Proxy 應為反向 Proxy，名稱為 translate-v1 且基本路徑為 /translate/v1。
5. API Proxy 的目標，是 Cloud Translation API 基本版的 HTTP 網址 (https://translation.googleapis.com/language/translate/v2)。
6. 請勿透過 Proxy 精靈的「Common Policies」頁面新增授權、CORS 或配額。
7. 在摘要頁面建立 API Proxy，並保留預設設定。
8. 將 Authentication 區段加入預設 TargetEndpoint。這樣一來，每當系統傳送後端要求，就會一併傳送存取權杖。使用 GoogleAccessToken 元素，並將 Scope 設為 https://www.googleapis.com/auth/cloud-translation。

注意： 請編輯 Proxy，並在「開發」分頁的「目標端點」專區下方，編輯預設 default.xml 檔案。

9. 使用下列 Cloud Shell 指令碼，確認已完整安裝 Apigee 執行階段：

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***";

如果指令碼傳回 ORG IS READY TO USE，即可繼續執行後續步驟。

注意： 如果您正在等待安裝執行階段，可以預先閱讀後續內容，規劃工作 2 的開發作業。

10. 使用下列服務帳戶儲存 translate-v1 Proxy，並部署至 eval 環境：

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

11. 測試 API Proxy。

您可以使用主機名稱「eval.example.com」呼叫 Apigee 組織中的 eval 環境。這個 DNS 項目僅適用於內部網路，因此必須使用已為您建立的 VM。

12. 在 Cloud Shell 啟用連往 apigeex-test-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

13. 如果系統要求您授權，請點按「授權」。對於透過 gcloud 指令提出的每個問題，按下 Enter 或 Return 鍵來使用預設輸入內容。

14. 順利完成工作 1 後，應能使用下列 curl 指令翻譯文字：

curl -i -k -X POST "https://eval.example.com/translate/v1" -H "Content-Type: application/json" -d '{ "q": "Translate this text!", "target": "es" }'

回應內容大致如下：

{ "data": { "translations": [ { "translatedText": "¡Traduce este texto!", "detectedSourceLanguage": "en" } ] } } 注意： 系統需要幾分鐘才會完整部署 API Proxy，在此之前您可能會收到 502 錯誤回應。

點選「Check my progress」，確認目標已達成。 為 Cloud Translation API 建立 Proxy

注意： 如果沒看到綠色勾號，請點按右上角的「Score」飛出式視窗，然後點選相關步驟的「Check my progress」。系統會開啟彈出式視窗並提供建議。

工作 2：變更 API 要求和回應

Cymbal Shops 想建立的 API 與 Translation API 提供的介面不同，因此請您修改兩項 Translation API 呼叫。

第一個呼叫用來擷取有效語言清單。

Cloud Translation API 要求：

REQUEST: POST https://translation.googleapis.com/language/translate/v2/languages Authorization: Bearer ACCESSTOKEN Content-Type: application/json { "target": "en" }

Cloud Translation API 回應：

Content-Type: application/json { "data": { "languages": [ { "language": "af", "name": "Afrikaans" }, { "language": "sq", "name": "Albanian" }, ... ] } }

translate-v1 要求：

GET https://eval.example.com/translate/v1/languages

translate-v1 回應：

Content-Type: application/json [{"language":"af","name":"Afrikaans"},{"language":"sq","name":"Albanian"}, ... ]

API Proxy 必須將 GET 取代為 POST、移除 data 和 languages 回應欄位，並從屬性集取得譯文語言代碼。工作 1 的 Authentication 區段會自動新增存取權杖。

第二個呼叫會將文字翻譯成指定語言。

Cloud Translate API 要求：

POST https://translation.googleapis.com/language/translate/v2 Authorization: Bearer ACCESSTOKEN Content-Type: application/json { "q": "Hello world!", "target": "de" }

Cloud Translate API 回應：

Content-Type: application/json { "data": { "translations": [ { "translatedText": "Hallo Welt!", "detectedSourceLanguage": "en" } ] } }

translate-v1 要求：

POST https://eval.example.com/translate/v1?lang=de Content-Type: application/json { "text": "Hello world!" }

translate-v1 回應：

Content-Type: application/json { "translated": "Hallo Welt!" }

API Proxy 必須透過 lang 查詢參數取得譯文語言，並變更傳入和翻譯文字的欄位名稱。您可以選擇省略 translate-v1 要求中的 lang 查詢參數。這樣一來，系統會透過屬性集的屬性取得譯文語言。

注意： Translation API 的「q」欄位可接受單一字串或字串陣列。您的 API 應該只支援單一字串。

必要操作：

1. 在 API Proxy 建立名稱為「language.properties」的屬性集，其中應有兩個屬性：output (值為 es) 和 caller (值為 en)。caller 屬性會在列出 name 欄位使用的語言時，指定譯文語言；output 屬性則會在未提供 lang 查詢參數時，指定預設使用的譯文語言。

2. 在 Proxy 端點中，為 POST / 資源建立路徑和動詞條件式流程，並命名為 translate。

3. 在 Proxy 端點中，為 /languages 資源建立路徑 (無動詞) 條件式流程，並命名為 getLanguages。請勿加入動詞。您會將要求的動詞從 GET (用於輸入 Proxy 的內容) 改成 POST (後端需要的元素)。如果條件包含動詞，流程中的回應政策就不會執行，因為 request.verb 不再等於 GET。

4. 建立 AssignMessage 政策並命名為 AM-BuildTranslateRequest，建構用於 translate 條件式流程的後端要求。

政策應符合以下幾點：

• 包含附範本的 AssignVariable 來建立變數，稍後會用於記錄訊息。其中，text 變數應使用 jsonPath 訊息範本凾式擷取要求中的 text 欄位。

• 使用 firstnonnull 訊息範本凾式建立 language 變數。如有指定 lang 查詢參數值，這個變數應包含該值；如未指定 lang 查詢參數，則應使用語言屬性集的 output 屬性設定譯文語言。

• 應使用 Set 區段設定後端服務所需的 JSON 酬載。您建立的兩個變數都會用於酬載。

• [AssignTo] 元素應使用現有要求語言。

  AssignMessage 政策中的 AssignVariable 區段應與下方類似：

  <AssignVariable> <Name>...</Name> <Template>...</Template> <AssignVariable>

5. 在 translate 條件式流程下，建立 AssignMessage 政策並命名為 AM-BuildTranslateResponse，以便使用 Translation API 回應為呼叫端建立回應。

政策應符合以下幾點：

• 包含附 jsonPath 範本的 AssignVariable，以便建立 translated 變數來擷取 Translation API 回應中的 translatedText 欄位。提示：擷取這個欄位的 JSONPath 運算式為 $.data.translations[0].translatedText。

• 將 createNew 設為 true。

• 新的 JSON 酬載會使用 translated 變數。

  AssignMessage 政策中的 AssignVariable 區段應與下方類似：

  <AssignVariable> <Name>...</Name> <Template>...</Template> <AssignVariable>

6. 建立 AssignMessage 政策並命名為 AM-BuildLanguagesRequest，建構用於 getLanguages 條件式流程的後端要求

政策應符合以下幾點：

• 使用 Set 為後端要求設定正確的動詞和酬載。

• 應將 language 屬性集的 caller 屬性，做為後端酬載中的 target 欄位。

• 將 createNew 設為 true。

• 將後端要求酬載的內容類型設為 application/json。

  AssignMessage 政策中的 AssignVariable 區段應與下方類似：

  <AssignVariable> <Name>...</Name> <Set> ... </Set> </AssignVariable>

7. 在 getLanguages 條件式流程下，建立 JavaScript 政策並命名為 JS-BuildLanguagesResponse，為呼叫端建構回應。JavaScript 程式碼應使用下列步驟：

• 使用 context.getVariable 擷取 response.content 變數。
• 使用 JSON.parse 將 response.content JSON 轉換為物件。
• 使用 JSON.stringify 將物件中的 data.languages 欄位轉換為 JSON。
• 使用 context.setVariable 將 response.content 替換為步驟 3 中的 JSON。

您的 JavaScript 程式碼應與下方類似：

var payload = ...; var payloadObj = JSON.parse(...); var newPayload = JSON.stringify(...); context.setVariable(...); 注意： 請務必在正確的條件式流程下建立指定政策，並在對應的 .xml 檔案中編輯所需政策設定。

8. 測試 API。在 apigeex-test-vm 虛擬機器中，使用下列 curl 指令測試上述範例：

• 語言清單：

  curl -i -k -X GET "https://eval.example.com/translate/v1/languages"

• 翻譯成指定語言 (德文)：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

• 翻譯成預設語言 (西班牙文)：

  curl -i -k -X POST "https://eval.example.com/translate/v1" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

點選「Check my progress」，確認目標已達成。 變更 API 要求和回應

注意： 如果沒看到綠色勾號，請點按右上角的「Score」飛出式視窗，然後點選相關步驟的「Check my progress」。系統會開啟彈出式視窗並提供建議。

工作 3：新增 API 金鑰驗證和配額限制

這個 API 的存取權應僅限於已核准的應用程式，因此您將新增 VerifyAPI 金鑰政策和配額政策，限制要求數量。

必要操作：

1. 建立 API 產品，並將名稱和顯示名稱設為 translate-product。這個 API 產品應具備公開存取權、會自動核准存取要求，且可在 eval 環境中使用。

2. 在 API 產品「translate-product」中，新增一項作業來允許存取 translate-v1 Proxy，並使用 / 路徑允許存取任何要求 (包括 /)。允許的方法為 GET 和 POST。新增作業配額設定，將要求數量限制為每分鐘 10 個。

3. 設定電子郵件地址為 joe@example.com 的開發人員。您可以自行選擇姓氏、名字和使用者名稱。

4. 建立應用程式並命名為 translate-app，然後為該應用程式啟用 API 產品「translate-product」。該應用程式必須與 joe@example.com 開發人員建立關聯。

5. 在 Proxy 端點預先流程中，新增 VerifyAPIKey 政策並命名為 VA-VerifyKey。每個要求都應包含 API 金鑰，並使用 Key 標頭傳送。

6. 在 Proxy 端點預先流程中，新增 Quota 政策並命名為 Q-EnforceQuota。

政策應包含下列步驟：

• 使用 calendar 類型，且 calendar 類型須有 StartTime 元素。
• 指定 UseQuotaConfigInAPIProduct 使用 API 產品的配額。如果 API 產品未指定配額，則預設為每小時 5 個要求。
• 將 Distributed 和 Synchronous 設為 true，並移除 AsynchronousConfiguration 元素。

完成這些變更後，如果未在 Key 標頭指定有效的 API 金鑰，要求應會傳回錯誤。

7. 在 apigeex-test-vm 虛擬機器中，使用下列 curl 指令測試 API 金鑰功能：

• 失敗 (沒有 API 金鑰)：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

• 失敗 (API 金鑰無效)：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: ABC123" -d '{ "text": "Hello world!" }'

• 成功 (KEY 變數設為有效 API 金鑰：KEY=<get this from the earlier step when setting up a Developer App>)：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

點選「Check my progress」，確認目標已達成。 新增 API 金鑰驗證和配額限制

注意： 如果沒看到綠色勾號，請點按右上角的「Score」飛出式視窗，然後點選相關步驟的「Check my progress」。系統會開啟彈出式視窗並提供建議。

工作 4：新增訊息記錄

如要瞭解翻譯服務使用情形，可以設定 MessageLogging 政策來記錄每則翻譯訊息。

必要操作：

1. 在 translate 條件式流程中，新增 MessageLogging 政策並命名為 ML-LogTranslation。政策必須在 AM-BuildTranslateResponse 步驟後執行。

注意： 請勿在 PostClientFlow 中新增該政策，因為系統只會建立翻譯作業的記錄。

2. 政策應記錄到 Cloud Logging。請參閱這份政策文件。

• LogName 值應為：

  projects/{organization.name}/logs/translate

• 記錄訊息的 contentType 應為 text/plain，且訊息內容應如下所示：

  {language}|{text}|{translated}

這則訊息需要 language、text 和 translated 變數。這些變數是透過 AM-BuildTranslateRequest 和 AM-BuildTranslateResponse 政策建立。

3. 在 Google Cloud 控制台的「Logging」頁面中，驗證記錄訊息。請使用「logName : "translate"」查詢，只查看翻譯記錄。

4. 成功新增 MessageLogging 政策後，使用下列 curl 指令：

curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

• 該 curl 指令應會建立含下列內容的記錄訊息：

  de|Hello world!|Hallo Welt!

注意： 經過短暫延遲後，記錄訊息才會顯示在記錄中。

點選「Check my progress」，確認目標已達成。 新增訊息記錄

注意： 如果沒看到綠色勾號，請點按右上角的「Score」飛出式視窗，然後點選相關步驟的「Check my progress」。系統會開啟彈出式視窗並提供建議。

工作 5：重寫後端錯誤訊息

如果傳送至 Translation API 的 target 參數無效，系統會傳回 400 Bad Request 錯誤訊息：

{ "error": { "code": 400, "message": "Invalid Value", "errors": [ { "message": "Invalid Value", "domain": "global", "reason": "invalid" } ] } }

這則錯誤訊息會造成呼叫端混淆，因此請重寫錯誤訊息。

必要操作：

1. 在 default 目標端點中，新增 FaultRules 區段。當後端傳回 400 回應，系統會自動評估目標端點中任何相符的錯誤規則。

注意： 使用者介面左側的導覽選單無法用來新增 FaultRules 區段，請在目標端點的 XML 設定中新增這項資訊。

2. 在 FaultRules 區段新增 FaultRule。請務必設定 FaultRule 的 Condition。這樣一來，當 fault.name 為 ErrorResponseCode，FaultRule 才能執行。

3. 建立 AssignMessage 政策並命名為 AM-BuildErrorResponse，然後附加至 FaultRule。請使用以下政策設定：

<AssignMessage name="AM-BuildErrorResponse"> <Set> <Payload contentType="application/json">{ "error": "Invalid request. Verify the lang query parameter." }</Payload> </Set> </AssignMessage>

附加政策後，目標端點的 FaultRules 區段應與下方類似：

<FaultRules> <FaultRule name="..."> <Step> <Name>...</Name> </Step> <Condition>...</Condition> </FaultRule> </FaultRules> 注意： 請務必手動編輯目標端點 XML，確認這是 TargetEndpoint，而非 ProxyEndpoint。

4. 測試 API。

• 有效要求 (如下所示) 應仍可運作：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

• 如果語言查詢參數無效 (如下所示)，系統應會傳回重寫的錯誤訊息：

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=invalid" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

點選「Check my progress」，確認目標已達成。 重寫後端錯誤訊息

注意： 如果沒看到綠色勾號，請點按右上角的「Score」飛出式視窗，然後點選相關步驟的「Check my progress」。系統會開啟彈出式視窗並提供建議。

恭喜！

在這個挑戰實驗室課程，您展現了 Apigee X API 開發和安全性方面的知識。

取得下一枚技能徽章

這個自學實驗室是「透過 Apigee X 開發及保護 API」任務的一部分。完成這項技能徽章任務即可獲得上方的徽章，表彰您的成果。您可以在履歷表和社群平台張貼徽章，並加上 #GoogleCloudBadge 公開這項成就。

這個技能徽章任務是 Google Cloud API 開發人員學習路徑的一環。您可以報名「部署與管理 Apigee X」課程，繼續精進專業能力。

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

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

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

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