创建开发者门户
良好的开发者门户是确保 API 使用的关键。快速创建您的内容。
摘要
第 1 章 开发人员门户
在本节结束时，您应熟悉开发人员门户，包括其结构、使用和功能。 您可以自定义整个开发人员门户的外观和感觉，使其符合您自己的品牌。您已完全控制门户的每个元素，因此您可以尽可能轻松控制，以便开发人员了解如何使用您的 API。成功的 API 开发人员门户将有助于开发人员随时将概念过渡到工作应用程序。
1.1. 开发人员门户概述
开发者门户由几个元素组成： 可访问 Content, Drafts, Redirects, Groups, Feature Visibility, ActiveDocs, 法律条款, Settings 和 Liquid 文档的左菜单。 包含上述部分详情的主要区域。
1.2. 内容
这是开发人员门户系统查看最重要的部分。content 部分显示站点结构和层次结构，并在同一个页面中提供编辑功能。这意味着您可以管理站点结构、页面和其他存储在它的资产。门户的层次结构以目录树的形式显示。 上面的镜像显示了 content 部分中其中一个页面的示例视图。如上所示，它会显示所有文件（页面、镜像、样式表、JavaScript 等）保留站点的路径层次结构。如以前一样，部分的功能与目录完全相同。 在右侧，您可以看到编辑页面视图。您可以在此处看到页面名称（它还代表了它是标准还是内置页面）以及将新元素添加到内容的按钮（页面、布局、部分、文件或 portlet）。下面，您可以选择页面将使用的布局，并切换 liquid 标签功能。以下部分是文本编辑器，它支持代码突出显示、tabulations、line numeration 等。选项卡按钮在编辑文档的草案和发布版本之间 Draft 和 Published 开关。以下两个图标列出了文档的版本，并分别打开一个弹出窗口。 要编辑页面内容，只需选择所需的布局，设置几个附加选项，如内容类型和 URL 路径，然后在 HTML、Markdown 或 Textile 中输入代码。 此视图中的另一个重要功能是 Preview 按钮。您可以选择是否预览页面发布的或草案版本。点按钮将您重定向到 Developer Portal 模式，您可以在其中看到页面的实时（或草案）呈现版本，其中右侧有一个灰色的垂直栏。此栏包含开发人员门户的页面、布局和部分编辑视图的链接。它允许您在草案和公布的视图之间切换。 还有一个过滤器功能，它不仅充当搜索字段，但允许您将显示的元素限制为仅样式表、JavaScript 或指定的任何其他类型。
1.3. 布局和部分
布局和部分部分管理模板和页面的可重复使用的部分。它们的功能与 content 部分的功能类似。 layout 部分由页面使用的模板定义组成。Layout 是页面的主要结构，此模板的内容将呈现在每个使用它的页面中。部分、portlet 和页面的实际内容驻留在模板中。 部分是代码的可重复使用的部分，可应用于不同页面上的多个位置。例如，在每个布局上，页脚都相同，在具有不同布局的几个页面中，侧边栏是相同的。 要在布局、部分、电子邮件模板或 portlet 中包含部分，请使用以下命令：
{% include "partial_name" %}
与门户的其他部分一样，布局和部分也具有草案和发布状态，并提供完整的版本历史记录，具有以下功能： 布局模板的文本编辑器。 保存草案、发布当前版本并恢复到上次发布的状态。 在草案和发布的版本间切换文本编辑器，列出版本历史记录，并启动弹出窗口。 有关 liquid 标签的完整指南，请查看 Liquid 参考指南 。
1.4. portlets
开发人员门户最初不会填充任何 portlet。您必须使用管理门户自行创建它们。 内容的最后小节是 portlets。它们为您提供了一些高级功能，而无需任何高级编码。我们的开发人员门户提供三个不同的 portlet： 外部 RSS 源：从给定源获取 RSS 源。 内容表：在给定部分中生成页面的链接列表。 最新论坛文章：生成最新论坛文章的列表。 在创建所需的 portlet 时，您必须在设置页面中输入请求的数据，如标题、系统名称和外部 RSS 源 portlet 的 URL 源。
1.4.1. 备注
编辑器使用自定义 liquid 标签预先填充标准 portlet 代码。如果您决定编辑生成的结构，请谨慎操作。当有疑问时，请参阅 liquid 参考 章节。
1.5. 重定向和更改
开发人员门户的最后元素是 redirect 和 changes 部分。它们比 content 部分要少，但仍然很重要，并提供一些自定义功能。 重定向可帮助您从一个门户 URL 重定向到另一个门户 URL 的帮助。例如，当弃用旧页面且不想更改所有链接时，这非常有用。重定向不能用于内置开发人员门户页面 - 它们仅用于您创建的页面 。 最后，但不是更改部分。它包含所有新编辑和未发布的页面的列表，并为您提供一次单独发布或全部发布页面的选择。
第 2 章 自定义注册表单字段
了解如何添加自定义注册字段以及此功能的不同选项。
默认情况下，3scale 在 user/account/application 处提供常用的字段。您可能需要在这些常见默认值中添加自己的自定义字段。
在管理门户中，进入
Audience > Accounts > Accounts > Field Definitions
，从中可查看默认表单字段并定义新的表单。
新帐户/用户注册页面实际上是前两个部分的修改。帐户字段显示在顶部，后跟用户字段，后跟不需要配置的密码字段。
尝试添加 3 个额外项，2 个添加到注册项，1 个添加到账户项。单击 create，添加以下新字段定义，然后创建它。当然，所需的复选框将使它在报名表上强制使用。另外，还有选项可使内容隐藏且只读。可以添加一个隐藏字段，例如：当您希望新符号设置有字段时，您不希望突出显示它们，如 access_restricted_are，它默认为空。作为管理员，您可以逐个用户将其更新为 true。您的页面逻辑可将其读取，以确定显示的内容。例如，只读字段可能是浏览器位置，您可以使用 JavaScript on page load 进行设置。
现在，尝试在用户注册表单中添加下拉菜单。将它命名为"员工类型"。将这些以逗号分隔的值添加到 choices 字段中：整时、部分时间和合同。下拉菜单将填充这些值。
现在，在帐户中添加预定义的字段。通常，您添加的字段没有系统功能 - 它们只是保存以后可以访问的数据。（请参阅
受限内容
。）
以正常方式创建字段。然后，在"name"的下拉菜单中，选择 po_number。使用此字段时，发送给此开发人员帐户的 3scale 生成的发票上将显示 PO 编号。系统范围的字段可以随时被您的管理员覆盖。为字段指定名称 - 类似于"PO number" - 并对其进行创建。
现在来看一下您的工作。您可以看到免费文本姓氏，并将雇佣类型下拉列表添加到 User 部分。PO 编号系统字段也添加了可用文本。
最后，这些自定义字段可使用 3scale ActiveDocs 进行设置；例如，
应用程序创建
。
第 3 章 配置注册流程
在本节中，您将了解将哪些设置配置为调整注册工作流。 注册工作流是您通过开发人员门户提供的开发人员体验的关键方面。此过程可以从完全自动和自助服务到其他极端服务，要求完全控制谁可以访问各种粒度级别。 3scale 平台允许您结合使用帐户（可选）、服务（可选）和应用程序计划对 API 进行建模。对于每个计划，您可以控制是否有您操作的批准。另外，您还要确定是否有默认值，或者开发人员是否需要执行下一步并做出选择。 对于最大自动化和自助服务，请删除所有批准步骤并启用所有可能的默认计划。这样，可以签发密钥以便在注册后立即提供对 API 的访问权限。
3.1. 删除所有批准步骤
要删除批准，请转到 Audience > Accounts > Usage Rules 的 Signup 部分，确保选中 Developers 选项。 另外，如果您启用了帐户和服务计划，请向下滚动页面并确保两个情况下都 直接启用更改计划 ：
3.2. 启用所有可能的默认计划
另外，如果您启用了帐户和服务计划，请选择那些帐户的默认计划 帐户计划（可选） 服务计划（可选）
3.3. 测试工作流
完成所需的设置更改后，进入开发人员门户并尝试注册新的开发人员，以测试结果。试验并做出必要的调整，以准确获取 API 的正确工作流。当您对工作流感到满意时，最好检查您的电子邮件通知，以确保他们为开发人员提供正确的信息。
第 4 章 多服务注册
在本节结束时，您将了解到创建和自定义多服务注册页面的步骤。 如果您使用多个服务功能，您可以自定义注册过程来让客户订阅不同的服务。
4.1. 先决条件
您应该熟悉布局和页面创建步骤，以及 Liquid 格式标签的基础知识。有关 quid 标签的详情，请参阅 Liquid 参考 。"多个服务"功能必须在您的帐户上启用（可用于 Pro Plan 和 up）。 强烈建议您阅读有关 注册工作流 的信息，因此您将准备好整个设置，并了解它的工作原理。
4.2. 简介
通过创建新布局来启动该过程，该布局将作为您的多服务注册页面的模板。进入 CMS 系统的布局部分，并创建新的布局。您可以将其称为 multipleservicesignup（多服务注册） ，以方便将其与其他布局区分。在编辑器中，粘贴标准布局（如家或主布局）的一般结构。现在，删除您不需要的一切 - 所有容器、侧边栏、附加框等。 创建了一个布局的后退性，请继续自定义代码以进行注册。
4.3. 多服务注册
4.3.1. 检索有关服务的信息
要检索有关需要构建正确注册链接的服务的所有信息，您必须通过服务对象进行循环。服务是模型对象的一部分。
{% for service in provider.services %}
{% endfor %}
4.3.2. 配置注册列
您已有布局和循环访问服务对象。现在，决定您要如何显示服务以及注册链接的信息。例如，通过服务描述和底部的注册链接将它们划分为列。每列将作为一门服务列框，其中包含所有必要的信息。
{% for service in provider.services %}
<div class="service-column">
<p>{{ service.name }}</p>
<p>{{ service.description }}</p>
{% endfor %}
内部容器充当自定义 description 字段。service.name 是服务名称，在本例中是容器的名称。
4.3.3. 配置订阅
现在，自定义服务注册的主要部分 - 创建注册链接，提取注册 URL 和服务 ID。从 URL 的对象和服务 ID 中获取您迭代循环的服务对象的注册 URL。最终的链接代码类似如下：
<a href="{{ urls.signup }}?{{ service | toparam }}">Signup to {{ service.name }}</a>
您还必须考虑该用户可能已对某些服务进行了签名。创建要检查的条件块。
{% unless service.subscribed? %}
<a href="{{ urls.signup }}?{{ service | toparam }}">Signup to {{ service.name }}</a>
{% endunless %}
因此，您可以生成最终代码：
{% for service in provider.services %}
<div class="service-column">
<p>{{ service.name }}</p>
<p>{{ service.description }}</p>
{% unless service.subscribed? %}
<a href="{{ urls.signup }}?{{ service | to_param }}">Signup to {{ service.name }}</a>
{% endunless %}
{% endfor %}
4.3.4. styling
根据您拥有的服务数量，向生成的标记添加一些最终的接触。在这个示例中，它有两个，因此 service-column div 的 CSS 代码将是：
.service-column {
float: left;
margin-left: 10%;
width: 45%;
.service-column:first-child {
margin-left: 0;
在示例中，我们使用了基于百分比的布局动态地分配包含维度的尺寸上列的宽度。
现在，您应该有一个正常工作且良好地忽略多个服务子版本。祝贺您！
如果您希望以特定顺序显示列，请尝试使用条件表达式(if/else/case)条件服务名称或其他值。
第 5 章 开发者门户身份验证
按照以下步骤配置开发人员门户的访问权限。 本文介绍了如何在开发人员门户上启用和禁用不同类型的身份验证，以使开发人员能够注册或登录。 目前，3scale 支持多种向开发人员门户进行身份验证的方法，具体将在以下部分介绍： 用户名/电子邮件和密码 通过 GitHub 进行身份验证 通过 Auth0 进行身份验证 通过 Red Hat Single Sign-On 进行身份验证 默认情况下，开发人员门户上只能启用一种类型的验证，如果您已在 3scale.net 中进行了签名： 用户名/电子邮件和密码 通过 GitHub 进行身份验证（使用 3scale GitHub 应用程序）- 只有在 3scale.net 上注册时才会默认启用 较早的 3scale 帐户（在 2015 年 12 月 14 日之前创建）可能需要遵循额外步骤才能启用 GitHub 和 Auth0 身份验证。 如果这适用于您，则需要将以下代码片段添加到登录并注册模板以便以两种形式启用此功能。
{% include 'login/sso' %}
5.1. 启用和禁用用户名/电子邮件和密码
默认情况下，开发人员门户上启用了用户名/电子邮件和密码身份验证。通常，此处未进行更改，因为这是开发人员创建帐户和登录的标准方法。 但是，在某些情况下，您可能需要删除这个验证类型。要做到这一点，编辑 Login > New 模板，如下屏幕截图中： 如果您需要向开发人员门户添加用户名/电子邮件和密码身份验证，只需删除上一步中添加的 liquid 注释标签即可。
5.2. 通过 GitHub 启用和禁用身份验证
要启用自己的 GitHub 应用，首先您需要创建一个并检索对应的凭据。
您可以通过 GitHub 配置身份验证的方法有两种：
使用 3scale GitHub 应用程序（默认为托管 3scale 帐户）
使用您自己的 GitHub 应用程序（用于内部安装）
要更改此默认配置，您可以进入 3scale 管理门户，在
Audience > Developer Portal > SSO Integrations
中，您会看到以下屏幕：
点击
GitHub
访问配置屏幕：
在此屏幕中，您可以：
在您的开发人员门户上提供或不可用 GitHub 身份验证，只需选中或取消选中"推送"框。
选择 3scale 品牌 GitHub 应用或添加您自己的 GitHub 应用 - 3scale GitHub 应用程序默认为启用（发布）。您可以通过单击
Edit
并输入 GitHub 中创建 OAuth 应用程序的详细信息（"Client"和"Client secret"），来配置自己的 GitHub 应用。请注意，为了使集成可以与您自己的 GitHub 应用程序正常工作，您应该使用 "Callback URL" 配置 GitHub 应用程序的授权回调 URL，以便在切换到"自定义品牌"选项后（例如
https://yourdomain.3scale.net/auth/github/callback
）。
测试配置的身份验证流是否按预期工作。
