创建开发者门户

开发者门户由几个元素组成：

这是开发人员门户系统查看最重要的部分。content 部分显示站点结构和层次结构，并在同一个页面中提供编辑功能。这意味着您可以管理站点结构、页面和其他存储在它的资产。门户的层次结构以目录树的形式显示。

上面的镜像显示了 content 部分中其中一个页面的示例视图。如上所示，它会显示所有文件（页面、镜像、样式表、JavaScript 等）保留站点的路径层次结构。如以前一样，部分的功能与目录完全相同。

在右侧，您可以看到编辑页面视图。您可以在此处看到页面名称（它还代表了它是标准还是内置页面）以及将新元素添加到内容的按钮（页面、布局、部分、文件或 portlet）。下面，您可以选择页面将使用的布局，并切换 liquid 标签功能。以下部分是文本编辑器，它支持代码突出显示、tabulations、line numeration 等。选项卡按钮在编辑文档的草案和发布版本之间 Draft 和 Published 开关。以下两个图标列出了文档的版本，并分别打开一个弹出窗口。

要编辑页面内容，只需选择所需的布局，设置几个附加选项，如内容类型和 URL 路径，然后在 HTML、Markdown 或 Textile 中输入代码。

此视图中的另一个重要功能是 Preview 按钮。您可以选择是否预览页面发布的或草案版本。点按钮将您重定向到 Developer Portal 模式，您可以在其中看到页面的实时（或草案）呈现版本，其中右侧有一个灰色的垂直栏。此栏包含开发人员门户的页面、布局和部分编辑视图的链接。它允许您在草案和公布的视图之间切换。

还有一个过滤器功能，它不仅充当搜索字段，但允许您将显示的元素限制为仅样式表、JavaScript 或指定的任何其他类型。

布局和部分部分管理模板和页面的可重复使用的部分。它们的功能与 content 部分的功能类似。

layout 部分由页面使用的模板定义组成。Layout 是页面的主要结构，此模板的内容将呈现在每个使用它的页面中。部分、portlet 和页面的实际内容驻留在模板中。

部分是代码的可重复使用的部分，可应用于不同页面上的多个位置。例如，在每个布局上，页脚都相同，在具有不同布局的几个页面中，侧边栏是相同的。

要在布局、部分、电子邮件模板或 portlet 中包含部分，请使用以下命令：

{% include "partial_name" %}

与门户的其他部分一样，布局和部分也具有草案和发布状态，并提供完整的版本历史记录，具有以下功能：

有关 liquid 标签的完整指南，请查看 Liquid 参考指南。

内容的最后小节是 portlets。它们为您提供了一些高级功能，而无需任何高级编码。我们的开发人员门户提供三个不同的 portlet：

在创建所需的 portlet 时，您必须在设置页面中输入请求的数据，如标题、系统名称和外部 RSS 源 portlet 的 URL 源。

开发人员门户的最后元素是 redirect 和 changes 部分。它们比 content 部分要少，但仍然很重要，并提供一些自定义功能。

重定向可帮助您从一个门户 URL 重定向到另一个门户 URL 的帮助。例如，当弃用旧页面且不想更改所有链接时，这非常有用。重定向不能用于内置开发人员门户页面 - 它们仅用于您创建的页面。

最后，但不是更改部分。它包含所有新编辑和未发布的页面的列表，并为您提供一次单独发布或全部发布页面的选择。

要删除批准，请转到 Audience > Accounts > Usage Rules 的 Signup 部分，确保选中 Developers 选项。

另外，如果您启用了帐户和服务计划，请向下滚动页面并确保两个情况下都 直接启用更改计划 ：

应用计划

另外，如果您启用了帐户和服务计划，请选择那些帐户的默认计划

帐户计划（可选）

服务计划（可选）

完成所需的设置更改后，进入开发人员门户并尝试注册新的开发人员，以测试结果。试验并做出必要的调整，以准确获取 API 的正确工作流。当您对工作流感到满意时，最好检查您的电子邮件通知，以确保他们为开发人员提供正确的信息。

您应该熟悉布局和页面创建步骤，以及 Liquid 格式标签的基础知识。有关 quid 标签的详情，请参阅 Liquid 参考。"多个服务"功能必须在您的帐户上启用（可用于 Pro Plan 和 up）。

强烈建议您阅读有关 注册工作流 的信息，因此您将准备好整个设置，并了解它的工作原理。

通过创建新布局来启动该过程，该布局将作为您的多服务注册页面的模板。进入 CMS 系统的布局部分，并创建新的布局。您可以将其称为 multipleservicesignup（多服务注册），以方便将其与其他布局区分。在编辑器中，粘贴标准布局（如家或主布局）的一般结构。现在，删除您不需要的一切 - 所有容器、侧边栏、附加框等。

创建了一个布局的后退性，请继续自定义代码以进行注册。

默认情况下，开发人员门户上启用了用户名/电子邮件和密码身份验证。通常，此处未进行更改，因为这是开发人员创建帐户和登录的标准方法。

但是，在某些情况下，您可能需要删除这个验证类型。要做到这一点，编辑 Login > New 模板，如下屏幕截图中：

如果您需要向开发人员门户添加用户名/电子邮件和密码身份验证，只需删除上一步中添加的 liquid 注释标签即可。

要启用自己的 GitHub 应用，首先您需要创建一个并检索对应的凭据。

您可以通过 GitHub 配置身份验证的方法有两种：

要更改此默认配置，您可以进入 3scale 管理门户，在 Audience > Developer Portal > SSO Integrations 中，您会看到以下屏幕：

点击 GitHub 访问配置屏幕：

在此屏幕中，您可以：

Red Hat Single Sign-On(RH-SSO)是一个集成的 Sign-On 解决方案(SSO)，它可与 3scale 一起使用时，允许您使用任何可用的 RH-SSO 身份提供程序和用户联合选项来验证您的开发人员。

有关 Red Hat Single Sign-On 版本与 3scale 兼容的信息，请参阅支持的 配置 页面。

5.4.3. 配置 3scale

复制链接

默认情况下，不通过 Red Hat Single Sign-On 进行身份验证。如果要将 Red Hat Single Sign-On 帐户与 3scale 结合使用来管理开发人员门户的访问权限，您可以按照以下步骤进行配置。

进入 3scale 管理门户，在 Audience > Developer Portal > SSO Integrations 中点 Red Hat Single Sign-On。（注意：这只是企业功能，因此您可能需要要求您的帐户经理为您启用此功能。

在这个配置屏幕中，您需要添加您在上一步中配置的 Red Hat Single Sign-On 客户端的详情：

• 客户端 ：红帽单点登录中的客户端名称
• Client Secret: Red Hat Single Sign-On 中的客户端 secret
• realm: Red Hat Single Sign-On 的名称和 URL 地址

输入后，选中"Published"框，再点 Create RH-SSO 使其在开发人员门户上可用。

首先，API 使用者必须在开发人员门户中有一个帐户。您可以使用帐户管理 API 将用户导入到 3scale，或者手动创建它们。在您的管理门户中找到 3scale ActiveDocs 的账户管理 API，位于您的管理门户，位于 右上角的文档（question mark icon(?)→ 3scale API Docs 部分。

用户存在后，您可以使用 API 请求调用来生成带有内置 SSO 令牌的 URL:

curl -X POST -d "provider_key=YOUR_PROVIDER_KEY&username=USERNAME&expires_in=60" https://YOUR_ADMIN_PORTAL.3scale.net/admin/api/sso_tokens.xml

此调用中有 2 个参数：username，用于指定您要请求令牌的人员和 expires_in，这是令牌的有效秒数（默认值为 10 分钟）。

您还可以传递额外的参数 redirect_url，该位置在成功登录后重定向用户。这个参数应该采用百分比编码。XML 响应将包含一个 URL，其中包含了一个 secret 令牌：

<?xml version="1.0" encoding="UTF-8"?>
<sso_url>
https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000
</sso_url>

响应包含一个带有令牌的 RH SSO 登录 URL：

https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000

URL 包含 3scale Developer Portal SSO 登录所需的所有信息。您可以直接嵌入 web 中。但是，URL 可以在用户单击之前过期，因此建议您在页面上有一个通用链接，此链接会动态请求新的 SSO URL 并重定向到它。这样，用户就可以无缝登录到开发人员门户。

在创建受限部分时，执行它以便每个部分映射到用户的逻辑组非常有用。在本例中，假设有一组名为"合作伙伴"的开发人员。

在 Developer Portal 中创建一个新部分，用于您要限制访问的每个页面或一组页面。取消选中"public"状态字段。然后拖放您想要的页面。

创建一个组，并授予它对您创建的部分的访问权限。

现在，每次您必须授予一个用户对这个部分的访问权限时，您要做的只是将它们分配给这个组。为此，请进入相应的帐户详细信息页面，然后进入"组权限"。 一旦进入，请选中您要允许的部分的框。

需要的标记是自定义开发人员门户的一种非常强大方式。请在此处根据条件来隐藏或显示页面的部分。3scale 允许您为帐户、应用程序和用户创建自定义字段。您可以使用它来存储有助于作为 API 提供程序的信息。在这里，您要创建一个附加到所有帐户的自定义字段，并使用它来指明指定帐户是否为合作伙伴。您可以通过转至 Audience > Account > Field Definitions 来创建此字段。向 Account 部分添加一个字段，并将它标记为隐藏，这样它就不会显示在注册页面上，或门户上的任何其他位置。

现在您可以使用自定义字段向合作伙伴展示特殊内容，方法是将其嵌套成以下代码片段中的条件：

{{ if current_account.extra_fields.partner == 'true' }}
  // content only accessible to partners
{{ endif }}

或者，如果您的情况更好，使用 inverse 逻辑：

{{ unless current_account.extra_fields.partner == 'true' }}
  // content forbidden for partners
{{ endunless }}

在这里，每当您想要向用户显示这些隐藏内容时，您要做的都是在其帐户详细信息页面的"true"字段中键入的。

您可以根据状态的变化，为开发人员提供对受限内容的访问。例如，升级应用程序计划的时间。

通过与帐户管理 API 结合使用 webhook 来简化调配的过程。帐户管理 API 位于 3scale ActiveDocs 中，您的管理门户可提供：

除了限制对上述内容的访问的两种方法外，还有另一种非常有用的技术：需要已登录的用户。

这非常容易使用 Liquid 标签来实现。您要做的就是包装内容，该内容仅适用于以下条件内的登录用户：

{{ if current_user }}
  // only visible if the user is logged in
{{ endif }}

本节介绍如何在布局和页面中启用流动标记处理。

9.1.1. 启用 Liquids

复制链接

默认情况下，所有部分和电子邮件模板都会启用 quid 标记处理。通过在 system_name 输入字段下的复选框在布局上启用它们。但是，要在页中启用它们，您必须前往该页面的高级选项部分。

只需展开高级选项部分，并标记"启用"复选框。现在，所有 liquid markup 将由内部引擎处理，开发人员门户内置编辑器也会添加代码高亮显示。

<!-- if we are inside '/documentation' URL -->
<li class="{% if request.request_uri contains "/documentation" %}active{% endif %}"><!-- add the active class to the menu item -->
  <a href="/documentation">Documentation</a>
</li>

本节介绍如何使用相关的标签来自定义电子邮件模板。

此故障排除部分将帮助您调试和修复可能出现的典型错误。

这些电子邮件模板属于帐户管理类别：

对于这些模板，您可以使用以下 liquid drops：

另外，以下模板：

向帐户邀请其他用户的电子邮件：

您可以使用以下 liquid drops：

可以访问：

以下电子邮件模板均处理应用程序和应用程序计划通知。

他们可以访问：

应用程序计划更改请求通知电子邮件模板：

他们可以访问：

以下电子邮件模板包含多个可用 drop，例如：

他们可以访问：

以及上述所有 liquid drops，以下应用程序计划消息…​

使列出额外的 quid 丢弃

针对应用程序键的以下电子邮件模板会更提示：

以下电子邮件模板…​

具有以下权限：

另外，以下 templates…​

分享以下 liquids：

以下电子邮件模板：

可以访问：

以及以上 liquid drops，以下服务模板…​

另外列出了 liquid drops：

以下电子邮件模板…​

可以访问：

有默认的样式表 default.css。它非常大、复杂，而不是扩展它，最好为您自己的自定义创建自己的风格表来覆盖默认值。您可以创建一个新样式表的方式创建页面（请记得在高级页面设置中选择适当的 MIME 内容类型）。

务必要确保所选的布局为空。否则，页面布局 HTML 将模糊处理 CSS 规则。

在链接到 bootstrap.css 的链接后，将每个布局模板（或部分有共同的 HEAD 部分）链接到您的自定义 CSS 的链接。例如：

<link rel="stylesheet" href="/stylesheets/custom.css">

现在，享受您自己的独一无二的品牌！

最重要的一点是确定要隐藏的内容。为此，请使用 Firebug（或其他开发人员工具，如 Chrome 开发人员工具或 Opera Dragonfly）。选择所需元素，并在控制台中点击它并选择 Copy CSS 路径。这样，您可以保存准确的 CSS 路径，以简化操作。请记住，如果元素是侧栏导航小部件的一部分，您还必须指定列表中的位置。对于这一点，您可以使用"+"选择器（例如，选择第 3 个部分），例如：ul + li + li + li + li + li）或 :nthild(n)CSS3 pseudoclass。

现在，已确定了元素，您可以更改其显示设置。根据元素类型，您可以从以下两种可能的方法中选择：CSCS 操作或 jQuery 脚本。CSS 操作更加轻便且更可靠，但对于很多页面存在的某些种类的元素（例如，管理门户控制面板侧栏的第 3 部分元素也存在不同的值）。某些棘手的实施需要使用 CSS3，而这些方案不受旧浏览器的支持。在接下来的两个步骤中，您将看到这两种方法。

例如，尝试从 Dashboard 页面中隐藏最新的论坛文章框。第一步，您已将其 CSS 路径识别为：

#three-scale .dashboard_bubble

请记住，这是第二个具有相同路径的方框，因此您将使用"+"选择器。您的路径现在类似如下：

.main_layout #three-scale .dashboard_bubble + .dashboard_bubble
/* or */
.main_layout #three-scale .dashboard_bubble:nth-child(1)

将 display 属性改为 none 会导致这个方框不可可见：

.main_layout #three-scale .dashboard_bubble:nth-child(1) {
  display: none;
}

如果您有复杂的元素来隐藏某一侧栏菜单元素，最好使用一些 jQuery。这些元素的 CSS 路径在 Dashboard 和 Account 部分中是一致的，您不想在这两个部分中隐藏元素。因此，请根据 CSS 路径和内容选择元素。在本例中，假设您想从 Dashboard 的边栏中隐藏 messages 部分。您的 CSS 路径为：

#three-scale #submenu li a

为了与内容匹配，您将使用 .text() 函数。您还会在文档头和就绪函数内包括代码，以便在生成所有内容后执行。

生成的代码片段类似如下：

$(function() {
  $('#three-scale #submenu li a').each(function() {
    if ($(this).text() == "Messages")
      $(this).parent().css('display', 'none');
  });
});

这不是唯一的解决方案。它只是显示这样一种可能的实现方法。同样的示例可以使用纯的 CSS 带有属性值的 CSS3 选择器。有关完整的 CSS3 选择器规范，请 在此处 查看。

webhook 是事件触发的自定义 HTTP 回调。在 3scale 系统中，所有可能的事件会显示在 帐户设置 （右上角的gear 图标） > Integrate > Webhooks。

当发生这些事件时，3scale 系统会向 webhook 部分中配置的 URI 发出 HTTP 或 HTTPS 请求。在末尾，您可以将监听程序配置为调用一些所需的行为，如事件跟踪。

剩余的两个复选框打开 Webhook ("Webhooks is" 交换机)，并允许在管理门户中的操作触发 Webhook。默认行为是仅由 Developer Portal 中触发的操作触发 Webhook。请记住，这意味着不能触发所有事件。

Webhook 的格式始终相同。它通过以下结构的 XML 文档发布到端点：

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

每个元素提供信息：

如果您需要提供 3scale 发布 webhook 的保证，公开 HTTPS Webhook URL，并在 3scale 中添加自定义参数到 webhook 声明中。例如：https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue。决定参数名称和值。然后，在 webhook 端点内检查是否存在这个参数值。

如果您在侦听端点时遇到问题，可以恢复失效的发送。如果端点返回了 200 代码，3scale 会认为发生了一个 webhook。否则，它将重试 5 次，并有间隔 60 秒。在因中断或定期进行任何恢复后，您应该运行检查，并在适用清理队列时运行。您可以在 ActiveDocs 中找到有关以下方法的更多信息：

该工作流部分通过下列步骤在管理门户中轻松设置。

进入 Audience > Developer Portal > Signup，在其中会显示一个空白页面来填充您的签字法律条款。您可以使用 HTML、JavaScript 和 CSS 的任意组合。还可以通过单击 Insert togling 代码来提供一些切换的代码。您在此框中编写的内容只需在开发者门户的 Sign Up 页面上的 Sign Up 按钮上方出现。

填写了条款和条件后，点 Update 保存它们。

如果您使用切换代码，它将显示"通过签名，您同意以下法定条款和条件"，后跟一个链接，在显示和隐藏您指定的条件和条款之间切换的链接。

默认情况下，这放置在 Signup 页面上，但它是一个部分(signup_licence)，可在开发人员门户的任何位置包含。要从 Signup 页面删除它，只需在页面中删除 {% include 'signup_licence' %} 行。同样，如果要在其它位置包含它，您可以通过代码片段的其它部分使用相同部分，这些部分可以放置在开发人员门户网站中的任何位置。

您可能还希望用户在创建新应用程序时(new_application_licence partial)和/或订阅新服务(service_subscription_licence partial)时，用户接受另一组条款和条件。要设置这些设置，您可以按照上述步骤相同的步骤。

您还可以定义不同策略所在的其他 URL。要设置它们，请转至 Audience > Billing > credit Card Policies 并设置您的策略页面所在的路径。

要使这些链接正常工作，您将需要在 Developer Portal 中创建新页面。

完成后，您可以使用 URL 的 liquid drop 引用它们。例如：

<a href="{{ urls.credit_card_terms }}">Legal Terms</a>
<a href="{{ urls.credit_card_privacy }}">Privacy</a>
<a href="{{ urls.credit_card_refunds }}">Refunds</a>

And that’s it!

在本教程结束时，您将启动并运行开发人员门户来推进您的 API，允许开发人员注册帐户，并访问其 API 密钥。

您可以配置其他区域，供您配置：