GSP843

總覽

API 是設計來讓應用程式開發人員用於為使用者提供獨特體驗。Google Cloud 的 Apigee API 平台可用於發布 API，方便應用程式開發人員運用。

在本實驗室中，您會建立 Apigee API Proxy，這項 Proxy 需要完成 API 金鑰驗證，才能限制 API 存取權。

您可以建立 API 產品，為內外部應用程式開發人員提供不同等級的服務；使用配額政策，限制每個應用程式的呼叫次數；以及建立 CORS 政策，為 API 新增跨源資源共享功能，允許從網頁應用程式呼叫 API。接著建立開發人員入口網站，並發布 API 產品供應用程式開發人員使用。

課程內容

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

• 驗證 API 金鑰，限制 API 存取權及追蹤應用程式使用情況
• 建立 API 產品，為不同類型的應用程式開發人員提供不同層級的存取權
• 根據附加的 API 產品，使用配額政策限制特定應用程式的呼叫次數
• 為 API 新增跨源資源共享 (CORS) 功能，允許網頁應用程式發出跨來源 API 呼叫要求
• 建立開發人員入口網站並發布 API 產品

設定和需求

瞭解以下事項後，再點選「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 總覽指南。

開啟 Apigee 控制台

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

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

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

• 前往導覽選單 ()，按一下「Apigee」旁的「收藏」圖示 ()。

這樣 Apigee 就會新增至導覽選單的收藏。

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

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

名為 simplebank-rest 的後端服務已建立並部署至 Cloud Run。

建立 Apigee Proxy

1. 在 Cloud Shell 中，使用下列指令擷取後端服務的網址：

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

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

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

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

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

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

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

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

   屬性	值
   Proxy 名稱	bank-v1
   基本路徑	/bank/v1
   目標 (現有 API)	backend URL

   注意： 確定使用「/bank/v1」做為基本路徑，而非「/bank-v1」。

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

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

5. 點選「下一步」。

6. 保留「Deploy (optional)」設定的預設值，然後按一下「建立」。

工作 2：新增 VerifyAPIKey 政策

在這項工作中，您會將 VerifyAPIKey 政策新增至 API Proxy。如果未提供有效的 API 金鑰，要求會遭到拒絕。

VerifyAPIKey 政策會在執行階段強制驗證 API 金鑰，只允許使用獲准 API 金鑰的應用程式存取 API。這項政策可確保 API 金鑰有效、未遭撤銷，且已獲准使用所要求資源。

新增 VerifyAPIKey 政策

1. 按一下「開發」分頁。

2. 在 Proxy 的導覽器選單中，按一下「Proxy Endpoints」部分中的「PreFlow」。

   應將 VerifyAPIKey 政策放在 API Proxy 流程的最前面。要求傳入 API Proxy 時，系統會先執行預設 Proxy 端點中的要求 PreFlow。

3. 在「Flow」窗格中，按一下要求流程右上方的「+ Add Policy Step」按鈕。

4. 選取「建立新政策」，並在「安全性」部分的「select policy」下方選取「Verify API Key」，然後將「顯示名稱」和「名稱」設為 VAK-VerifyKey。

5. 按一下「新增」。

6. 按一下 VAK-VerifyKey 名稱。

   「政策」下方的「程式碼」窗格會顯示 VerifyAPIKey 設定。

   APIKey 元素會標示要求中提供 API 金鑰的位置。

7. 在 APIKey 元素中，將 request.queryparam.apikey 替換為 request.header.apikey。

   如果 API 金鑰是在標頭中指定，較不可能記錄或儲存在瀏覽器記錄中。

修改目標，傳送 OpenID Connect 身分權杖

後端服務部署時，要求經過驗證才能存取，因此必須提供有效的 OpenID Connect 身分權杖，才能呼叫服務。

HTTPTargetConnection 會指定服務的後端目標。

1. 在 Proxy 的導覽器選單中，在「目標端點」部分按一下「PreFlow」。

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

   <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection>

注意： 如果沒有看到「HTTPTargetConnection」部分，請確認是在「目標端點」部分點選「PreFlow」，而不是「Proxy Endpoints」部分。

3. 在網址下方新增「驗證」部分，如下所示：

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

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

<TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <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>

5. 按一下「儲存」。

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

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

   export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; if [ -z "${GOOGLE_CLOUD_PROJECT}" ]; then echo "Error: GOOGLE_CLOUD_PROJECT environment variable is not set. Please set it to your project ID."; else 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}\" or (.environment | endswith(\"/${ENV_NAME}\"))) | .environment" --raw-output); [[ -n "${ATTACHMENT_DONE}" ]] && break; echo -n "."; sleep 5; done; echo; echo "${ENV_NAME} environment attached"; echo "***ORG IS READY TO USE***"; fi

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

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

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

   等待組織準備就緒期間，可以參閱 API 產品、CORS (跨源資源共享) 和開發人員入口網站瞭解相關資訊。

部署 API Proxy

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

2. 按一下「部署」。

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

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

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

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

6. 等待評估部署狀態顯示已部署 Proxy。

點選「Check my progress」，確認目標已達成。 建立 Apigee Proxy 並新增 VerifyAPIKey 政策

測試 API Proxy

您可使用主機名稱「eval.example.com」呼叫 Apigee 組織的評估環境。這個主機名稱的 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

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

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

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

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

4. 在評估環境中呼叫已部署的 bank-v1 API Proxy：

   curl -i -k -X GET "https://eval.example.com/bank/v1/customers"

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

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

   這個 API 會嘗試擷取客戶清單。現在您應該會看到類似以下「401 Unauthorized」回應：

   HTTP/2 401 content-type: application/json x-request-id: 01e8da87-dc8c-4428-9cdf-8bea84e98860 content-length: 146 date: Tue, 07 Dec 2021 22:54:37 GMT via: 1.1 google {"fault":{"faultstring":"Failed to resolve API Key variable request.header.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

   這項回應說明，因為未提供 API 金鑰，API Proxy 已禁止存取後端服務。

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

工作 3：新增 API 產品和應用程式

在這項工作中，您將新增 API 產品，提供不同層級的 API 存取權，接著建立兩個應用程式，並分別與 API 產品建立關聯，提供不同存取權給應用程式。

建立第一個 API 產品

第一個 API 產品提供服務的完整存取權。

1. 在 Apigee 導覽選單中，依序選取「發布」>「API 產品」。

2. 如要建立新的 API 產品，請按一下「+ 建立」。

3. 在「產品詳細資料」窗格中，指定下列項目：

   屬性	值
   名稱	bank-fullaccess
   顯示名稱	銀行 (完整存取權)
   說明	可完整存取銀行 API
   環境	選取「評估」
   存取權	選取「公開」

   請選取「Automatically approve access requests」。

4. 在「作業」部分中，按一下「+Add an Operation」。

   作業用於指定與 API 產品相關聯的應用程式，可以在哪些 API Proxy 中發出哪些要求。

   注意： 確認按鈕位於「作業」部分，而非「GraphQL Operations」部分。

5. 指定下列項目：

   名稱	值
   來源	選取 bank-v1 API Proxy
   路徑	/**
   方法	選取 GET、PATCH、POST、PUT 和 DELETE

   路徑運算式「/**」表示所有深度的任何路徑後置字串都符合作業的條件。

   在正式環境中，您可能會逐一新增允許的作業，而不是使用這個萬用字元路徑運算式。

6. 按一下「儲存」儲存作業。

7. 在 API 產品的「自訂屬性」部分，按一下「+ 新增自訂屬性」。

   自訂屬性可用於附加希望在 Proxy 中提供的任何資料，以控管存取權。

   在本例中，由於這是讓應用程式完整存取 Retail API 的 API 產品，因此您會建立自訂屬性，指出呼叫 API 的應用程式應獲得完整存取權。

8. 指定下列項目：

   屬性	值
   名稱	full-access
   值	yes

9. 按一下「確定」儲存自訂屬性。

10. 如要儲存 API 產品，請按一下頁面頂端的「儲存」。

11. 返回「發布」>「API 產品」頁面，畫面上會列出 API 產品。

點選「Check my progress」，確認目標已達成。 新增 API 產品和應用程式

建立提供有限存取權的 API 產品

第二個 API 產品會提供服務的唯讀存取權。

1. 如要建立新的 API 產品，請按一下「+ 建立」。

2. 在「產品詳細資料」窗格中，指定下列項目：

   屬性	值
   名稱	bank-readonly
   顯示名稱	銀行 (唯讀)
   說明	允許提供銀行 API 的唯讀存取權
   環境	選取「評估」
   存取權	選取「公開」

   請選取「Automatically approve access requests」。

3. 在「作業」部分中，按一下「+Add an Operation」。

   注意： 確認按鈕位於「作業」部分，而非「GraphQL Operations」部分。

4. 指定下列項目：

   屬性	值
   來源	選取 bank-v1 API Proxy
   路徑	/**
   方法	選取 GET

5. 按一下「儲存」儲存作業。

6. 如要儲存 API 產品，請按一下頁面頂端的「儲存」。

7. 返回「發布」>「API 產品」頁面，畫面上會列出 API 產品。

建立應用程式開發人員

建立應用程式之前，必須先建立應用程式開發人員。

注意： 應用程式開發人員通常是透過開發人員入口網站建立，您稍後會在實驗室中建立開發人員入口網站。目前請先使用 Apigee 控制台建立開發人員。

1. 在 Apigee 導覽選單中，依序點選「發布」>「開發人員」。

2. 如要建立新的應用程式開發人員，請按一下「+ 建立」。

3. 指定下列項目：

   屬性	值
   名字	小明
   姓氏	陳
   電子郵件	joe@example.com
   使用者名稱	joe

4. 按一下「新增」，建立應用程式開發人員。

建立具有唯讀存取權的應用程式

1. 在 Apigee 導覽選單中，依序點選「發布」>「應用程式」。

2. 如要建立新的應用程式，請按一下「+ 建立」。

3. 在「應用程式詳細資料」窗格中，指定下列項目：

   屬性	值
   名稱	readonly-app
   開發人員	選取陳小明

4. 在「憑證」窗格中，依序按一下「+ 新增憑證」和「+ 加入產品」，選取銀行 (唯讀)，然後按一下「新增」。

   在「產品」下方，按一下銀行 (唯讀) 旁邊的核取方塊，然後按一下「核准」。

5. 按一下「建立」，建立應用程式。

   應用程式的金鑰和密鑰已設定完成。

6. 在 Apigee 導覽選單中，依序點選「發布」>「應用程式」>「readonly-app」。

7. 在「憑證」下方，按一下「金鑰」旁邊的「顯示」。

   這是用來呼叫 API 的 API 金鑰。您可以複製金鑰，但我們後續會透過 curl 呼叫 Apigee API 來擷取 API 金鑰。

建立具有完整存取權的應用程式

1. 在左側導覽選單中，依序點選「發布」>「應用程式」。

2. 如要建立新的應用程式，請按一下「+ 建立」。

3. 在「應用程式詳細資料」窗格中，指定下列項目：

   屬性	值
   名稱	fullaccess-app
   開發人員	選取陳小明

4. 在「憑證」窗格中，依序按一下「+ 新增憑證」和「+ 加入產品」，選取銀行 (完整存取權)，然後按一下「新增」。

   在「產品」下方，按一下銀行 (完整存取權) 旁邊的核取方塊，然後按一下「核准」。

5. 按一下「建立」，建立應用程式。

6. 在 Apigee 導覽選單中，依序點選「發布」>「應用程式」>「fullaccess-app」。

7. 在「憑證」下方，按一下「金鑰」旁邊的「顯示」。

點選「Check my progress」，確認目標已達成。 建立提供有限存取權的 API 產品

使用 API 金鑰測試

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. 如果系統要求授權，請按一下「授權」。

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

3. 如要取得唯讀應用程式的 API 金鑰，請執行下列指令：

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) echo "PROJECT_ID=${PROJECT_ID}" export API_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) echo "API_KEY=${API_KEY}"

   第一組指令會讀取 gcloud 設定，以取得目前的專案。第二組指令會使用 Apigee API 擷取 API 金鑰。您傳送的存取權杖具有登入使用者的權限，因此要求已獲得授權。

4. 使用虛假的 API 金鑰，在評估環境中呼叫已部署的 bank-v1 API Proxy：

   curl -i -k -X GET -H "apikey: ABC123" "https://eval.example.com/bank/v1/customers"

   回應為 401 Unauthorized 並附帶錯誤訊息，指出 API 金鑰無效。

5. 使用真實的 API 金鑰，在評估環境中呼叫已部署的 bank-v1 API Proxy：

   curl -i -k -X GET -H "apikey: ${API_KEY}" "https://eval.example.com/bank/v1/customers"

   要求獲准，且回應中提供了客戶清單。

6. 再次使用真實的 API 金鑰，在評估環境中呼叫已部署的 bank-v1 API Proxy：

   curl -i -k -X POST -H "apikey: ${API_KEY}" -H "Content-Type: application/json" "https://eval.example.com/bank/v1/customers" -d '{"firstName": "Julia", "lastName": "Dancey", "email": "julia@example.org"}'

   這次的回應是 401 Unauthorized，並附帶錯誤訊息，指出 API 金鑰不適用於指定資源。要求之所以遭拒，是因為提供的 API 金鑰與唯讀 API 產品相關聯，但此類產品不允許 POST 要求。

7. 輸入 exit 結束虛擬機器 SSH 工作階段。

工作 4：強制執行配額

在這項工作中，您將新增配額政策，限制每個應用程式在特定時間內允許的要求數量。配額政策會套用 API 產品中指定的配額設定。

新增配額政策

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

3. 按一下「開發」分頁。

4. 在 Proxy 的導覽器選單中，按一下「Proxy Endpoints」部分中的「PreFlow」。

   配額政策會驗證特定應用程式的配額是否超出上限。如果達到上限，配額政策就會觸發錯誤訊息，並中止要求；如果未達上限，允許的要求數就會減少。

   配額政策會根據 VerifyAPIKey 政策填入的變數，判斷發出呼叫的應用程式。因此，配額政策必須放在 VerifyAPIKey 政策之後。

5. 在「Flow」窗格中，按一下要求流程右上方的「+ Add Policy Step」按鈕。

6. 選取「建立新政策」，並在「流量管理」部分的「select policy」下方選取「配額」，然後將「顯示名稱」和「名稱」設為 Q-EnforceQuota。

7. 按一下「新增」。

8. 按一下 Q-EnforceQuota 名稱。

   「配額」設定會顯示在「程式碼」窗格中。

9. 將配額設定變更為：

   <Quota continueOnError="false" enabled="true" name="Q-EnforceQuota" type="calendar"> <Identifier ref="client_id"/> <UseQuotaConfigInAPIProduct stepName="VAK-VerifyKey"> <DefaultConfig> <Allow>2</Allow> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> </DefaultConfig> </UseQuotaConfigInAPIProduct> <Distributed>true</Distributed> <Synchronous>true</Synchronous> <StartTime>2021-01-01 00:00:00</StartTime> </Quota>

   您將使用 API 產品，指定允許的 API 使用頻率。UseQuotaConfigInAPIProduct 元素中的 stepName 會指定決定 API 產品的步驟。

   驗證 API 金鑰或 OAuth 權杖後，即可將其和 API 產品相關聯的應用程式建立關聯。使用這些政策設定時，名為 VAK-VerifyKey 的 VerifyAPIKey 步驟會決定 API 產品。VerifyAPIKey 政策必須在 Q-EnforceQuota 政策之前執行。

   配額政策中指定的預設值，是每 (Interval) 個月 (TimeUnit) 最多 2 項 (Allow) 要求。只有在沒有可用值時，才會套用預設值，這只會在與 API 金鑰相關聯的 API 產品未設定配額設定時發生。

10. 按一下「儲存」。如果系統通知您已將 Proxy 儲存為新的修訂版本，請按一下「另存為新的修訂版本」。

11. 按一下「部署」。

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

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

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

14. 按一下「總覽」分頁，等待評估部署狀態顯示已部署 Proxy。

為提供完整存取權的 API 產品新增配額設定

1. 在 Apigee 導覽選單中，依序選取「發布」>「API 產品」，然後按一下銀行 (完整存取權)。
2. 按一下「編輯」。
3. 在「作業」部分找到「bank-v1」這一行，按一下「動作」選單圖示 ，然後選取「編輯」。
4. 將作業配額設為「5 requests every 1 minute」，然後按一下「儲存」儲存作業。

注意： 請務必編輯作業中設定的配額。

5. 按一下「儲存」，儲存 API 產品。

點選「Check my progress」，確認目標已達成。 強制執行配額

啟動偵錯工作階段

「偵錯」工具可監測在 Apigee 上執行的 API Proxy，並排解相關問題，還能在 API 呼叫期間，幫助您檢查每個步驟的詳細資料。

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

2. 按一下「偵錯」分頁。

3. 按一下「Start a debug session」。

4. 在「Start a debug session」窗格中，選取環境下拉式選單中的「評估」。

5. 按一下「啟動」。

   偵錯工作階段可能需要一小段時間，才會開始擷取要求。

注意： 如果在畫面頂端附近看到紅色方塊，當中顯示「Error fetching debug transactions」或「List debug session transaction error」錯誤訊息，偵錯工作階段可能仍可正常運作。

您將發出 API 要求，然後檢查偵錯工作階段。

測試配額

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. 如果系統要求授權，請按一下「授權」。

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

3. 如要取得這兩組 API 金鑰，請執行下列指令：

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) echo "PROJECT_ID=${PROJECT_ID}" export API_KEY_READONLY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) echo "API_KEY_READONLY=${API_KEY_READONLY}" export API_KEY_FULL=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/fullaccess-app" | jq ".credentials[0].consumerKey" --raw-output) echo "API_KEY_FULL=${API_KEY_FULL}"

4. 重複傳送這項要求，直到收到配額用盡錯誤訊息：

   curl -i -k -X GET -H "apikey: ${API_KEY_READONLY}" "https://eval.example.com/bank/v1/customers" 注意： 如要在 Cloud Shell 或 SSH 工作階段中快速重複執行指令，請按向上鍵，然後按 Return 或 Enter 鍵。

   配額用盡錯誤訊息大致如下所示：

   {"fault":{"faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : bKSV3nOz2JS5Z58sWMh2RBnnwWeEeNK2N2G6HMCESgLGDLFI","detail":{"errorcode":"policies.ratelimit.QuotaViolation"}}}

5. 返回 Apigee UI 分頁。

   您應該會看到一些狀態碼為 200 的要求，以及 1 筆狀態碼為 429 的要求。

   按一下狀態碼為 200 的要求。交易地圖右側會顯示工廠圖示，表示已呼叫後端。

6. 在「偵測工作階段錯誤」窗格中，按一下左上方的向左箭頭圖示 <。

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

8. 按一下「偵錯」分頁。

9. 按一下「Start Debug Session」，開始新的偵錯工作階段。

10. 返回 SSH 工作階段，然後使用對應完整存取權的 API 金鑰重複傳送這項要求，直到收到配額用盡錯誤訊息：

    date; curl -i -k -X GET -H "apikey: ${API_KEY_FULL}" "https://eval.example.com/bank/v1/customers"

    這次您應該可以傳送至少 5 項要求，才會因 429 回應而遭拒。提供完整存取權 API 產品的配額為每分鐘 5 項要求。時間的秒數歸零時，配額就會重設。上述指令會在呼叫 API 前顯示當前時間，因此您可以知道配額大約會在什麼時候重設。

11. 輸入 exit 結束虛擬機器 SSH 工作階段。

12. 返回 Apigee UI 分頁。

    選取要求並按一下配額圖示，您會發現 VAK-VerifyKey 配額變數現在顯示每分鐘 5 項要求。

工作 5：在 API Proxy 中新增 CORS

在這項工作中，您會將 CORS (跨源資源共享) 新增至 bank-v1 Proxy。

CORS 是一種通訊協定，使用 HTTP 標頭告知瀏覽器是否可從其他網域安全存取受限資源。根據預設，同源安全性政策會禁止跨網域要求，有助於保護瀏覽器使用者，避免在不知情的情況下，與不肖分子分享工作階段資訊。

同源政策的運作機制是，源於 www.example.com 的網頁在預設情況下無法呼叫 api.example.com 的 API，因為兩者主機名稱不同。CORS 可用來允許這類跨來源存取行為。

您需要在銀行 API 上啟用 CORS，開發人員入口網站才能存取。Apigee 開發人員入口網站的網域名稱為 *.apigee.io，API 則透過其他網域存取。如要從說明文件叫用 API，請將 CORS 標頭新增至所有 API 回應 (包括錯誤回應)。

CORS 也會使用預檢要求。瀏覽器會使用 OPTIONS HTTP 動詞傳送預檢要求，確定是否允許下一個呼叫要求。

CORS 政策可完成所有 CORS 相關操作。

如要進一步瞭解 CORS，請參閱 Apigee CORS 說明文件。

新增 CORS 政策

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

2. 按一下「開發」分頁。

3. 在 Proxy 的導覽器選單中，按一下「Proxy Endpoints」部分中的「PreFlow」。

4. 在「Flow」窗格中，按一下要求流程右上方的「+ Add Policy Step」按鈕。

5. 選取「建立新政策」，並在「安全性」部分的「select policy」下方選取「CORS」，然後將「顯示名稱」和「名稱」設為 CORS。

6. 按一下「新增」。

   「Flow」窗格下方會顯示「CORS 政策」設定。

   AllowOrigins 用於列出允許的來源。預設設定允許任何來源，因為它會將允許的來源設為要求中傳遞的 Origin。在一般正式環境中，可能只允許來自特定主機名稱的要求。

   AllowMethods 用於指定允許 API 使用的方法。

   AllowHeaders 用於列出可在要求中傳遞的標頭。

   ExposeHeaders 用於指定透過 Origin 呼叫時應允許的回應標頭。預設值為 *，表示不會從回應中移除任何回應標頭。

   MaxAge 用於指定瀏覽器可以快取預檢回應的時間長度 (以秒為單位)。

   AllowCredentials 用於指示可否在要求中傳送授權標頭、TLS 用戶端憑證或 Cookie。

   GeneratePreflightResponse 用於指定是否處理使用 OPTIONS 方法的預檢要求。

7. 按一下 CORS 名稱。

8. 將 AllowHeaders 設定替換為：

   <AllowHeaders>origin, x-requested-with, accept, content-type, apikey</AllowHeaders>

   您的 API 使用 apikey 標頭指定 API 金鑰，因此必須新增該標頭，才能從瀏覽器呼叫 API。

9. 將 MaxAge 值替換為 -1。

   這會停用瀏覽器對預檢回應的快取，因此您一律會看到預檢要求。在正式環境中，您通常會允許快取回應，避免每個要求都進行兩次呼叫。

10. 在 Proxy 的導覽器選單中，按一下「Proxy Endpoints」部分中的「PreFlow」。

    新增 CORS 政策時，會自動加到流程結尾的位置。不過，預檢要求不應要求提供 API 金鑰。

11. 編輯 PreFlow 設定，將 CORS 政策移至 VAK-VerifyKey 政策之前。將以下項目：

    <PreFlow name="PreFlow"> <Request> <Step> <Name>VAK-VerifyKey</Name> </Step> <Step> <Name>Q-EnforceQuota</Name> </Step> <Step> <Name>CORS</Name> </Step> </Request> <Response/> </PreFlow>

    替換為：

    <PreFlow name="PreFlow"> <Request> <Step> <Name>CORS</Name> </Step> <Step> <Name>VAK-VerifyKey</Name> </Step> <Step> <Name>Q-EnforceQuota</Name> </Step> </Request> <Response/> </PreFlow>

12. 按一下「儲存」。如果系統通知您已將 Proxy 儲存為新的修訂版本，請按一下「另存為新的修訂版本」。

13. 按一下「部署」。

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

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

15. 依序按一下「部署」和「確認」。

16. 按一下「總覽」分頁，等待評估部署狀態顯示已部署 Proxy。

點選「Check my progress」，確認目標已達成。 在 API Proxy 中新增 CORS

啟動偵錯工作階段

1. 按一下「偵錯」分頁。

2. 按一下「Start a debug session」。

3. 在「Start a debug session」窗格中，選取環境下拉式選單中的「評估」。

4. 按一下「啟動」。

   偵錯工作階段可能需要一小段時間，才會開始擷取要求。

測試 CORS 功能

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. 如果系統要求授權，請按一下「授權」。

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

3. 如要取得 API 金鑰，請執行下列指令：

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) echo "PROJECT_ID=${PROJECT_ID}" export API_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/fullaccess-app" | jq ".credentials[0].consumerKey" --raw-output) echo "API_KEY=${API_KEY}"

4. 提出擷取客戶清單的要求：

   curl -i -k -X GET -H "apikey: ${API_KEY}" "https://eval.example.com/bank/v1/customers"

   由於沒有 Origin，因此系統會略過 CORS 功能。確認未傳回 Access-Control-Allow-Origin 標頭。

5. 再次提出要求，但這次請加入 Origin 標頭。這會測試一般 CORS 要求：

   curl -i -k -X GET -H "Origin: https://www.example.com" -H "apikey: ${API_KEY}" "https://eval.example.com/bank/v1/customers"

   由於提供了 Origin，因此會傳回 access-control-* 標頭。

6. 提出預檢要求：

   curl -i -k -X OPTIONS -H "Origin: https://www.example.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type,apikey" "https://eval.example.com/bank/v1/customers"

   CORS 政策會在回應中設定預檢標頭，並禁止要求繼續傳送至後端。

   如要確認 CORS 政策是否不允許呼叫傳遞至後端服務，請返回 Apigee UI，查看「偵錯」工具中的 OPTIONS 呼叫。

7. 輸入 exit 結束虛擬機器 SSH 工作階段。

工作 6：下載及修改 OpenAPI 規格

在這項工作中，您將下載並修改用於定義 API Proxy 介面的 OpenAPI 規格。

將 API Proxy 發布至開發人員入口網站時會套用 OpenAPI 規格。

下載並編輯 OpenAPI 規格

1. 在 Cloud Shell 中執行下列指令，下載 API Proxy 的 OpenAPI 規格：

   curl https://storage.googleapis.com/spls/shared/firestore-simplebank-data/dev-portal/simplebank-spec.yaml?$(date +%s) --output ~/simplebank-spec.yaml

   這項 curl 指令會下載名稱為 simplebank-spec.yaml 的檔案，並儲存在主目錄中同名的檔案中。

注意： 「?$(date +%s)」會在網址中加入查詢參數，也就是代表目前日期/時間的字串。這個動態變數會變更網址，並強制 curl 擷取最新版檔案 (即使已快取先前版本也一樣)。

2. 在 Cloud Shell 中按一下「開啟編輯器」，然後視需要點選「在新視窗中開啟」。

   

3. 在編輯器中，選取 simplebank-spec.yaml 檔案。

   這個 OpenAPI 規格會指定在本實驗室中建立的 API Proxy 介面，並在開發人員入口網站中，用於提供即時說明文件。

   開發人員入口網站會從外部網路存取 Apigee Proxy。您使用的主機名稱 eval.example.com 僅適用於內部網路。

   系統已佈建負載平衡器，提供 API Proxy 的外部存取權。外部存取時會使用萬用字元 DNS 供應商 nip.io 提供的主機名稱，

   看起來會像這樣：

   eval.60.70.80.90.nip.io

   這個主機名稱已指定為 eval-group 環境群組的相符主機名稱。

4. 在 Cloud Shell 中，如要擷取 eval-group 設定，請使用下列指令：

   curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/envgroups/eval-group"

   主機名稱陣列包含兩個主機名稱：一個沒有 IP 位址 (eval.example.com)，另一個有 IP 位址 (類似於 eval.60.70.80.90.nip.io)。在 OpenAPI 規格中，您會使用有 IP 位址的主機名稱。

5. 在編輯器中，於第 10 行替換主機名稱：

   eval.<IPADDR>.nip.io

   在伺服器網址中替換主機名稱後，第 10 行應會類似於下方所示：

   - url: "https://eval.60.70.80.90.nip.io/bank/v1"

6. 依序點選「檔案」>「儲存」。

7. 依序用滑鼠右鍵按一下「simplebank-spec.yaml」>「下載」。

   檔案就會下載到本機電腦。您將透過開發人員入口網站使用新版規格。

工作 7：建立開發人員入口網站，並在當中發布 API

在這項工作中，您將建立整合式開發人員入口網站，然後在當中發布 API。

建立整合式開發人員入口網站

1. 在 Apigee 導覽選單中，依序選取「發布」>「入口網站」，然後按一下「+ 建立」。

2. 輸入銀行做為名稱，然後按一下「建立」。

   建立作業可能需要一分鐘，完成後應會開啟入口網站總覽頁面。

3. 如果畫面上顯示「Enroll in beta for team and audience management features」訊息，請按一下「註冊」。

將 API 發布到入口網站

1. 在 Apigee 導覽選單中，依序選取「發布」>「入口網站」，然後按一下銀行。

2. 按一下「+ API」。

3. 選取銀行 (完整存取權) 做為 API 產品。

4. 自訂 API 詳細資料：

   屬性	值
   已發布 (列於目錄)	selected
   顯示標題	SimpleBank
   顯示說明	SimpleBank API v1
   API 瀏覽權限	選取「公開」(所有人都能看見)

   「已發布」：API 會顯示在入口網站中；「公開」瀏覽權限：即使使用者未登入入口網站，也能看到 API。

5. 按一下 Display Image中的「選取」，然後按一下「網址」。

6. 將圖片網址設為：

   https://storage.googleapis.com/spls/shared/firestore-simplebank-data/dev-portal/piggy-bank.png

   點選「預覽」後，應該會看到小豬撲滿的圖片。

7. 按一下「選取」。

8. 在「API 說明文件」部分，選取「OpenAPI 說明文件」。

9. 在 Select File 中，按一下「選取」。

10. 點選「瀏覽」，然後選取從 Cloud Shell 下載的 OpenAPI 規格檔案 (simplebank-spec.yaml)。

11. 按一下「選取」。

12. 按一下「儲存」。

13. 如要在新分頁中開啟開發人員入口網站，請按一下右上角的「查看線上入口網站」。

點選「Check my progress」，確認目標已達成。 建立開發人員入口網站，並在當中發布 API

啟動偵錯工作階段

1. 返回 Apigee 導覽選單，依序選取「Proxy 開發」>「API Proxy」，然後點選「bank-v1」。
2. 按一下「偵錯」分頁。
3. 在「Start a debug session」窗格中，選取環境下拉式選單中的「評估」。
4. 按一下「啟動」。

使用開發人員入口網站測試 API

1. 在 Cloud Shell 中執行下列指令，取得提供完整存取權的 API 金鑰：

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) echo "PROJECT_ID=${PROJECT_ID}" export API_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/fullaccess-app" | jq ".credentials[0].consumerKey" --raw-output) echo "API_KEY=${API_KEY}"

   將 API 金鑰複製到剪貼簿。

2. 返回「Live Portal」分頁，然後按一下「API」。

3. 按一下小豬撲滿。

   畫面上會顯示 SimpleBank API。

4. 點選「授權」。

5. 將 API 金鑰貼到「金鑰」部分。

6. 按一下「授權」，然後按一下「確定」。

   現在，所有要求都會傳送這個 API 金鑰。

7. 按一下左選單中的「/customers POST」。

8. 指定下列要求主體：

   { "email": "mina@example.com", "lastName": "Yu", "firstName": "Mina" }

9. 按一下「執行」。

   200 OK 回應表示已建立客戶。

10. 按一下左選單中的「/customers GET」。

11. 按一下「執行」。

    剛剛建立的客戶會與資料庫中的其他客戶一同傳回。

    如果返回 Apigee UI 和偵錯工作階段，您可以看到在傳送這兩組指令前，瀏覽器已自動傳送 OPTIONS (預檢) 要求。由於瀏覽器不知道是否應允許 apikey 標頭，因此必須先發出預檢要求，才能執行 GET 指令。

工作 8：在入口網站中建立應用程式開發人員 (選擇性)

在這項工作中，您將使用開發人員入口網站建立應用程式開發人員。

注意： 這項工作需要輸入電子郵件地址，以便接收註冊電子郵件。電子郵件中會提供連結，請點選該連結，註冊的帳戶才能登入開發人員入口網站。提供的電子郵件地址不會用於其他任何用途，Google Cloud 專案自動刪除時便會一併移除。

在開發人員入口網站中註冊應用程式開發人員

1. 返回「Live Portal」，然後按一下「登入」。

2. 按一下「建立帳戶」。

3. 輸入名字、姓氏、電子郵件地址和密碼。

   您需要使用密碼登入開發人員入口網站，因此請選擇記得住的密碼。

4. 按一下表示同意條款的方塊。

   提供 API 給應用程式開發人員的組織會指定「條款及細則」頁面。

5. 按一下「建立帳戶」。

   一封電子郵件會傳送至您的電子郵件地址，必須點選當中連結，才能允許帳戶使用者登入。

6. 按一下電子郵件中的連結。

   開發人員入口網站會在瀏覽器分頁中開啟。

7. 按一下「登入」。

8. 輸入電子郵件地址和密碼，然後按一下「登入」。

為應用程式開發人員建立應用程式

1. 按一下右上角的電子郵件地址，然後點選「應用程式」。

2. 按一下「+ 新增應用程式」。

3. 將 MyApp 指定為應用程式名稱。

4. 在「API」部分找到「SimpleBank」，按一下「啟用」。

5. 按一下「儲存」。

   應用程式已註冊，畫面上會顯示 API 金鑰。這個 API 金鑰可能會用到開發人員入口網站中。如要查看應用程式開發人員和應用程式，請返回 Apigee UI，然後依序前往「發布」>「開發人員」和「發布」>「應用程式」。

恭喜！

在本實驗室中，您使用 API 金鑰驗證功能，限制 API 的存取權；建立了 API 產品，為內外部應用程式開發人員提供不同等級的服務；使用配額政策限制每個應用程式的呼叫次數，並新增 CORS 政策，在 API 中支援跨源資源共享；還建立開發人員入口網站，並發布 API 產品供應用程式開發人員使用。

後續步驟/瞭解詳情

• API 產品
• CORS (跨源資源共享)
• 開發人員入口網站。

Google Cloud 教育訓練與認證

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

使用手冊上次更新日期：2025 年 8 月 5 日

實驗室上次測試日期：2025 年 8 月 5 日

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