在 WordPress 上自訂 API 管理開發人員入口網站

適用於：開發人員 | 基本 | 標準 | 進階

本文說明如何設定開放原始碼開發人員入口網站外掛程式 (預覽)，以便在 WordPress 上自訂 API 管理開發人員入口網站。 使用外掛程式，將任何 WordPress 網站轉換成開發人員入口網站。 利用 WordPress 中的網站功能，在開發人員入口網站中自訂和新增功能，包括當地語系化、可折疊和可展開的功能表、自訂樣式表、檔案下載等等。

在本文中，您會在 Azure App Service 上建立 WordPress 網站，並在 WordPress 網站上設定開發人員入口網站外掛程式。 已設定使用 Microsoft Entra ID 向 WordPress 網站和開發人員入口網站進行驗證。

必要條件

  • 建立 一個 API 管理實例。

    注意

    目前，API 管理 v2 層不支援外掛程式。

  • 啟用和發佈開發人員入口網站。 如需相關步驟，請參閱教學課程：存取及自訂開發人員入口網站。
  • 具備在與 Azure 訂用帳戶相關聯的 Microsoft Entra 租用戶中建立應用程式註冊的權限。
  • 開發人員入口網站 WordPress 外掛程式的安裝檔案，以及外掛程式存放庫中的自訂 WordPress 主題。 從存放庫中的 dist 資料夾下載下列 zip 檔案：
    • 插件檔案： apim-devportal.zip
    • 主題檔案： twentytwentyfour.zip

步驟 1：在 App Service 上建立 WordPress

在此案例中，您會建立裝載在 Azure App Service 上的受控 WordPress 網站。 以下是簡要步驟：

  1. 在 Azure 入口網站中，瀏覽至 https://portal.azure.com/#create/WordPress.WordPress。

  2. 在 [在 App Service 上建立 WordPress] 頁面上的 [基本] 索引標籤中，輸入您的專案詳細數據、Web 應用程式詳細數據和 WordPress 設定設定。

    將 WordPress 管理員使用者名稱和密碼儲存在安全的地方。 需要這些認證才能登入 WordPress 管理網站，並在稍後的步驟中安裝外掛程式。

    警告

    請避免使用預設的 WordPress admin 用戶名稱，並建立強密碼。 想了解更多，請參閱 WordPress 密碼最佳實務。

  3. 在增益集索引標籤上：

    1. 選取 [使用 Azure 通訊服務、Azure Front Door 和 Azure Blob 儲存體的電子郵件] 的建議預設值。
    2. 選擇或建立新的 AFD 設定檔。
    3. 在 [虛擬網路] 中，選取 [新增] 值或現有的虛擬網路。

  4. 在 [部署] 索引標籤上，將 [新增預備位置] 保留為未選取狀態。

  5. 選取 [檢閱 + 建立] 以執行最終驗證。

  6. 選取 [建立] 以完成應用程式服務部署。

應用程式服務可能需要幾分鐘的時間才能完成部署。

步驟 2：建立新的 Microsoft Entra 應用程式註冊

在此步驟中，建立新的 Microsoft Entra 應用程式。 在稍後的步驟中，您會將此應用程式設定為識別提供者，以便向您的應用程式服務和 API 管理執行個體中的開發人員入口網站進行驗證。

  1. 在 Azure 入口網站，進入 應用程式註冊，然後選擇 + 新註冊。

  2. 提供新的應用程式名稱，然後在 支援帳號類型中選擇 「僅單一租戶」。 選取註冊。

  3. 在 [概觀] 頁面上，複製 [應用程式 (用戶端) 識別碼] 和 [目錄 (租用戶) 識別碼] 並儲存在安全的地方。您在後續步驟中會需要使用這些值來設定驗證，以便向 API 管理執行個體和應用程式服務進行驗證。 入口網站應用程式註冊概覽頁面的截圖。

  4. 在側邊欄選單中 ，管理選項中，選擇 「認證>+新增平台」。 如果你沒看到這個設定，請選擇切換到舊體驗的選項。

  5. 在 [設定平台] 頁面中，選取 [Web]。

  6. 在 [設定 Web] 頁面上，輸入下列重新導向 URI 並替換您的應用程式服務名稱，然後選取 [設定]：

    https://app-service-name>.azurewebsites.net/.auth/login/aad/callback

  7. 再次選取 [+ 新增平台]。 選擇單頁應用程式。

  8. 在 [設定單頁應用程式] 頁面上，輸入下列重新導向 URI 並替換您的 API 管理執行個體名稱，然後選取 [設定]：

    https://<apim-instance-name>.developer.azure-api.net/signin

  9. 再次選取 [+ 新增平台]。 再次選取 [單頁應用程式 ]。

  10. 在 [設定單頁應用程式] 頁面上，輸入下列重新導向 URI 並替換您的 API 管理執行個體名稱，然後選取 [設定]：

    https://<management-instance-name>.developer.azure-api.net/

  11. 在側邊欄功能表的 [管理] 底下，選取 [權杖設定>] + [新增選擇性宣告]。

  12. 在 新增可選申請 頁面，選擇 「身分證」，然後選擇以下申請： 電子郵件、family_name、given_name、onprem_sid、preferred_username、UPN。 選取 [新增]。

  13. 出現提示時，請選取 [開啟 Microsoft Graph 電子郵件、設定檔權限]。 選取 [新增]。

  14. 在側邊欄選單中的管理下，選擇API 權限，並確認下列 Microsoft Graph 權限是否存在：電子郵件、個人檔案、User.Read。

    此螢幕擷取畫面顯示入口網站中的 API 權限。

  15. 在側邊欄選單中 ，管理選項中選擇 憑證與秘密+>新客戶端秘密。

  16. 設定密鑰並選擇 [新增]。 密碼產生後，立即複製密碼的值並存放在安全的地方。 您在後續步驟中會需要使用這個值，以便在新增應用程式至 API 管理執行個體和應用程式服務時進行驗證。

  17. 在側邊欄選單中，在 管理選項中選擇 Expose an API。 請記下預設的 [應用程式識別碼 URI]。 如果需要，也可以選擇新增自訂瞄準鏡。

步驟 3：啟用對應用程式服務進行驗證

在此步驟中，新增 Microsoft Entra 應用程式註冊作為識別提供者，以便向 WordPress 應用程式服務進行驗證。

  1. 在入口網站中，瀏覽至 WordPress 應用程式服務。

  2. 在側邊欄選單中，在設定中選擇「驗證>」「新增身份提供者」。

  3. 在 [基本] 索引標籤的 [識別提供者] 中，選取 [Microsoft]。

  4. 在 [應用程式註冊] 下方，選取 [提供現有應用程式註冊的詳細資料]。

    1. 依據您在上一步驟中建立的應用程式註冊資訊，輸入 [應用程式 (用戶端) 識別碼] 和 [用戶端密碼]。
    2. 在 [簽發者 URL] 中，輸入驗證端點的下列其中一個值：https://login.microsoftonline.com/<tenant-id> 或 https://sts.windows.net/<tenantid>。 將 <tenant-id> 替換為應用程式註冊中的 目錄 (租戶) 識別碼。

      重要

      不要針對簽發者 URL 使用 2.0 版端點 (以 /v2.0 結尾的 URL)。

  5. 在[c0] 允許的權杖受眾[/c0] 中，輸入應用程式註冊中的 [c1] 應用程式識別碼 URI[/c1]。 範例：api://<app-id>。

  6. 在 [其他檢查] 下方，選取適合您環境的值或使用預設值。

  7. 針對其餘設定設定您想要的值，或使用預設值。 選取 [新增]。

    注意

    如果你想讓訪客用戶和已登入的使用者在 WordPress 上存取開發者入口網站，可以啟用未經認證的存取權限。 在 [限制存取] 中，選取 [允許未經驗證的存取]。 欲了解更多，請參閱 授權行為。

身分提供者已新增至應用服務。

步驟 4：啟用 API 管理開發人員入口網站驗證

將相同的 Microsoft Entra 應用程式註冊設定為 API 管理開發人員入口網站的識別身分提供者。

  1. 在入口網站中，瀏覽至您的 API 管理執行個體。

  2. 在側邊欄功能表的 [開發人員入口網站] 底下，選取 [身分識別>+ 新增]。

  3. 在 新增身份提供者 頁面，選擇 Microsoft Entra ID。

  4. 依據您在上一步驟中建立的應用程式註冊資訊，輸入用戶端 ID、用戶端密鑰 和登入租戶 的值。 登入租用戶是應用程式註冊中的目錄 (租用戶) 識別碼。

  5. 在 [用戶端程式庫] 中，選取 [MSAL]。

  6. 接受其餘設定的預設值，然後選取 [新增]。

  7. 重新發佈開發人員入口網站以套用變更。

  8. 若要測試驗證，請在下列 URL 登入開發人員入口網站並替換您的 API 管理執行個體名稱：https://<management-instance-name>.developer.azure-api.net/signin。 請選擇底部的 Microsoft Entra ID 按鈕登入。

    當你第一次打開它時，可能會被要求同意特定的權限。

步驟 5：在 API 管理中設定開發人員入口網站設定

在 API 管理執行個體中更新開發人員入口網站的設定，以啟用 CORS 並納入應用程式服務網站作為入口網站原點。

  1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。

  2. 在側邊欄選單中，在 開發者入口網站下方，選擇 入口網站概覽。

  3. 在 [入口網站概觀] 索引標籤上，選取 [啟用 CORS]。

  4. 在側邊欄功能表的 [開發人員入口網站] 底下，選取 [入口網站設定]。

  5. 在 [自主代管入口網站設定] 索引標籤上，輸入 App Service 網站上的 WordPress 主機名稱做為入口網站原點，並在下列 URL 中替換您的應用程式名稱：https://<yourapp-service-name>.azurewebsites.net

  6. 重新發佈開發人員入口網站以套用變更。

另請更新 API 管理執行個體中的 cors 原則設定，以新增應用程式服務網站作為允許的原點。 需要此值以允許從開發人員入口網站的測試主控台在 WordPress 網站上發出呼叫。

在您的 origin 原則設定中新增下列 cors 值：

<cors ...>
    <allowed-origins>
        [...]
        <origin>https://<yourapp-service-name>.azurewebsites.net</origin>
    </allowed-origins>
</cors>

深入了解如何設定或編輯原則。

步驟 6：瀏覽至 WordPress 管理網站並上傳自訂主題

在此步驟中，您會將 API 管理開發人員入口網站的自訂主題上傳至 WordPress 管理網站。

重要

建議您上傳外掛程式存放庫提供的主題。 該主題基於 Twenty Twenty Four 主題，並自訂以支援 WordPress 開發者入口的功能。 如果你選擇使用其他主題，某些功能可能無法如預期運作，或需要額外自訂。

  1. 在下列 URL 開啟 WordPress 管理網站，並替換您的應用程式服務名稱：http://<app-service-name>.azurewebsites.net/wp-admin

    當你第一次打開它時，可能會被要求同意特定的權限。

  2. 使用您在 App Service 上建立 WordPress 時輸入的使用者名稱和密碼來登入 WordPress 管理網站。

  3. 在側邊欄選單中，選擇 外觀>主題 ，然後 新增主題。

  4. 選取 [上傳主題]。 選取選擇檔案，以便上傳您先前下載的 API 管理開發人員入口網站主題 zip 檔案。 選取 [立即安裝]。

  5. 在下一個畫面中，選取以已上傳內容取代目前使用中內容。

  6. 如果出現提示，請選取 [啟用]。

注意

如果您的 WordPress 網站包含快取外掛程式，請在啟用主題之後清除快取以確保變更生效。

步驟 7：安裝開發人員入口網站外掛程式

  1. 在 WordPress 管理網站的側邊欄選單中，選擇 「插件」>「新增」 新增插件。

  2. 選取 [上傳外掛程式]。 選取選擇檔案，以便上傳您先前下載的 API 管理開發人員入口網站外掛程式 zip 檔案 (apim-devportal.zip)。 選取 [立即安裝]。

  3. 安裝成功之後，請選取 [啟用外掛程式]。

  4. 在側邊欄選單中，選擇 Azure API 管理開發者入口網站。

  5. 在 APIM 設定 頁面，輸入以下設定並選擇 「儲存變更」：

    • APIM 服務名稱 - API 管理執行個體的名稱
    • 啟用 [建立預設頁面] 和 [建立導覽功能表]

步驟 8：新增自訂樣式表

新增 API 管理開發人員入口網站的自訂樣式表。

  1. 在 WordPress 管理網站的側邊欄選單中，選擇 外觀>主題。

  2. 選取 [自訂]，然後瀏覽至 [樣式]。

  3. 選取鉛筆圖示 ([編輯樣式])。

  4. 在 [樣式] 窗格中，選取 [其他] (三個點) > [其他 CSS]。

  5. 在 [其他 CSS] 中，輸入下列 CSS：

    .apim-table {
  width: 100%;
  border: 1px solid #D1D1D1;
  border-radius: 4px;
  border-spacing: 0;
}

.apim-table th {
  background: #E6E6E6;
  font-weight: bold;
  text-align: left;
}

.apim-table th,
.apim-table td {
  padding: .7em 1em;
}

.apim-table td {
  border-top: #E6E6E6 solid 1px;
}

.apim-input,
.apim-button,
.apim-nav-link-btn {
    border-radius: .33rem;
    padding: 0.6rem 1rem;
}

.apim-button,
.apim-nav-link-btn {
    background-color: var(--wp--preset--color--contrast);
    border-color: var(--wp--preset--color--contrast);
    border-width: 0;
    color: var(--wp--preset--color--base);
    font-size: var(--wp--preset--font-size--small);
    font-weight: 500;
    text-decoration: none;
    cursor: pointer;
    transition: all .25s ease;
}

.apim-nav-link-btn:hover {
    background: var(--wp--preset--color--base);
    color: var(--wp--preset--color--contrast);
}

.apim-button:hover {
    background: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-button:disabled {
    background: var(--wp--preset--color--contrast-2);
    cursor: not-allowed;
}

.apim-label {
    display: block;
    margin-bottom: 0.5rem;
}

.apim-input {
    border: solid 1px var(--wp--preset--color--contrast);
}

.apim-grid {
    display: grid;
    grid-template-columns: 11em max-content;
}

.apim-link,
.apim-nav-link {
    text-align: inherit;
    font-size: inherit;
    padding: 0;
    background: none;
    border: none;
    font-weight: inherit;
    cursor: pointer;
    text-decoration: none;
    color: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-nav-link {
    font-weight: 500;
}

.apim-link:hover,
.apim-nav-link:hover {
    text-decoration: underline;
}

#apim-signIn {
    display: flex;
    align-items: center;
    gap: 24px;
}

  6. 儲存變更。 再次選取 [儲存]，儲存主題的變更。

  7. 登出 WordPress 管理後台。

步驟 9：登入部署在 WordPress 上的 API 管理開發人員入口網站

存取 WordPress 網站，以查看部署在 WordPress 上並裝載於 App Service 的新 API 管理開發人員入口網站。

  1. 在新的瀏覽器視窗中，瀏覽至您的 WordPress 網站，並在下列 URL 中替換您的應用程式服務名稱：https://<yourapp-service-name>.azurewebsites.net。

  2. 出現提示時，請使用開發人員帳戶的 Microsoft Entra ID 認證登入。 如果已啟用開發人員入口網站的未驗證存取，請在開發人員入口網站的首頁上選取 [登入]。

注意

您只能使用 Microsoft Entra ID 認證登入 WordPress 上的開發人員入口網站。 不支援基本驗證。

您現在可以使用 API 管理開發人員入口網站的下列功能：

  • 登入入口網站
  • 請參閱 API 清單
  • 瀏覽至 API 詳細資料頁面，並查看作業清單
  • 使用有效的 API 金鑰測試 API
  • 請參閱產品清單
  • 訂閱產品並產生訂用帳戶金鑰
  • 瀏覽至顯示帳戶和訂閱詳情的 個人資料 索引標籤
  • 登出入口網站

下列螢幕擷取畫面顯示裝載在 WordPress 上的 API 管理開發人員入口網站範例頁面。

此螢幕擷取畫面顯示裝載在 WordPress 上的開發人員入口網站。

疑難排解

我在 WordPress 網站上看不到最新的開發人員入口網站頁面

如果您在瀏覽 WordPress 網站時看不到最新的開發人員入口網站頁面，請檢查是否已在 WordPress 管理網站中安裝、啟用和設定開發人員入口網站外掛程式。 步驟請參見 安裝開發者入口外掛。

您可能也需要清除 WordPress 網站或 Azure Front Door 中的快取 （如果已設定）。 或者，您也可能需要清除瀏覽器上的快取。

我在登入或登出開發人員入口網站時發生問題

如果您在登入或登出開發人員入口網站時發生問題，請清除瀏覽器快取，或在個別的瀏覽器工作階段中檢視開發人員入口網站 (使用 Incognito 或私人瀏覽模式)。

我在開發人員入口網站導覽列上看不到登入按鈕

如果你使用的自訂主題與插件倉庫提供的不一樣，可能需要手動在導航列新增登入功能。 在首頁上，新增下列簡短代碼區塊：[SignInButton]。 欲了解更多，請參閱 WordPress 文件。

您也可以在瀏覽器中輸入下列 URL，手動登入或登出：

  • 登入：https://<app-service-name>.azurewebsites.net/.auth/login/aad
  • 登出：https://<app-service-name>.azurewebsites.net/.auth/logout

相關內容

  • Last updated on