發布 API

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊

將 API 發布到入口網站，方便應用程式開發人員使用，如以下各節所述。

API 發布總覽

將 API 發布到入口網站的程序有兩個步驟：

  1. 選取要發布至入口網站的 API 產品。
  2. 以 OpenAPI 文件或 GraphQL 結構定義的快照提供 Render API 參考說明文件，方便應用程式開發人員瞭解您的 API。(如要進一步瞭解快照，請參閱「什麼是快照？」一文)。

哪些項目會發布至入口網站？

發布 API 時，系統會自動對入口網站進行以下更新：
  • API 參考說明文件。視您使用 OpenAPI 文件還是 GraphQL 結構定義來發布 API 時，系統提供的介面會有所不同。請參閱以下資訊：
  • API 頁面中新增 API 參考資料頁面的連結

    API 頁面 (包含在範例入口網站中) 會列出發布至入口網站的所有 API，並按字母順序排列，並提供相關 API 參考說明文件連結，進一步瞭解相關資訊。您也可以自訂下列項目：

    • 每張 API 資訊卡顯示的圖片
    • 用於標記 API 的類別，可讓開發人員在 API 頁面上探索相關 API

    線上入口網站的 API 頁面，顯示兩種類別的圖片與使用情況

    • SmartDocs (OpenAPI)

    使用 OpenAPI 文件發布 API 時，SmartDocs API 參考說明文件會加入入口網站中。

    開發人員可以查看您的 SmartDocs API 參考說明文件，並使用「試用這個 API」面板提出 API 要求並查看輸出內容。您可以嘗試這個 API，根據 OpenAPI 文件中定義的安全性方法，搭配不安全的端點或採用基本驗證、API 金鑰或 OAuth 驗證的安全防護端點。針對 OAuth，支援的流程如下：授權碼、密碼和用戶端憑證。

    API 參考說明文件頁面，其中說明瞭如何授權 API 呼叫、取消固定「試用這個 API」面板、下載相關規格及執行 API。

    按一下「」展開「試用這個 API」面板。展開的面板可讓您查看各種格式 (例如 HTTP、Python、Node.js 等) 的 curl 呼叫和程式碼範例，如下所示。

    展開「試用這個 API」面板

    GraphQL Explorer

    使用 GraphQL 結構定義發布 API 時，GraphQL Explorer 會新增到入口網站中。GraphQL Explorer 是一個互動式遊樂場，可讓您針對 API 執行查詢。此探索工具是以 GraphiQL 為基礎，這是由 GraphQL Foundation 開發的 GraphQL IDE 參考實作。

    開發人員可以使用 GraphQL Explorer 探索結構定義式互動式說明文件、建立及執行查詢、查看查詢結果，以及下載結構定義。如要安全存取您的 API，開發人員可以在「Request Headers」窗格中傳遞授權標頭。

    如要進一步瞭解 GraphQL，請參閱 graphql.org。

    入口網站的 GraphQL Explorer

    什麼是快照？

    每項 OpenAPI 或 GraphQL 文件都會做為 API 生命週期中的可靠資料來源。在 API 生命週期的每個階段，從開發、發布到監控，都會使用這份文件。修改文件時，您必須瞭解這樣的變更在其他生命週期階段對 API 的影響。詳情請參閱「修改文件會有什麼影響？」

    發布 API 時，您必須拍攝 OpenAPI 或 GraphQL 文件的快照，以轉譯 API 參考說明文件。該快照代表文件的特定版本。如果您修改文件，可以選擇拍攝文件另一張快照，以反映 API 參考說明文件中的最新變更。

    關於回呼網址

    如果您的應用程式需要回呼網址，例如在使用 OAuth 2.0 授權碼授權類型 (通常稱為「三足式 OAuth」) 時，您可以要求開發人員在註冊應用程式時指定回呼網址。回呼網址通常會指定應用程式的網址，指定為代表用戶端應用程式接收授權碼。詳情請參閱「實作授權碼授權類型」。

    您可以在在入口網站新增 API 時，設定應用程式註冊期間是否需要回呼網址。您隨時可以修改這項設定，詳情請參閱「管理 API 的回呼網址」一文。

    註冊應用程式時，開發人員必須針對所有需要的 API 輸入回呼網址，如「註冊應用程式」一文所述。

    將 API Proxy 設定為支援「試用這個 API」

    使用 OpenAPI 文件發布 API 之前，您需要先設定 API Proxy，才能支援在 SmartDocs API 參考說明文件中的「試用這個 API」面板提出要求，說明如下：

    • 在 API Proxy 中新增 CORS 支援，強制執行用戶端跨源要求

      CORS 是一種標準機制，可讓在網頁中執行的 JavaScript XMLHttpRequest (XHR) 呼叫與非來源網域的資源互動。CORS 是所有瀏覽器強制執行的「同源政策」常實作的解決方案。

    • 如果你使用的是基本驗證或 OAuth2，請更新 API Proxy 設定

    下表歸納了 API Proxy 設定需求，根據驗證存取權而在 SmartDocs API 參考說明文件中支援「試用這個 API」面板。

    驗證存取權 政策設定規定
    無或 API 金鑰 在 API Proxy 中新增 CORS 支援。為方便起見，請使用 GitHub 提供的範例 CORS 解決方案，或按照「新增 CORS 支援至 API Proxy」一文中的步驟操作。
    基本驗證 請執行下列步驟：
    1. 在 API Proxy 中新增 CORS 支援。為方便起見，請使用 GitHub 提供的範例 CORS 解決方案，或按照「新增 CORS 支援至 API Proxy」一文中的步驟操作。
    2. 在「Add CORS AssignMessage」政策中，確認 Access-Control-Allow-Headers 標頭包含 authorization 屬性。例如：
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
    OAuth2
    1. 在 API Proxy 中新增 CORS 支援。為方便起見，請使用 GitHub 提供的範例 CORS 解決方案，或按照「新增 CORS 支援至 API Proxy」一文中的步驟操作。
    2. 在「Add CORS AssignMessage」政策中，確認 Access-Control-Allow-Headers 標頭包含 authorization 屬性。例如：
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
    3. 修正 OAuth2 政策中不符合 RFC 規範的行為。為了方便起見，請參考 GitHub 提供的 OAuth2 範例解決方案，或按照下列步驟操作：
      • 確認 OAuth2 政策中的 <GrantType> 元素已設為 request.formparam.grant_type (表單參數)。詳情請參閱 <GrantType>。
      • 確認 OAuth2 政策中的 token_type 已設為 Bearer，而非預設的 BearerToken。

    探索 API 目錄

    如要查看 API 目錄，請按照下列步驟操作： 1. 依序選取「Publish」(發布) >「Ports」(入口網站)，然後選取入口網站。2. 點選入口網站首頁的「API Catalog」。或者，您也可以在頂端導覽列的入口網站下拉式選單中選取「API 目錄」。

    API 目錄的「API」分頁會顯示已新增至入口網站的 API 清單。

    顯示 API 相關資訊的 API 分頁，包括名稱、說明、瀏覽權限、類別、相關規格和修改時間

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

    在入口網站中新增 API

    如何在入口網站新增 API：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。

    3. 按一下 [+]。+

      系統隨即會顯示「將 API 產品新增至目錄」對話方塊。

    4. 選取要新增至入口網站的 API 產品。

    5. 點選「下一步」。 系統隨即會顯示 API 詳細資料頁面。

    6. 設定 API 參考說明文件內容，以及入口網站上的瀏覽權限：

      欄位 說明
      已發布選取「已發布」，將 API 發布至入口網站。如果您還沒準備好發布 API，請取消勾選核取方塊。您日後可以變更這項設定，詳情請參閱「在入口網站上發布或取消發布 API」。
      顯示標題 更新顯示在目錄中的 API 標題。根據預設，系統會使用 API 產品名稱。日後你可以按照「編輯顯示標題和說明」中的說明，變更顯示標題。
      顯示說明 更新顯示在目錄中的 API 說明。根據預設，系統會使用 API 產品說明。日後也可以變更顯示說明，詳情請參閱「編輯顯示標題和說明」一節。
      開發人員必須指定回呼網址如果你想要求應用程式開發人員指定回呼網址，請啟用這個選項。您可以稍後再新增或更新回呼網址，詳情請參閱「管理 API 的回呼網址」一文。
      API 說明文件 如何使用 OpenAPI 文件：
      1. 選取「OpenAPI document」。
      2. 按一下「選取文件」。
      3. 執行下列其中一項操作：
        • 按一下「My Specs」分頁標籤，然後從規格商店中選取規格。
        • 按一下「上傳檔案」分頁標籤，然後上傳檔案。
        • 按一下「Import from a URL」(從網址匯入) 分頁標籤，然後從網址匯入規格。
      4. 按一下「選取」。

      如何使用 GraphQL 結構定義：

      1. 選取「GraphQL 結構定義」。
      2. 按一下「選取文件」。
      3. 前往並選取 GraphQL 結構定義。
      4. 按一下「選取」。

      您也可以選取「沒有說明文件」，然後在新增 API 後再新增，如管理文件的快照所述。

      API 瀏覽權限

      如果您尚未註冊目標對像管理功能 Beta 版，請選取下列其中一個選項：

      • 匿名使用者：允許所有使用者查看 API。
      • 已註冊的使用者：僅允許已註冊的使用者查看 API。

      如果您已註冊目標對像管理功能 Beta 版，請選取下列其中一個選項：

      • 公開 (所有人都看得見)：讓所有使用者都能查看 API。
      • 已驗證的使用者：僅允許已註冊的使用者查看 API。
      • 已選取的目標對象，選擇您要查看 API 的特定目標對象。

      之後可以按照「在入口網站管理 API 的瀏覽權限」一文的說明管理目標對象瀏覽權限。

      多媒體圖像 如要在 API 頁面的 API 資訊卡中顯示圖片，請按一下「選取圖片」。在「選取圖片」對話方塊中，選取現有圖片、上傳新圖片或提供外部圖片的網址，然後按一下「選取」。預覽 API 縮圖，然後按一下「選取」。您可以稍後再新增圖片，詳情請參閱「管理 API 資訊卡的圖片」。使用外部網址指定圖片時，系統不會將該圖片上傳至您的素材資源；此外，在整合的入口網站中載入圖片時，可能會受內容安全性政策封鎖或限制。
      類別

      新增要為 API 加上標記的類別，方便應用程式開發人員在 API 頁面上探索相關 API。如何識別類別：

      • 從下拉式清單中選取類別。
      • 輸入新類別的名稱，然後按下 Enter 鍵。新類別將新增至「類別」頁面，並在新增或編輯其他 API 時出現。

    7. 點按「儲存」。

    管理文件快照

    發布 API 後，您隨時可以拍攝 OpenAPI 或 GraphQL 文件的快照，以更新發布於入口網站的 API 參考說明文件。

    如何管理文件快照：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 檢查快照狀態。 如果資訊已過時，則會顯示下列訊息： 指出快照過時的圖示和訊息
    5. 按一下「編輯圖示」。
    6. 執行下列其中一項工作：
      • 如要重新整理已過期的 OpenAPI 文件快照，請按一下「Refresh Snapshot」。
      • 如要變更用來產生 API 文件的文件，請按一下 API 說明文件下方的「選取文件」，然後選取新文件。
    7. 點按「儲存」。

    API 參考說明文件會從文件轉譯，並新增至「API 參考資料」頁面。快照狀態會更新為：

    表示目前快照的圖示和訊息

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

    如何在入口網站發布或取消發布 API：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。
    5. 在「API 詳細資料」下方，選取或取消選取「已發布 (列於目錄)」，分別在入口網站上發布或取消發布 API。
    6. 點按「儲存」。

    管理入口網站的 API 瀏覽權限

    如要管理入口網站的 API 瀏覽權限，請授予下列項目的存取權：

    如何管理入口網站中 API 的瀏覽權限：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。
    5. 在「API 瀏覽權限」下方，選取下列其中一個選項：

    6. 選取瀏覽權限設定。 如果您已註冊使用目標對像功能的 Beta 版，請選取下列其中一個選項：

      • 公開 (所有人都看得見)：允許所有使用者檢視網頁。
      • 已驗證的使用者：僅允許已註冊的使用者查看網頁。
      • 已選取的目標對象，選取您想查看網頁的目標對象。請參閱「管理入口網站的目標對象」一文。
      否則，請選取下列其中一個選項：
      • 匿名使用者：允許所有使用者檢視網頁。
      • 已註冊的使用者：僅允許已註冊的使用者查看網頁。

    7. 點選「提交」。

    管理 API 的回呼網址

    管理 API 的回呼網址。請參閱「關於回呼網址」。

    如要管理 API 的回呼網址：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。
    5. 在「API 詳細資料」下方，選取或取消選取「已發布 (列於目錄)」，分別在入口網站上發布或取消發布 API。
    6. 點按「儲存」。

    管理 API 資訊卡的圖片

    您可以新增或變更目前的映像檔，藉此管理 API 頁面中顯示的 API 資訊卡圖片。

    如何管理 API 資訊卡的圖片：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。

    5. 在「API 詳細資料」下方：

      • 如果目前未選取任何圖片，請按一下「選取圖片」指定或上傳圖片。
      • 點選「變更圖片」，即可指定或上傳其他圖片。
      • 按一下圖片中的「x」即可移除。x

      指定圖片時，請指定含有目錄項目外部網址的圖片，或是 儲存在入口網站中的圖片檔檔案路徑，例如 /files/book-tree.jpg。指定外部圖片的網址時，該圖片不會上傳至您的素材資源；此外，在整合式入口網站中載入圖片時，圖片的可用性可能會受到 內容安全性政策封鎖或限制。

    6. 點按「儲存」。

    使用類別標記 API

    以下列其中一種方式使用類別標記 API：

    • 管理 API 在編輯 API 時標記的類別，如下所述。
    • 在編輯類別時管理已標記類別的 API。

    若要在編輯 API 時標記類別，請按照下列步驟進行：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。
    5. 在「類別」欄位中按一下，然後執行下列任一操作：
      • 從下拉式清單中選取類別。
      • 輸入新類別的名稱，然後按下 Enter 鍵。新類別將新增至「類別」頁面，並在新增或編輯其他 API 時出現。
    6. 重複以上步驟，將 API 標記為更多類別。
    7. 點按「儲存」。

    編輯顯示標題和說明

    如要編輯顯示標題和說明，請按照下列步驟操作：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」分頁標籤，請按一下該分頁標籤。
    3. 找出要編輯的 API，並按一下資料列。
    4. 按一下「「編輯」圖示」。
    5. 視需要編輯「顯示標題」和「顯示說明」欄位。
    6. 點按「儲存」。

    從入口網站中移除 API

    如何從入口網站中移除 API：

    1. 存取 API 目錄。
    2. 如果尚未選取「API」，請選取該選項。
    3. 將滑鼠遊標移到清單中的 API 上，即可顯示動作選單。
    4. 按一下「「編輯」圖示」。

    管理用於探索相關 API 的類別

    使用類別標記 API，可讓應用程式開發人員在線上入口網站的 API 頁面探索相關的 API。新增及管理類別 (如下節所述)。

    探索「類別」頁面

    如何查看「類別」頁面：

    1. 依序選取「Publish」(發布) >「Ports」(入口網站)，然後選取入口網站。
    2. 點選入口網站首頁的「API Catalog」。

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

    3. 按一下「類別」分頁標籤。

    API 目錄的「類別」分頁會顯示入口網站所定義的類別清單。

    「類別」分頁會顯示類別名稱，以及指派的 API 總數與總數

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

    新增類別

    透過下列其中一種方式新增類別：

    新類別將新增至「類別」頁面，並在新增或編輯其他 API 時出現。

    如要手動新增類別，請按照下列步驟操作：

    1. 存取「類別」頁面。
    2. 按一下 [+]。+
    3. 輸入新類別的名稱。
    4. 視需要選取一或多個 API 以標記類別。
    5. 點選「建立」。

    編輯類別

    如何編輯類別：

    1. 存取「類別」頁面。
    2. 按一下「」。
    3. 編輯類別名稱。
    4. 新增或移除 API 標記。
    5. 點按「儲存」。

    刪除類別

    如果您刪除某個類別，也會一併刪除該類別的所有 API 標記。

    如何刪除類別：

    1. 存取「類別」頁面。
    2. 將遊標移到您要編輯的類別上，即可顯示動作選單。
    3. 按一下「」。
    4. 編輯類別名稱。
    5. 新增或移除 API。
    6. 點按「儲存」。

    排解已發布 API 的相關問題

    下列各節提供資訊，協助您透過我們發布的 API 排解特定錯誤。

    錯誤：無法擷取使用這個 API 時傳回的錯誤

    使用這個 API 時，如果傳回 TypeError: Failed to fetch 錯誤，請考慮下列可能的原因和解決方法：

    • 如果是複合型內容錯誤，這個錯誤可能是已知的 Swagger-ui 問題所造成。其中一種可能的解決方法，是確保在 OpenAPI 文件的 schemes 定義中，將 HTTPS 指定為 HTTP。例如：

      schemes:
   - https
   - http

    • 如果是跨源資源共享 (CORS) 限制錯誤，請確認 API Proxy 支援 CORS。CORS 是一種標準機制，可以啟用用戶端跨來源要求。請參閱「設定 API Proxy 來支援試用這個 API」。

    錯誤：「Access-Control-Allow-Origin」標頭含有多個值「*, *」，但僅允許一個值

    使用「試用這個 API」時，如果 Access-Control-Allow-Origin 標頭已存在，您可能會收到以下錯誤訊息：

    The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

    如要修正這項錯誤，請將 AssignMessage 政策修改為使用 <Set> 設定 CORS 標頭，而不是 <Add>，如以下節錄所示。詳情請參閱相關社群文章。 

    <AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

    錯誤：不允許使用要求標頭欄位

    使用試用 API 時，如果您收到類似以下範例的 Request header field not allowed 錯誤，則可能需要更新 CORS 政策中支援的標頭。例如：

    Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

    在這個範例中，您必須將 content-type 標頭新增至 CORS AssignMessage 政策的 Access-Control-Allow-Headers 區段，如「將新增 CORS 政策附加至新的 API Proxy」一文所述。

    錯誤：使用 OAuth2 呼叫 API Proxy 時存取遭拒

    Apigee 的 OAuthV2 政策會傳回權杖回應，其中包含某些不符合 RFC 規定的屬性。舉例來說，這項政策會傳回值為 BearerToken 的權杖，而非預期的 RFC 值 Bearer。使用此 API 時，這項無效的 token_type 回應可能會導致 Access denied 錯誤。

    如要修正這個問題，您可以建立 JavaScript 或 AssignMessage 政策，將政策輸出內容轉換為符合規定的格式。詳情請參閱不符合 RFC 規定的行為。