設計及編輯 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 Hub 目錄中，智慧偵測並重複使用現有的結構定義、中繼資料和安全性定義。雖然您不需要指定確切的物件名稱，但您可以在提示中加入 Use API Hub 或 Leverage Enterprise Context 等字詞，暗示這項功能。
• 使用後續提示來重複執行 API：您可以使用「從這個 API 中移除位置實體」等提示，修改 API。

以下是建立及編輯 API 規格時，較不理想和較理想的提示範例：

使用 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：Chat：在對話視窗中輸入 Apigee 代碼 @Apigee，然後選取 Apigee 工具。
     
   • 透過 Cloud Code 中的 Apigee：按一下「Apigee」資料列中的魔法棒。 這會載入 Gemini Code Assist：Chat。使用 @Apigee 叫用 Apigee 工具，即可開始建立規格。
     
2. 從 Apigee 工具選項中選取「Create API specification」。
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 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 面板中按一下「View code」，在編輯分頁中開啟 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 註冊至 API Hub，讓其他開發人員使用：

1. 在新增或編輯的 API 規格 Swagger 面板中，按一下「發布至 API 中心」。
2. 在表單中提供 API 的中繼資料，以便在 API Hub 目錄中改善 API 的可發現性和組織。大部分的欄位會從 API 規格自動填入，但您可以變更值。如要瞭解如何註冊 API 中心，以及需要提供的資訊，請參閱「註冊 API」。
   • API 顯示名稱 (必填)：其他開發人員可見的 API 名稱。
   • API 說明 (選用)：API 的說明，供內部/開發人員參考。
   • API 擁有者名稱 (選用)：API 擁有者的名稱。
   • API 擁有者電子郵件地址 (選填)：擁有者的電子郵件地址。
   • API 版本 (必填)：API 版本。
   • 生命週期階段 (選用)：從清單中選取階段。
3. 按一下「發布」，即可將 API 發布至 API 中心。
4. 經過短暫延遲後，您應該會在 Cloud Code 的 Apigee 專區中，看到 API Hub 樹狀結構中的變更內容。

使用模擬伺服器測試 API

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

使用本機模擬伺服器

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

本機模擬伺服器：

• 使用 Cloud Shell 編輯器或 Cloud Workstations 時無法使用。
• 使用 VS Code 遠端探索器時，可能無法正常運作。

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

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 用戶端程式庫」。

如何部署遠端模擬伺服器：

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

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

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

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

1. 前往 Apigee API 中心。
2. 找出 API，查看 API 的所有部署作業，包括任何遠端模擬伺服器。
3. 使用資源網址前往部署作業，並在模擬伺服器上執行其他操作，停止、刪除部署作業並進行管理。

將 API 儲存為 API Proxy 套裝組合

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

1. 按一下 Swagger 面板中的「Create API proxy bundle」。
2. 在提示訊息欄位中為 API Proxy 命名，然後繼續操作。
3. API Proxy 會顯示在本機工作區 Apigee 左選單的 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 Hub 中納入或排除其他 API 的結構定義資訊。只有在 enabled 設為 true 時，才能使用 includeSchema。
• includeSecurity 會控管是否要納入安全性相關的內容。這項設定會在 API Hub 中加入或排除其他 API 的安全性資訊。只有在 enabled 設為 true 時，才能使用 includeSecurity。