迁移到新开发人员门户Migrate to the new developer portal

本文介绍从已弃用的旧门户迁移到 API 管理中的新开发人员门户所需的步骤。This article describes the steps you need to take to migrate from the deprecated legacy portal to the new developer portal in API Management.

重要

旧开发人员门户现在已弃用,并且将仅接收安全更新。The legacy developer portal is now deprecated and it will receive security updates only. 你可以像往常一样继续使用它,直到它在 2023 年 10 月停用,届时将从所有 API 管理服务中将其删除。You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services.

API 管理开发人员门户

可用性Availability

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

新开发人员门户中的改进Improvements in new developer portal

新的开发人员门户解决了已弃用门户的许多限制。The new developer portal addresses many limitations of the deprecated portal. 它具有用于编辑内容的可视化拖放编辑器和设计人员用于设置网站样式的专用面板。It features a visual drag-and-drop editor for editing content and a dedicated panel for designers to style the website. 页面、自定义和配置将保存为 API 管理服务中的 Azure 资源管理器资源,这样你便能够自动执行门户部署Pages, customizations, and configuration are saved as Azure Resource Manager resources in your API Management service, which lets you automate portal deployments. 最后,门户的代码库是开源的,因此你可以使用自定义功能对其进行扩展Lastly, the portal's codebase is open-source, so you can extend it with custom functionality.

如何迁移到新的开发人员门户How to migrate to new developer portal

新的开发人员门户与已弃用门户不兼容,因此无法自动迁移。The new developer portal is incompatible with the deprecated portal and automated migration isn't possible. 需要手动重新创建内容(页面、文本、媒体文件)并自定义新门户的外观。You need to manually recreate the content (pages, text, media files) and customize the look of the new portal. 具体步骤将因门户的自定义内容和复杂性而异。Precise steps will vary depending on the customizations and complexity of your portal. 有关指南,请参阅开发人员门户教程Refer to the developer portal tutorial for guidance. 其余的配置(如 API、产品、用户、标识提供程序)将在两个门户之间自动共享。Remaining configuration, like the list of APIs, products, users, identity providers, is automatically shared across both portals.

重要

如果之前已启动新的开发人员门户,但尚未进行任何更改,请重置默认内容,将其更新到最新版本。If you've launched the new developer portal before, but you haven't made any changes, reset the default content to update it to the latest version.

从已弃用的门户迁移时,请记住以下更改:When you migrate from the deprecated portal, keep in mind the following changes:

  • 如果通过自定义域公开开发人员门户,请向新的开发人员门户分配域If you expose your developer portal via a custom domain, assign a domain to the new developer portal. 使用 Azure 门户中下拉列表中的“开发人员门户”选项。Use the Developer portal option from the dropdown in the Azure portal.

  • 在 API 上应用 CORS 策略,以启用交互式测试控制台。Apply a CORS policy on your APIs to enable the interactive test console.

  • 如果注入自定义 CSS 来设置门户样式,需要使用内置设计面板复制样式If you inject custom CSS to style the portal, you need to replicate the styling using the built-in design panel. 新门户中不允许使用 CSS 注入。CSS injection isn't allowed in the new portal.

  • 只能在新门户的自托管版本中注入自定义 JavaScript。You can inject custom JavaScript only in the self-hosted version of the new portal.

  • 如果你的 API 管理位于虚拟网络中,并且通过应用程序网关向 Internet 公开,请参阅本文档文章,了解具体的配置步骤。If your API Management is in a virtual network and is exposed to the Internet via Application Gateway, refer to this documentation article for precise configuration steps. 你需要:You need to:

    • 启用与 API 管理的管理终结点的连接。Enable connectivity to the API Management's management endpoint.
    • 启用与新门户终结点的连接。Enable connectivity to the new portal endpoint.
    • 禁用所选的 Web 应用程序防火墙规则。Disable selected Web Application Firewall rules.
  • 如果将默认电子邮件通知模板更改为包含显式定义的弃用门户 URL,请将它们更改为使用门户 URL 参数或指向新的门户 URL。If you changed the default e-mail notification templates to include an explicitly defined deprecated portal URL, change them to either use the portal URL parameter or point to the new portal URL. 如果模板改用内置门户 URL 参数,则不需要进行任何更改。If the templates use the built-in portal URL parameter instead, no changes are required.

  • 新开发人员门户不支持“问题”和“应用程序” 。Issues and Applications aren't supported in the new developer portal.

  • 新开发者门户不支持以标识提供者身份与 Facebook、Microsoft、Twitter 和 Google 直接集成。Direct integration with Facebook, Microsoft, Twitter, and Google as identity providers isn't supported in the new developer portal. 可以通过 Azure AD B2C 与这些提供商集成。You can integrate with those providers via Azure AD B2C.

  • 如果使用委派,请更改应用程序中的返回 URL,并使用“获取共享访问令牌”API 终结点而不是“生成 SSO URL”终结点 。If you use delegation, change the return URL in your applications and use the Get Shared Access Token API endpoint instead of the Generate SSO URL endpoint.

  • 如果你使用 Azure AD 作为标识提供者:If you use Azure AD as an identity provider:

    • 更改应用程序中的返回 URL,使其指向新的开发人员门户域。Change the return URL in your application to point to the new developer portal domain.
    • 将应用程序中返回 URL 的后缀从 /signin-aad 修改为 /signinModify the suffix of the return URL in your application from /signin-aad to /signin.
  • 如果你使用 Azure AD B2C 作为标识提供者:If you use Azure AD B2C as an identity provider:

    • 更改应用程序中的返回 URL,使其指向新的开发人员门户域。Change the return URL in your application to point to the new developer portal domain.
    • 将应用程序中返回 URL 的后缀从 /signin-aad 修改为 /signinModify the suffix of the return URL in your application from /signin-aad to /signin.
    • 在应用程序声明中包含“名”、“姓”和“用户的对象 ID” 。Include Given Name, Surname, and User's Object ID in the application claims.
  • 如果在交互式测试控制台中使用 OAuth 2.0,请更改应用程序中的返回 URL,使其指向新的开发人员门户域并修改后缀:If you use OAuth 2.0 in the interactive test console, change the return URL in your application to point to the new developer portal domain and modify the suffix:

    • 对于授权代码授予流,从 /docs/services/[serverName]/console/oauth2/authorizationcode/callback 更改为 /signin-oauth/code/callback/[serverName]From /docs/services/[serverName]/console/oauth2/authorizationcode/callback to /signin-oauth/code/callback/[serverName] for the authorization code grant flow.
    • 对于隐式授权流,从 /docs/services/[serverName]/console/oauth2/implicit/callback 更改为 /signin-oauth/implicit/callbackFrom /docs/services/[serverName]/console/oauth2/implicit/callback to /signin-oauth/implicit/callback for the implicit grant flow.
  • 如果在交互式测试控制台中使用 OpenID Connect,请更改应用程序中的返回 URL,使其指向新的开发人员门户域并修改后缀:If you use OpenID Connect in the interactive test console, change the return URL in your application to point to the new developer portal domain and modify the suffix:

    • 对于授权代码授予流,从 /docs/services/[serverName]/console/openidconnect/authorizationcode/callback 更改为 /signin-oauth/code/callback/[serverName]From /docs/services/[serverName]/console/openidconnect/authorizationcode/callback to /signin-oauth/code/callback/[serverName] for the authorization code grant flow.
    • 对于隐式授权流,从 /docs/services/[serverName]/console/openidconnect/implicit/callback 更改为 /signin-oauth/implicit/callbackFrom /docs/services/[serverName]/console/openidconnect/implicit/callback to /signin-oauth/implicit/callback for the implicit grant flow.

后续步骤Next steps

详细了解开发人员门户:Learn more about the developer portal: