API 管理開發人員入口網站 - 常見問題

發行項
04/13/2024

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

若入口網站中不支援我所需要的功能，該怎麼辦？

下列選項可供您選擇：

針對小型自訂，請使用內建小工具來新增自訂 HTML。目前，API 管理 v2 層不提供自訂 HTML 程式代碼小工具。
針對較大型自訂，請建立和上傳自訂小工具至受控開發人員入口網站。目前，API 管理 v2 層不提供自定義小工具。
只有在您需要修改開發人員入口網站程式碼基底的核心時，才能自我裝載開發人員入口網站。
開啟 GitHub 存放庫中的功能要求。

深入了解如何自訂和擴充開發人員入口網站的功能。

一項 API 管理服務是否可有多個開發人員入口網站？

您可有一個受控入口網站和多個自我裝載入口網站。所有入口網站的內容都會儲存在相同的 API 管理服務中，因此它們會相同。若要區分入口網站的外觀和功能，您可使用自訂小工具進行自我裝載，在執行階段以動態方式自訂頁面 (例如根據 URL)。

入口網站是否支援 Azure Resource Manager 範本，且/或是否與 API 管理 DevOps 資源套件相容？

否。

入口網站內容是否與備份/還原功能一併儲存於 API 管理？

否。

我是否必須啟用額外的 VNet 連線能力，以符合受控入口網站相依性？

在大部分情況下 - 否。

若 API 管理服務位於內部 VNet，則開發人員入口網站僅可在該網路內存取。在存取入口網站系統管理介面所用的電腦上，管理端點的主機名稱必須解析為服務的內部 VIP。請確定管理端點已在 DNS 中註冊。如果設定錯誤，您會看到錯誤： Unable to start the portal. See if settings are specified correctly in the configuration (...)。

若 API 管理服務位於內部 VNet，且透過網際網路應用程式閘道存取，請務必啟用與開發人員入口網站的連線，以及 API 管理的管理端點連線。您可能必須停用 Web 應用程式防火牆規則。如需詳細資訊，請參閱此文章。

我已指派自訂 API 管理網域，但發佈的入口網站無法運作

更新網域後，您必須重新發佈入口網站，變更才會生效。

我已新增識別提供者，但未顯示於入口網站

設定識別提供者之後（例如 Azure AD、Azure AD B2C），您必須重新發佈入口網站，變更才會生效。請確定您的開發人員入口網站頁面包含 OAuth 按鈕小工具。

入口網站未使用我設定的委派

設定委派後，您必須重新發佈入口網站，變更才會生效。

開發人員入口網站中尚未傳播 API 管理組態的其他變更

大部分的組態變更 (如 VNet、登入、產品條款) 必須重新發佈入口網站。

使用互動式主控台時發生 CORS 錯誤

互動式主控台會由瀏覽器提出用戶端 API 要求。在 API 上新增 CORS 原則，或設定入口網站以使用 CORS Proxy 來解決 CORS 問題。如需詳細資訊，請參閱在 API 管理開發人員入口網站中啟用互動式控制台的CORS。

在環境中使用自定義 HTML 程式代碼小工具時，您可能會在與小工具載入的 IFrame 互動時看到 CORS 錯誤。之所以發生此問題，是因為 IFrame 會從與開發人員入口網站不同的來源提供內容。若要避免此問題，您可以改用自定義小工具。

編輯開發人員入口網站需要哪些權限？

若在系統管理模式中開啟入口網站時發生 Oops. Something went wrong. Please try again later. 錯誤，則可能缺少必要權限 (Azure RBAC)。

入口網站需要範圍 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1 的使用權限 Microsoft.ApiManagement/service/users/token/action。

您可使用下列 PowerShell 指令碼來建立具有必要權限的角色。請記得變更 <subscription-id> 參數。

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole

建立角色後，即可從 Azure 入口網站的存取控制 (IAM) 區段授與任何使用者。若將此角色指派給使用者，則會指派服務範圍的權限。使用者將可代表服務中的任何使用者產生 SAS 權杖。此角色至少須指派給服務的管理員。下列 PowerShell 命令示範如何在最低範圍內將角色指派給使用者 user1，以免將不必要的權限授與使用者：

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1"

將權限授與使用者後，使用者必須登出，並再次登入 Azure 入口網站，新權限才會生效。

我看到 `Unable to start the portal. See if settings are specified correctly (...)` 錯誤

GET 呼叫 https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview 失敗時會顯示此錯誤。入口網站的系統管理介面會透過瀏覽器發出呼叫。

若 API 管理服務位於 VNet，請參閱 VNet 連線能力問題。

呼叫失敗也可能由指派給自定義網域且瀏覽器不信任的 TLS/SSL 憑證所造成。您可移除管理端點自訂網域，作為因應措施。 API 管理將會回復為具有受信任憑證的預設端點。

入口網站的瀏覽器支援？

瀏覽器	支援
Apple Safari	是¹
Google Chrome	是¹
Microsoft Edge	是¹
Microsoft Internet Explorer	No
Mozilla Firefox	是¹

¹ 支援兩個最新的實際執行版本。

自我裝載入口網站的本機開發已不再運作

如果您的本機版本開發人員入口網站無法從記憶體帳戶或 API 管理實例儲存或擷取資訊，則 SAS 令牌可能已過期。您可產生新權杖以修正此問題。如需指示，請參閱教學課程自我裝載開發人員入口網站。

若開發人員入口網站無須預設啟用註冊功能，您可透過下列步驟停用：

在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
在功能表中的 [開發人員入口網站] 下，選取 [身分識別]。
刪除清單所顯示的每個識別提供者。選取各提供者，選取捷徑功能表 (...)，並選取 [刪除]。
瀏覽至開發人員入口網站管理員介面。
移除入口網站內容中的註冊連結和瀏覽項目。如需自訂入口網站內容的相關資訊，請參閱教學課程：存取和自訂開發人員入口網站。
修改 [註冊] 頁面內容，移除輸入身分識別資料所用的欄位，以免使用者直接瀏覽。

您也可選擇刪除 [註冊] 頁面。目前，您可使用 contentItem REST API 來列出和刪除此頁面。
儲存變更，並重新發佈入口網站。

如何移除 API 管理服務所佈建的開發人員入口網站內容？

在開發人員入口網站 GitHub 存放庫的 scripts.v3/cleanup.bat 指令碼中提供必要參數，並執行該指令碼

cd scripts.v3
.\cleanup.bat
cd ..

自我裝載的開發人員入口網站如何啟用單一登入 (SSO) 驗證？

除了其他驗證方法以外，開發人員入口網站也支援單一登入 (SSO)。若要使用此方法進行驗證，您必須使用下列查詢參數中的權杖來呼叫 /signin-sso：

https://contoso.com/signin-sso?token=[user-specific token]

產生使用者權杖

您可使用 API 管理 REST API 的取得共用存取權杖作業，以產生使用者特定權杖 (含管理員權杖)。

注意

權杖須為 URL 編碼。

深入了解開發人員入口網站：

瀏覽其他資源：

使用原始程式碼 GitHub 存放庫

共用方式為

API 管理開發人員入口網站 - 常見問題

若入口網站中不支援我所需要的功能，該怎麼辦？

一項 API 管理服務是否可有多個開發人員入口網站？

入口網站是否支援 Azure Resource Manager 範本，且/或是否與 API 管理 DevOps 資源套件相容？

入口網站內容是否與備份/還原功能一併儲存於 API 管理？

我是否必須啟用額外的 VNet 連線能力，以符合受控入口網站相依性？

我已指派自訂 API 管理網域，但發佈的入口網站無法運作

我已新增識別提供者，但未顯示於入口網站

入口網站未使用我設定的委派

開發人員入口網站中尚未傳播 API 管理組態的其他變更

使用互動式主控台時發生 CORS 錯誤

我在使用自定義 HTML 程式代碼小工具時收到 CORS 錯誤

編輯開發人員入口網站需要哪些權限？

我看到 `Unable to start the portal. See if settings are specified correctly (...)` 錯誤

入口網站的瀏覽器支援？

自我裝載入口網站的本機開發已不再運作

如何移除 API 管理服務所佈建的開發人員入口網站內容？

自我裝載的開發人員入口網站如何啟用單一登入 (SSO) 驗證？

產生使用者權杖

意見反應

其他資源

共用方式為

API 管理開發人員入口網站 - 常見問題

若入口網站中不支援我所需要的功能，該怎麼辦？

一項 API 管理服務是否可有多個開發人員入口網站？

入口網站是否支援 Azure Resource Manager 範本，且/或是否與 API 管理 DevOps 資源套件相容？

入口網站內容是否與備份/還原功能一併儲存於 API 管理？

我是否必須啟用額外的 VNet 連線能力，以符合受控入口網站相依性？

我已指派自訂 API 管理網域，但發佈的入口網站無法運作

我已新增識別提供者，但未顯示於入口網站

入口網站未使用我設定的委派

開發人員入口網站中尚未傳播 API 管理組態的其他變更

使用互動式主控台時發生 CORS 錯誤

我在使用自定義 HTML 程式代碼小工具時收到 CORS 錯誤

編輯開發人員入口網站需要哪些權限？

我看到 Unable to start the portal. See if settings are specified correctly (...) 錯誤

入口網站的瀏覽器支援？

自我裝載入口網站的本機開發已不再運作

如何在開發人員入口網站中停用註冊？

如何移除 API 管理服務所佈建的開發人員入口網站內容？

自我裝載的開發人員入口網站如何啟用單一登入 (SSO) 驗證？

產生使用者權杖

相關內容

意見反應

其他資源

我看到 `Unable to start the portal. See if settings are specified correctly (...)` 錯誤