發布 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 頁面，其中顯示兩種類別及使用圖片

    • SmartDocs (OpenAPI)

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

    開發人員可以查看您的 SmartDocs API 參考說明文件，然後點選「試用這個 API」面板提出 API 要求並查看輸出結果。請依據 OpenAPI 文件中定義的安全方法，試用這個 API 與不安全的端點或採用基本、API 金鑰或 OAuth 驗證的安全端點搭配使用。系統支援下列 OAuth 流程：授權碼、密碼和用戶端憑證。

    API 參考資料說明文件頁面，當中的摘要說明如何授權 API 呼叫、復原「試用這個 API」面板、下載相關規格，以及執行 API。

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

    已展開「試用這個 API」面板

    GraphQL Explorer

    使用 GraphQL 結構定義發布 API 時，GraphQL Explorer 會新增至入口網站。GraphQL Explorer 是可以對 API 執行查詢的互動式遊樂場。探索工具是以 GraphiQL 為基礎，這是由 GraphQL 基金會開發的 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 輸入回呼網址，如「註冊應用程式」中所述。

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

    使用 OpenAPI 文件發布 API 前，您必須先在 SmartDocs API 參考說明文件的「試用這個 API」面板中設定 API Proxy 來支援發出要求，如下所示：

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

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

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

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

    驗證存取權 政策設定需求
    無或 API 金鑰 為 API Proxy 新增 CORS 支援。為了方便起見，請使用 GitHub 提供的範例 CORS 解決方案，或按照「為 API Proxy 新增 CORS 支援」一文的步驟操作。
    基本驗證 請執行下列步驟：
    1. 為 API Proxy 新增 CORS 支援。為了方便起見，請使用 GitHub 提供的範例 CORS 解決方案，或按照「為 API Proxy 新增 CORS 支援」一文的步驟操作。
    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 解決方案，或按照「為 API Proxy 新增 CORS 支援」一文的步驟操作。
    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. 依序選取 [發布] > [入口網站]，然後選取您的入口網站。
    2. 按一下入口網站首頁的「API 目錄」。
    您也可以在頂端導覽列的入口網站下拉式選單中選取「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 文件」。
      2. 按一下「選取文件」。
      3. 執行下列任一步驟：
        • 按一下「My Specs」分頁標籤，然後從規格商店中選取規格。
        • 按一下「上傳檔案」分頁標籤，然後上傳檔案。
        • 按一下「從網址匯入」分頁標籤，然後從網址匯入規格。
      4. 按一下「選取」。

      如何使用 GraphQL 結構定義：

      1. 選取「GraphQL Schema」。
      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 文件的快照，請按一下「重新整理快照」。
      • 如要變更用於產生 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即可移除。

    6. 按一下「儲存」。

    使用類別標記 API

    透過下列其中一種方式使用類別標記 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. 依序選取 [發布] > [入口網站]，然後選取您的入口網站。
    2. 按一下入口網站首頁的「API 目錄」。

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

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

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

    「類別」分頁，顯示類別名稱、已指派的 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 再指定 HTTPS。例如：

      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

    在本範例中，請按照將新增 CORS 政策附加至新的 API Proxy 一節所述，將 content-type 標頭新增至 CORS AssignMessage 政策的 Access-Control-Allow-Headers 區段中。

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

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

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