設計及編輯 API

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何在 Cloud Code 中設計及編輯 Apigee 的 API，並運用 Gemini Code Assist 加速建立、編輯及管理 API 規格。

事前準備

使用本指南中的功能前，請先完成下列事項：

• 請務必完成「在 VS Code 的 Cloud Code 中設定 Apigee API 管理平台」的設定步驟，包括「 搭配 Apigee 使用 Gemini Code Assist」。
• 請確認您的使用者帳戶具備「 在 Apigee 中使用 Gemini Code Assist 的必要角色」一文列出的角色，才能執行各項工作。

撰寫有效的 API 規格提示

建立及編輯 API 規格時，您會在 Apigee 中提示 Gemini Code Assist。生成 API 規格的準確度和適用性，主要取決於提供給模型的提示。

如要撰寫有效的 API 規格建立和編輯提示，請按照下列步驟操作：

• 使用 Gemini Code Assist Chat 時，請務必在提示開頭加上 Apigee 控制代碼 (@Apigee)，以建立或編輯 API 規格。Apigee 控制代碼可讓您存取 Apigee 工具，包括本指南所述的強大且功能豐富的 API 規格開發功能。
• 使用自然語言：撰寫提示時，想像自己正與人對話，請對方建立規格。
• 具體說明：盡可能提供確切需求，例如牙醫診所預約 API 必須包含多種預約類型和多個牙醫診所地點。
• 運用企業脈絡，不必指定物件名稱： Gemini Code Assist 會從 API 中心目錄智慧偵測並重複使用現有結構定義、中繼資料和安全性定義。雖然不需要指定確切的物件名稱，但您可以在提示中加入 Use API Hub 或 Leverage Enterprise Context 等詞組，暗示這項功能。
• 使用後續提示疊代 API：您可以使用「從這個 API 移除位置實體」等提示，變更 API。

以下是建立及編輯 API 規格時，效果較差和較好的提示範例：

效果較差的提示	提示說明	更完善的提示
「為我的商店建立 API。」	這個提示的資訊太少，模型無法生成完整且準確的規格。	「為我的商店建立 API，讓消費者查看產品供應情形，並將商品加入購物車。」 「建立 API，讓顧客能使用各種付款方式 (例如信用卡和簽帳金融卡) 支付訂單費用。」
「建立新的退款 API，重複使用訂單物件。」	建立 API 時，請勿指定 Gemini Code Assist 應重複使用的物件； Gemini Code Assist 會自動偵測最適合重複使用的物件。	「建立新的退款 API，讓顧客可以要求先前的訂單退款。」
「為外送服務建立 API。」	產生的 API 過於籠統。	「我們是披薩餐廳，希望採用線上客製化披薩外送解決方案。建立 API，接受披薩訂單，並提供披薩大小和配料。 「API for food delivery business. 顧客可以在單一訂單中訂購披薩、漢堡或三明治的組合。每種食物類型都有自己的結構定義。披薩有配料和尺寸。漢堡有配料和肉餅類型。三明治有麵包類型、肉類、蔬菜、起司和自訂指示。」

使用 Gemini Code Assist 設計 API

您可以在 Cloud Code 中使用 Gemini Code Assist，設計 OpenAPI 規格 (OAS) 3.0 版 API。設計的 API 在產生新 API 時可納入企業情境，且僅適用於使用 API 中心的專案。

如要瞭解如何設定，以便使用本節中的功能，請參閱「事前準備」。

如要使用 Gemini Code Assist 生成新 API，請按照下列步驟操作：

1. 使用下列其中一種方法存取 API 規格建立提示：
   • 從 Gemini Code Assist：對話：在對話視窗中輸入 Apigee 控制代碼 @Apigee，然後選取 Apigee 工具。
     
   • 從 Cloud Code 中的 Apigee：按一下「Apigee」資料列中的魔杖。 這會載入 Gemini Code Assist：Chat。使用 @Apigee 叫用 Apigee 工具，即可開始建立規格。
     
2. 從 Apigee 工具選項中選取「建立 API 規格」。
3. 在提示中填寫新 API 的說明。請參閱撰寫有效的 API 規格提示。(請勿複製及貼上 @Apigee 控制代碼。請在帳號代碼後方輸入或貼上文字，完成提示。
4. 提交提示。
5. Gemini Code Assist 會生成定義 API 的 OAS。(這項程序最多可能需要一分鐘。)如果 API Hub 包含其他 API，新的 OAS 可能會納入目錄中的物件和內容。情境式對話摘要會提供產生的 API 和使用的來源資訊。
6. 查看產生的規格。新 API 的 YAML 程式碼規格和 Swagger 面板都會自動顯示在分頁中。
7. 新規格完成後，您可以使用模擬伺服器進行測試。請參閱「使用模擬伺服器測試 API」。
8. 如要將新 API 儲存至 API 中心目錄，請參閱「將 API 發布至 API 中心」。
9. 如要從這項規格建立 Apigee API Proxy 套裝組合，請參閱「將 API 儲存為 API Proxy 套裝組合」。

編輯 API

您可以編輯本機儲存的 API，或是 API Hub 目錄中的 API。您在 Cloud Code 中所做的變更可以儲存至 API 中心，或儲存為 Apigee API Proxy 套裝組合。

從 API Hub 編輯 API 規格

如要編輯儲存在 API Hub 目錄中的 API 規格，請按照下列步驟操作：

1. 請確認您在 Cloud Code 中選取的專案，是包含要編輯 API 的 API 中心目錄專案。
2. 在左側導覽列中，展開 Apigee 部分的「API 中心」樹狀結構。
3. 從清單中選取要編輯的 API 和版本。
4. 在 Swagger 面板中查看 API 作業。在 Swagger 面板中點按「查看程式碼」，即可在編輯分頁中開啟 YAML 檔案。

編輯儲存在本機的 API 規格

如要編輯儲存在本機的 API 規格，請在 Cloud Code 中開啟 API 規格檔案。您可以手動更新規格，或使用 Gemini Code Assist Chat 疊代規格。

使用 Gemini Code Assist Chat 疊代 API 規格

您可以使用 Gemini Code Assist Chat 變更現有的 API 規格：

1. 按照「API 中心提供的 API 規格」或「本機 API 規格檔案」的操作說明，將規格檔案載入 Cloud Code。
2. 請確認包含規格的 YAML 檔案是編輯器中目前開啟的分頁。
3. 在 Gemini Code Assist 對話視窗中，輸入 Apigee 控制代碼 (@Apigee)，然後選取 Apigee 工具。
4. 輸入規格更新提示。如需相關指引，請參閱「 撰寫有效的 API 規格提示」。
5. (選用) 使用模擬伺服器測試 API。
6. 如要將新 API 儲存至 API 中心目錄，請參閱「將 API 發布至 API 中心」。
7. 如要從這項規格建立 Apigee API Proxy 套件，請參閱「將 API 儲存為 API Proxy 套件」。

將 API 發布至 API 中心

如果您使用 API Hub，可以向 API Hub 註冊 API，讓其他開發人員使用：

1. 在新的或已編輯 API 規格的 Swagger 面板中，按一下「發布至 API 中心」。
2. 在表單中提供 API 的中繼資料，以利在 API 中心目錄中搜尋及整理 API。大部分欄位都會從 API 規格自動填入，但您可以變更值。如要瞭解如何向 API 中心註冊 API，以及需要提供的資訊，請參閱「註冊 API」。
   • API 顯示名稱 (必填)：其他開發人員會看到的 API 名稱。
   • API 說明 (選用)：供內部/開發人員參考的 API 說明。
   • API 擁有者名稱 (選用)：API 擁有者的名稱。
   • API 擁有者電子郵件地址 (選填)：擁有者的電子郵件地址。
   • 「API Version」(API 版本) (必填)：API 版本。
   • 生命週期階段 (選用)：從清單中選取階段。
3. 按一下「發布」，將 API 發布至 API 中心。
4. 稍待片刻後，您應該就能在 Cloud Code 的 Apigee 專區中，看到 API Hub 樹狀結構的變更。

使用模擬伺服器測試 API

您可以透過本機模擬伺服器或以 Google Cloud為基礎的遠端模擬伺服器測試 API。系統預設會安裝並提供本機模擬伺服器，但您必須設定及管理 Google Cloud 模擬伺服器。

使用本機模擬伺服器

本機模擬伺服器會接受對這項 API 的要求，並模擬回應。只有目前使用者才能在目前工作階段中使用。不過，與遠端模擬伺服器不同，這種方式不需要設定或管理，也不會產生任何費用。

此外，本機模擬伺服器：

• 使用 Cloud Shell 編輯器或 Cloud Workstations 時，這項功能無法運作。
• 使用 VS Code Remote Explorer 時，可能無法正常運作。

如要使用本機模擬伺服器，請按照下列步驟操作：

1. 在「Servers」(伺服器) 下拉式選單中選取本機模擬伺服器 (如果尚未選取)：
   
2. 在 Swagger 面板中開啟路徑，然後按一下「Try it out」(試試看)。
   
3. 填寫任何要求參數，然後按一下「執行」。
   

使用遠端模擬伺服器

遠端模擬伺服器可建立持續性模擬伺服器執行個體，與本機模擬伺服器不同，遠端模擬伺服器可與貴機構中的其他使用者共用，並供他們用來測試新 API。遠端模擬伺服器只能搭配在 API 中心註冊的 API 使用。

部署模擬伺服器後，您對 API 所做的任何變更都不會自動更新至遠端模擬伺服器，因此請等到 API 完全建立完成後，再新增模擬伺服器。

部署 Google Cloud 遠端模擬伺服器會建立新的 Cloud Run 服務。這項作業會使用 Cloud Build 為模擬伺服器建構容器映像檔，並將容器映像檔上傳至 Google 專案中的 Cloud Artifact Registry。請參閱「什麼是 Cloud Run？」一文，管理服務，以及 Artifact Registry 說明文件。

您可以選擇使用預設服務帳戶，或是提供限制較多的服務帳戶來部署 Cloud Run 應用程式。詳情請參閱「在 Cloud Code for VS Code 中管理 Cloud API 和 Cloud 用戶端程式庫」。

重要事項：建立遠端模擬伺服器後，您必須負責支付相關費用和維護作業。您也必須在不再需要或使用時刪除該檔案。如需定價資訊，包括任何免費層級選項的資訊，請參閱 Cloud Run 定價。

如要部署遠端模擬伺服器，請按照下列步驟操作：

1. 從 Swagger 面板選取「Deploy mock server」(部署模擬伺服器)。
2. 如果 API 尚未在 API 中心註冊，請按照提示註冊。
3. 指定遠端模擬伺服器的詳細資料：伺服器名稱、安全伺服器、服務帳戶 (如要使用預設服務帳戶，請留空)，以及是否要將伺服器網址新增至 API 規格。 按一下「建立」，建立遠端模擬伺服器。
   重要事項： 請勿建立多個同名的遠端模擬伺服器，即使目前使用者介面不會阻止您這麼做。
4. 產生遠端模擬伺服器需要幾分鐘的時間。您可以在 Cloud Code OUTPUT 面板中，以及 VS Code 右下角的通知彈出式視窗中，查看進度。
5. 遠端模擬伺服器建立程序完成後，您會在 Swagger 面板伺服器清單和「OUTPUT」面板中看到遠端伺服器網址。
6. 如要使用模擬伺服器，請開啟路徑並點選「Try it out」。
   
   
   填寫任何要求參數，然後按一下「執行」。
   
   
   您也可以在提示中透過 curl 提出要求。使用「伺服器」下拉式選單中的伺服器位址和通訊埠。

如要與其他使用者共用模擬伺服器的存取權，請按照下列步驟操作：

1. 為其他使用者授予已部署服務的呼叫者角色。請參閱「驗證開發人員」。
2. 向模擬伺服器提出要求時，使用者會按照「測試私人服務」一文的操作說明進行。

如要管理已部署的遠端模擬伺服器，請按照下列步驟操作：

1. 前往 Apigee API Hub。
2. 找到 API，即可查看 API 的所有部署作業，包括任何遠端模擬伺服器。
3. 使用「資源網址」前往部署作業，並透過停止、刪除及在模擬伺服器上執行其他動作來管理部署作業。

將 API 儲存為 API Proxy 套裝組合

您可以將 API 儲存為 Apigee API Proxy 套件，以便在 Apigee 本機開發環境中處理。如要瞭解如何在 Cloud Code 中使用 API Proxy，請參閱「 開發 API Proxy」。

1. 在 Swagger 面板中，按一下「Create API proxy bundle」(建立 API Proxy 套裝組合)。
2. 在提示欄位中為 API Proxy 命名，然後繼續。
3. API Proxy 會顯示在本地工作區的 Apigee 左選單中，位於「apiproxies」apiproxies下方。

在規格生成過程中控制企業情境

OAS 生成作業可納入貴機構其他 API 的結構定義、中繼資料和安全性定義。這個程序會使用物件名稱和說明尋找類似的 API。系統不會考量 API 中心 API 的部署狀態。

企業環境預設為啟用。

如要停用新規格產生的企業背景資訊，請在 settings.json 檔案中 "cloudcode.apigee.gemini.enable": true 後方新增以下幾行：

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

地點：

• enabled：指定是否要全面啟用企業環境。設為 false 即可停用企業情境。
• includeMetadata 可控制是否要納入中繼資料內容。這項設定會決定是否要在 API Hub 中納入其他 API 的中繼資料。只有在 enabled 設為 true 時，才適用 includeMetadata。
• includeSchema 可控制是否要納入結構定義內容。這項設定會納入或排除 API 中心其他 API 的結構定義資訊。只有在 enabled 設為 true 時，才適用 includeSchema。
• includeSecurity 可控制是否要納入安全性相關內容。這項設定會決定是否要在 API Hub 中納入其他 API 的安全性資訊。只有在 enabled 設為 true 時，才適用 includeSecurity。