發布 API (原始版本)

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

如要讓應用程式開發人員使用 API，請按照下列各節所述，將 API 發布到入口網站。

API 發布總覽

將 API 發布至入口網站的程序分為兩個步驟：

  1. 選取要發布到入口網站的 API 產品。
  2. 從 OpenAPI 規格的快照自動產生 API 參考文件，方便應用程式開發人員瞭解您的 API。(如要進一步瞭解快照，請參閱「什麼是 OpenAPI 規格的快照？」一文)。

將 API 發布到入口網站時，系統會自動更新入口網站，包括：

  • API 參考頁面會新增至入口網站
    API 參考頁面會顯示您從 OpenAPI 規格快照自動產生的 API 參考說明文件。開發人員可以查看 API 說明文件，然後點按「試用」提出 API 要求並查看輸出內容。

    注意：您無法直接編輯這個頁面的內容，且這個頁面不會顯示在入口網站的頁面清單中。

  • API 參考資料頁面的連結已新增至 API 頁面
    API 頁面 (隨附於範例入口網站) 會列出發布至入口網站的所有 API，並提供各 API 參考文件的連結，方便您進一步瞭解。

    注意：您無法直接編輯這個頁面的內容，且這個頁面不會顯示在入口網站的頁面清單中。

什麼是 OpenAPI 規格快照？

在 API 的整個生命週期中，每個 OpenAPI 規格都是可靠的資料來源。從開發、發布到監控，API 生命週期的每個階段都使用相同的規格。修改規格時，請務必留意變更對 API 在其他生命週期階段的影響，詳情請參閱「修改規格會發生什麼事？」一文。

發布 API 時，系統會擷取 OpenAPI 規格的快照，產生 API 參考文件。該快照代表規格儲存庫中的特定規格版本。如果您使用規格編輯器修改 OpenAPI 規格，可以決定是否要再次擷取規格快照，以便在 API 參考文件中反映最新變更。

在 API Proxy 中新增 CORS 支援

發布 API 前，您需要在 API Proxy 中新增 CORS 支援，才能支援用戶端跨源要求。

CORS (跨源資源共享) 是一種標準機制，可讓網頁中執行的 JavaScript XMLHttpRequest (XHR) 呼叫與非來源網域的資源互動。CORS 是常見的解決方案，可因應所有瀏覽器強制執行的同源政策。舉例來說，如果您從瀏覽器中執行的 JavaScript 程式碼，對 Twitter API 發出 XHR 呼叫，該呼叫就會失敗。這是因為向瀏覽器提供網頁的網域，與提供 Twitter API 的網域不同。CORS 允許伺服器「選擇加入」跨源資源共享，藉此解決這個問題。

如要在發布 API 前為 API Proxy 新增 CORS 支援，請參閱「為 API Proxy 新增 CORS 支援」。

注意：大多數新式瀏覽器都會強制執行 CORS。請參閱支援瀏覽器的完整清單。如要深入瞭解 CORS，請參閱 跨源資源共享 W3C 建議。

瀏覽「API」頁面

如要存取「API」頁面，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 按一下入口網站首頁上的「API」。

或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。

畫面上會顯示 API 清單。

API 參考資料

如上圖所示，「API」頁面可讓您：

在入口網站中新增 API

注意：入口網站最多可新增 100 個 API。

如要在入口網站中新增 API，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 在入口網站首頁上，按一下「API」。
    或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。
  3. 按一下「+ API」。
    「Add API Product to Portal」(將 API 產品新增至入口網站) 對話方塊隨即顯示。

  4. 在對話方塊的「API 產品」分頁中，選取要新增至入口網站的 API 產品。

  5. 點選 [下一步]。

  6. 選取要用於快照的來源。
    如果您使用 OpenAPI 規格建立 API 產品中包含的 API Proxy，請從下拉式清單中選取規格。
    新增快照

    或者，你也可以選取：

    • 不指定規格，並在 API 發布後再新增，如「為規格建立快照」一文所述。
    • 選擇其他規格，選取或上傳新規格。

  7. 選取「已發布」核取方塊，將 API 發布到入口網站。如果尚未準備好發布 API，請取消選取「已發布」。
    您稍後可以變更設定，詳情請參閱「在入口網站發布或取消發布 API」。

  8. 在「目標對象」下方，選取下列其中一個選項，允許存取權來管理 API 目標對象：

    • 匿名使用者，允許所有使用者查看該頁面。
    • 已註冊的使用者：只允許已註冊的使用者查看頁面。

    如要變更這項設定，請參閱管理入口網站上的 API 目標對象。

  9. 按一下「Finish」。

拍攝規格快照

發布 API 後，您可以隨時擷取 OpenAPI 規格的新快照，更新入口網站上發布的 API 參考文件。

如要擷取 OpenAPI 規格的快照，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 在入口網站首頁上，按一下「API」。
    或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。
  3. 將游標移到要拍攝快照的 API 上，顯示動作。

  4. 按一下「快照圖示」。

    注意：如果快照與所選來源規格相符，系統會顯示訊息。

  5. 從「快照來源」下拉式選單選取現有規格，或選取「選擇其他規格」，選取或上傳新規格，用於產生 API 的說明文件。你也可以選取「無規格」來移除目前的規格。

  6. 按一下「更新快照」(或「移除快照」，如果已選取「無規格」)。

API 參考文件會根據規格產生，並新增至「API 參考資料」頁面。

在入口網站發布或取消發布 API

如要在入口網站發布或取消發布 API，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 在入口網站首頁上，按一下「API」。
    或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。
  3. 將游標移到要發布或取消發布的 API 上。
  4. 按一下「設定圖示」。
  5. 選取「已啟用」核取方塊，將 API 發布到入口網站。取消選取「已啟用」，即可取消發布 API。
  6. 按一下「儲存」。

在入口網站中管理 API 的目標對象

在入口網站上管理 API 的目標對象，方法是允許存取：

  • 所有使用者
  • 僅限已註冊的使用者

如要管理入口網站上 API 的目標對象，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 在入口網站首頁上，按一下「API」。
    或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。
  3. 將游標移到要管理目標對象的 API 上，顯示動作。
  4. 按一下「設定圖示」。
  5. 在「目標對象」下方，選取下列其中一個選項：
    • 匿名使用者：允許所有使用者查看 API 產品。
    • 已註冊的使用者：只允許已註冊的使用者查看 API 產品。
  6. 按一下「儲存」。

從入口網站移除 API

如要從入口網站移除 API，請按照下列步驟操作：

  1. 依序選取「發布」>「入口網站」，然後選取入口網站。
  2. 在入口網站首頁上，按一下「API」。
    或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API」。
  3. 將游標移到清單中的 API 上，即可顯示動作選單。
  4. 按一下「刪除」。

排解已發布 API 的問題

使用「試試看」時，如果系統傳回 TypeError: Failed to fetch 錯誤，請考慮下列可能原因和解決方法：

  • 如果是複合型內容錯誤，可能是已知的 swagger-ui 問題所致。其中一個可能的解決方法，是在 OpenAPI 規格的 schemes 定義中，確保 HTTPS 位於 HTTP 之前。例如： 

     schemes:
   - https
   - http

  • 如為 CORS (跨源資源共享) 限制錯誤，請確認 API Proxy 支援 CORS。 CORS 是一種標準機制，可讓用戶端發出跨源要求。請參閱「為 API Proxy 新增 CORS 支援功能」。請確認瀏覽器也已啟用 CORS。