GSP845

總覽

Apigee 是 API 開發與管理平台，可協助您運用 Google Cloud 服務 (如 Pub/Sub、Cloud Logging)，或是任何其他提供 REST API 的雲端服務。本實驗室將帶您瞭解如何透過 Apigee API Proxy 運用多項 Google Cloud 服務。

在本實驗室中，您會透過 Apigee API Proxy，使用多項 Google Cloud 服務處理使用者留言。

目標

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

• 啟用必要的 Google Cloud API
• 建立服務帳戶並套用適當角色
• 使用 Google Cloud REST API 呼叫 Google Cloud 服務
• 呼叫 Cloud Natural Language API 執行情緒分析
• 使用 PublishMessage 政策發布 Pub/Sub 訊息
• 將錯誤訊息記錄至 Cloud Logging

設定和需求

瞭解以下事項後，再點選「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：啟用 Google Cloud API

在這項工作中，您將啟用 Apigee API Proxy 會用到的 API。

1. 前往「Cloud 控制台」，依序點選「導覽選單」圖示 >「API 和服務」>「程式庫」。

   您可在這個頁面啟用 Apigee API Proxy 會用到的 API。

2. 在「搜尋 API 和服務」方塊中，輸入 Cloud Natural Language，然後按下 Enter 鍵。

   Cloud Natural Language API 會以自然語言提供洞察資訊，例如情緒分析和實體辨識結果。我們將使用這個 API 分析留言內容，判斷使用者是否不滿意。

3. 點選「Cloud Natural Language API」。

   API 已成功啟用。

   您也能使用 gcloud 指令啟用 API。

4. 在 Cloud Shell 執行下列指令，啟用必要的 API：

   gcloud services enable language.googleapis.com pubsub.googleapis.com logging.googleapis.com

   您啟用了 Cloud Natural Language API、Pub/Sub API 和 Cloud Logging API。

   如果 Natural Language API 指出使用者不滿意，系統會透過 Pub/Sub 將訊息發布至主題。您可選擇建立 Cloud 函式並針對每則訊息執行，與使用者聯絡來嘗試解決問題，並提高顧客滿意度。

   Cloud Logging 可為收到的每則留言擷取記錄項目。這些記錄可能包含內部 API 詳細資料，或許有助於偵測服務或應用程式的問題。

工作 2：建立服務帳戶

在這項工作中，您將建立 Apigee Proxy 要使用的服務帳戶。

建立 IAM 服務帳戶

1. 依序點選「導覽選單」圖示 >「IAM 與管理」>「服務帳戶」。

2. 點選「+ 建立服務帳戶」。

3. 在「服務帳戶名稱」部分指定下列值：

   apigee-gc-service-access

   Apigee API Proxy 可使用這個服務帳戶存取指定的 Google Cloud 服務。

4. 點選「建立並繼續」。

5. 在「選取角色」部分，依序選取「Pub/Sub」>「Pub/Sub 發布者」。

   Apigee API Proxy 即會發布至 Pub/Sub 主題。

6. 點選「+ 新增其他角色」。

7. 在「選取角色」部分，依序選取「Logging」>「記錄寫入者」。

   Apigee API Proxy 即可將記錄訊息寫入 Cloud Logging。

注意：呼叫 Natural Language API 不需要特定角色。

8. 點選「完成」。

   服務帳戶建立完畢。

點選「Check my progress」，確認目標已達成。建立服務帳戶並指派角色

工作 3：建立 API Proxy

在這項工作中，您將建立 Apigee API Proxy。稍後 API Proxy 會使用政策呼叫服務，因此無須指定目標。

開啟 Apigee 控制台

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

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

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

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

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

建立 Apigee API Proxy

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

2. 點選「Create」，使用 Proxy 精靈建立新的 Proxy。

3. 在「Proxy template」部分，依序選取「General template」>「No target」。

   這個 Proxy 不會使用後端服務，屆時與外部服務的所有通訊都將透過政策完成。

注意：請勿選取「OpenAPI spec template」部分的「No target」。

4. 在「Proxy details」部分指定下列值：

   屬性	值
   Proxy 名稱	services-v1
   基本路徑	/services/v1

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

5. 點選「下一步」。

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

建立新的條件式流程

1. 在 Proxy 編輯器中，點選「Develop」分頁標籤。

2. 在左側窗格中，依序選取「Proxy endpoints」>「default」。

3. 點選「Response」窗格上方的「+」按鈕。

4. 在「Add conditional flow」對話方塊中，指定下列值：

   屬性	值
   流程名稱	postComment
   說明	發布特定類別的留言
   條件類型	選取「Path and Verb」
   路徑	/comments
   動詞	選取「POST」。

   將「Target URL」留空。

5. 點選「Add」。

部署 API

1. 點選「儲存」。如果系統顯示訊息，通知您已將 Proxy 另存為新的修訂版本，請點選「另存為新的修訂版本」。

2. 點選「部署」。

3. 在「Environment」部分，選取「eval」。

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

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

5. 依序點選「Deploy」>「Confirm」。

   等待部署作業完成。

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

工作 4：呼叫 Natural Language API

在這項工作中，您將新增 ServiceCallout 政策來呼叫 Natural Language API，以便判斷傳入留言的情緒。

擷取輸入參數

POST/comments 資源會使用 JSON 酬載，其中包含兩個參數：comment (使用者輸入的任意文字) 和 category (指定留言類型)。ExtractVariables 政策則會擷取輸入內容。

1. 在「Flow」窗格中，移至「Request」窗格的「postComment」流程，然後點選旁邊的「+」。

2. 在「Add policy step」對話方塊，點選「Create new policy」。

3. 在「Select Policy」下拉式選單中，選取「Mediation」部分的「Extract Variables」政策類型。

4. 指定下列值：

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

5. 點選「Add」。

6. 點選「EV-ExtractRequest」政策，然後將 ExtractVariables 的 XML 設定改成下列內容：

<ExtractVariables name="EV-ExtractRequest"> <Source>request</Source> <JSONPayload> <Variable name="comment"> <JSONPath>$.comment</JSONPath> </Variable> <Variable name="category"> <JSONPath>$.category</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </ExtractVariables>

這項政策會從 POST/comments JSON 要求擷取 comment 和 category。另一方面，IgnoreUnresolvedVariables 元素設為 false，表示若未設定這兩項輸入內容，就會發生錯誤。

注意：使用正式環境 API 時，建議您新增錯誤處理程式碼，重新編寫大多數源於政策的錯誤內容。本實驗室並不會新增錯誤處理機制。

呼叫 Natural Language API

ServiceCallout 政策可呼叫 Natural Language API，傳回留言的情緒。

1. 如果 postComment 流程未醒目顯示，請按一下該流程，然後在「Response」窗格中，點選「postComment」流程旁邊的「+」。

   Natural Language API 呼叫的回應將傳回呼叫端。

2. 在「Add policy step」對話方塊，點選「Create new policy」。

3. 在「Select Policy」下拉式選單中，選取「Extension」部分的「Service Callout」政策類型。

4. 指定下列值：

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

5. 點選「Add」。

   流程應大致如下所示：

   

6. 點選「SC-NaturalLanguage」政策。

7. 將 ServiceCallout 的 XML 設定改成下列內容：

   <ServiceCallout name="SC-NaturalLanguage"> <Request clearPayload="true"> <Set> <Verb>POST</Verb> <Payload contentType="application/json">{ "document": { "content": "{comment}", "type": "PLAIN_TEXT" } } </Payload> </Set> </Request> <Response>response</Response> <HTTPTargetConnection> <Properties/> <URL>https://language.googleapis.com/v1/documents:analyzeSentiment</URL> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-language</Scope> </Scopes> </GoogleAccessToken> </Authentication> </HTTPTargetConnection> </ServiceCallout>

   ServiceCallout 政策的「Request」部分會指定發布至服務的要求，這個酬載的格式只適用於 Natural Language API。

   Response 元素則指出 Natural Language API 回應會儲存在 response 訊息中。

   「HTTPTargetConnection」部分會指定要呼叫的服務網址。如要瞭解網址、要求和回應格式，請參閱 Natural Language API 參考資料。

   「Authentication」部分指定了 Google Cloud API 的驗證機制，呼叫要求將自動加入 Google OAuth 存取權杖。「Scope」部分指出必須使用該存取權杖，才能存取 Natural Language API。

8. 點選「儲存」。

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

• 在 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 環境是否已附加。

接下來，等待執行個體準備就緒。

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

等待組織準備就緒期間，歡迎探索 Google Cloud 的 AI 產品和服務。

部署 API

1. 返回「services-v1」API Proxy，然後點選「Develop」分頁標籤。

2. 點選「部署」。

3. 在「Environment」部分，選取「eval」。

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

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

5. 依序點選「Deploy」>「Confirm」。

6. 點選「總覽」分頁標籤，等待「eval」部署作業狀態顯示 Proxy 部署完畢。

點選「Check my progress」，確認目標已達成。呼叫 Natural Language API

測試 API

您可使用主機名稱「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

   看到「Do you want to continue (Y/n)?」訊息時，請輸入 Y。

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

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

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

3. 在「eval」環境呼叫部署的「services-v1」API Proxy：

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"Jane was nice enough to return to her car to get me extra hot sauce. Thanks Jane!", "category":"delivery-reviews"}'

   Natural Language API 的回應會如下所示：

{ "documentSentiment": { "magnitude": 1.8, "score": 0.9 }, "language": "en", "sentences": [ { "documentSentiment": { "magnitude": 1.8, "score": 0.9 }, "language": "en", "sentences": [ { "text": { "content": "Jane was nice enough to return to her car to get me extra hot sauce.", "beginOffset": -1 }, "sentiment": { "magnitude": 0.9, "score": 0.9 } }, { "text": { "content": "Thanks Jane!", "beginOffset": -1 }, "sentiment": { "magnitude": 0.9, "score": 0.9 } } ] } ] }

「documentSentiment」分數範圍會介於 1 至 -1 之間；1 表示非常正面，-1 表示非常負面。在本例中，留言的情緒非常正面。

4. 再次呼叫 API Proxy：

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"delivery-reviews"}'

   這則留言的情緒相當負面。

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

工作 5：針對負面留言發布訊息至 Pub/Sub

在這項工作中，您將新增 PublishMessage 政策，每當收到負面留言時，系統就會將 Pub/Sub 訊息發布至 Pub/Sub 主題。主題訂閱端可執行工作流程，嘗試解決留言者的問題。

建立 Pub/Sub 主題來傳送評論

每個類別都要建立對應的 Pub/Sub 主題。您必須先建立主題，才能順利發布訊息。

1. 依序點選「導覽選單」圖示 >「Pub/Sub」>「主題」。

2. 點選「+ 建立主題」。

3. 在「主題 ID」部分，輸入 apigee-services-v1-delivery-reviews，然後點選「建立」。

   新的主題和訂閱項目隨即會建立。

從 Natural Language API 回應中擷取分數

1. 返回 Cloud 控制台的「Apigee」頁面。

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

3. 開啟「Develop」分頁。點選「postComment」流程。

4. 在「Flow」窗格中，移至「Response」窗格的「postComment」流程，然後點選旁邊的「+」。

5. 在「Add policy step」對話方塊，點選「Create new policy」。

6. 在「Select Policy」下拉式選單中，選取「Mediation」部分的「Extract Variables」政策類型。

7. 指定下列值：

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

8. 依序點選「Add」>「EV-ExtractSentiment」政策。

9. 將 ExtractVariables 的 XML 設定改成下列內容：

   <ExtractVariables name="EV-ExtractSentiment"> <Source>response</Source> <JSONPayload> <Variable name="sentimentScore"> <JSONPath>$.documentSentiment.score</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

新增 PublishMessage 政策

1. 依序點選「postComment」流程 >「Response」流程下方的「+」按鈕。

2. 在「Extension」部分，選取「Publish Message」政策類型。

3. 指定下列值：

   屬性	值
   顯示名稱	PM-PublishScore
   名稱	PM-PublishScore

4. 依序點選「Add」>「PM-PublishScore」政策。

5. 將 PublishMessage 的 XML 設定改成下列內容：

   <PublishMessage continueOnError="true" name="PM-PublishScore"> <Source>{response.content}</Source> <CloudPubSub> <Topic>projects/{organization.name}/topics/apigee-services-v1-{category}</Topic> </CloudPubSub> </PublishMessage>

6. 點選「儲存」。如果系統顯示訊息，通知您已將 Proxy 另存為新的修訂版本，請點選「另存為新的修訂版本」。

   response.content 是 Natural Language API 傳回的酬載，也就是 Pub/Sub 訊息。要求中的 category 則會用來建構 Pub/Sub 主題名稱。

   如果類別不正確，主題名稱將顯示為不存在。使用正式環境 API 時，建議您先確認指定的類別，再發布 Pub/Sub 訊息。在本例中，政策的 continueOnError 設為 true，因此即使主題不存在，也不會發生錯誤。

為 PublishMessage 政策新增條件式檢查

您可使用條件來選擇是否略過流程中的政策。

1. 在 Proxy 的導覽選單中，點選「Proxy Endpoints」下方的「default」。

   ProxyEndpoint 設定會隨即顯示。

2. 更改「PM-PublishScore」步驟來新增條件：

<Step> <Name>PM-PublishScore</Name> </Step>

改成下列內容：

<Step> <Name>PM-PublishScore</Name> <Condition>sentimentScore LesserThan 0.0</Condition> </Step>

這表示只有在情緒分數低於 0 時，PublishMessage 政策才會執行。

部署 API

1. 點選「儲存」。如果系統顯示訊息，通知您已將 Proxy 另存為新的修訂版本，請點選「另存為新的修訂版本」。

2. 點選「部署」。

3. 在「Environment」部分，選取「eval」。

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

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

5. 依序點選「Deploy」>「Confirm」。

點選「Check my progress」，確認目標已達成。針對負面留言發布訊息至 Pub/Sub

測試 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. 在「eval」環境呼叫部署的「services-v1」API Proxy：

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"delivery-reviews"}'

3. 依序點選「導覽選單」圖示 >「Pub/Sub」>「主題」。

4. 點選「apigee-services-v1-delivery-reviews」主題。

5. 向下捲動至底部，然後點選「apigee-services-v1-delivery-reviews-sub」訂閱項目。

6. 依序點選「訊息」分頁標籤 >「提取」。

7. 在訊息中，點選「查看所有資料列內容」下拉式選單按鈕。

   畫面上會顯示針對負面情緒留言傳送的 JSON 酬載內容。

工作 6：新增 MessageLogging 政策

在這項工作中，您將新增 MessageLogging 政策，將訊息記錄至 Cloud Logging。

建立 PostClientFlow

ProxyEndpoint 具有選用流程「PostClientFlow」。凡是附加至這個流程的政策，一律會在回應已傳回呼叫端之後執行。換句話說，這個流程不會提高要求的延遲時間，相當適合用來執行訊息記錄作業。

1. 返回「Apigee」分頁後，視需要返回 services-v1 的「Develop」頁面。

2. 在 Proxy 的導覽選單中，點選「Proxy Endpoints」下方的「default」。

   ProxyEndpoint 設定會隨即顯示。

3. 在「HTTPProxyConnection」部分的正上方，加入下列這行程式碼：

   <PostClientFlow/>

   新增這一行後，ProxyEndpoint 程式碼的底部應如下所示：

<PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow/> <HTTPProxyConnection> <BasePath>/services/v1</BasePath> </HTTPProxyConnection> <RouteRule name="noroute"/> </ProxyEndpoint>

這會為 ProxyEndpoint 新增空白的 PostClientFlow 流程。

新增 MessageLogging 政策

1. 在 Proxy 的導覽選單中，選取「Proxy Endpoints」下方的「PostClientFlow」，然後點選「Response」流程下方的「+」按鈕。

2. 在「Add policy step」對話方塊，點選「Create new policy」。

3. 在「Select Policy」下拉式選單中，選取「Extension」部分的「Message Logging」政策類型。

4. 指定下列值：

   屬性	值
   顯示名稱	ML-LogToCloudLogging
   名稱	ML-LogToCloudLogging

5. 依序點選「Add」>「ML-LogToCloudLogging」政策。

6. 將 PublishMessage 的 XML 設定改成下列內容：

   <MessageLogging name="ML-LogToCloudLogging"> <CloudLogging> <LogName>projects/{organization.name}/logs/apiproxy-{apiproxy.name}</LogName> <Message contentType="application/json">{ "messageid": "{messageid}", "environment": "{environment.name}", "apiProxy": "{apiproxy.name}", "proxyRevision": "{apiproxy.revision}", "uri": "{request.uri}", "statusCode": "{response.status.code}", "category": "{category}", "score": "{sentimentScore}", "publishFailed": "{publishmessage.failed}" }</Message> <Labels> <Label> <Key>proxyName</Key> <Value>services-v1</Value> </Label> </Labels> </CloudLogging> </MessageLogging>

   「CloudLogging」部分會指定要記錄至 Cloud Logging 的資訊。這項政策會使用 Proxy 名稱設定 LogName，方便您在 Cloud Logging 尋找。

   這項政策的訊息是 JSON 訊息，但您可在記錄中使用任何類型的文字訊息。記錄內容通常應包含 Proxy 流程變數，有助於偵錯任何問題。舉例來說，如果 Pub/Sub 訊息未送出，變數「publishmessage.failed」就會是 true。

   您也能為記錄的訊息加上標籤來歸類。

部署 API

1. 點選「儲存」。如果系統顯示訊息，通知您已將 Proxy 另存為新的修訂版本，請點選「另存為新的修訂版本」。

2. 點選「部署」。

3. 在「Environment」部分，選取「eval」。

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

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

5. 依序點選「Deploy」>「Confirm」。

   等待部署作業完成。

點選「Check my progress」，確認目標已達成。新增 MessageLogging 政策

測試 API

1. 如果 SSH 連線已關閉，請在 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. 在「eval」環境呼叫部署的「services-v1」API Proxy：

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"The driver never arrived with my dinner. :(", "category":"invalid-category"}'

   這表示提供的類別 (invalid-category) 沒有對應的 Pub/Sub 主題。

3. 依序點選「導覽選單」圖示 >「記錄」>「Logs Explorer」。

4. 在「查詢」方塊中，輸入下列查詢：

   "invalid-category"

5. 點選「執行查詢」。

6. 在「查詢結果」窗格中，依序展開記錄項目和「jsonPayload」。

展開記錄項目後，會看見記錄的 JSON 訊息和其他中繼資料。jsonPayload 應如下所示：

{ "apiProxy": "services-v1", "category": "invalid-category", "environment": "eval", "messageid": "32c1eda7-f661-98f4-8d66-3c1c158dc620", "proxyRevision": "4", "publishFailed": "true", "score": "-0.8", "statusCode": "200", "uri": "/services/v1/comments" }

publishFailed 為 true，因為這個類別並未建立主題。提醒您，清楚詳盡的記錄有助於找出 API Proxy 和後端服務的問題。

恭喜！

在本實驗室中，您啟用了 Google Cloud API、建立服務帳戶，並採用 Apigee 提供的服務帳戶驗證資訊，使用 ServiceCallout 政策呼叫 Cloud Natural Language API。接著，您透過 PublishMessage 政策將訊息發布至 Pub/Sub 主題。最後，您使用 MessageLogging 政策將訊息記錄至 Cloud Logging。

後續步驟/瞭解詳情

• Pub/Sub
• Cloud Logging
• AI 和機器學習產品，包括 Cloud Natural Language API

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

使用手冊上次測試日期：2025 年 8 月 8 日

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