Language:
Format:

创建开发人员门户

Red Hat 3scale API Management 2.11

优秀的开发人员门户必须确保采用您的 API。无需再创建您的密码。

摘要

本指南记录了红帽 3scale API 管理 2.11 上的开发人员门户。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。详情请查看我们的 CTO Chris Wright 信息。

第 1 章为 3scale 管理的 API 创建开发者门户概述

您的 3scale 开发人员门户是 API 用户使用的网站：

注册以访问 3scale 管理的上游 API
有关如何使用上游 API 的文档

3scale 提供了一个示例开发者门户，它包括了大多数 API 供应商要在其开发者门户中实施的功能。这个原生开发人员门户使用示例 Echo API 来演示典型的开发人员门户的结构。在浏览原生开发人员门户后，您需要做相应的修改信息，以便您了解如何创建自己的开发人员门户。

了解和修改原生开发人员门户没有先决条件。但是，在修改原生开发人员门户以创建自己的开发人员门户后，还必须在为 API 用户打开开发人员门户前实施单点登录工作流和验证。

1.1. 为创建开发者门户提供 3scale 编辑环境

在开始创建开发人员门户前，请先浏览 3scale 提供的 Echo API 开发人员门户示例。Echo API 开发人员门户是创建自己的开发人员门户的起点。您不会从头开始创建开发者门户。相反，您可以修改原生 Echo API 开发人员门户，以创建具有您想要的外观和感觉的开发者门户。

步骤

在 3scale 管理门户中，展开顶部的上下文选择器，再单击 Audience。
在左侧的导航树中，展开 Developer Portal，再单击 Content。这显示了用于创建开发人员门户的主要编辑环境：
在 Root 下，3scale 显示 Developer Portal 资源层次结构：
1. 文档、主页和 Show 是开发人员门户的基础页面。对于每个页面，向下滚动以查看定义页面内容的 HTML。
2. 这些页面下的文件夹包含将 3scale 资源拉取到开发者门户的页面。例如，Account 文件夹包含用于显示并编辑 3scale 帐户的页面，该帐户时在管理门户中创建的 3scale 管理员。使用这些页面作为起点，并根据需要对其进行修改。
3. 在右上角，通过 New Page 下拉菜单可以添加一个页面、布局、部分、部分、文件或 portlet。选择每个选项查看您提供的信息来创建。
在选择了 Developer Portal > Content 时，将资源层次结构向下滚动到几乎底部，直到您看到 Layouts 并点 Main layout。
向上滚动到顶部，可以看到 布局"Main Layout" 标题。
在内部标题和系统名称后，您可以看到 Liquid 已启用。liquid 是 3scale 用于显示和处理 3scale 系统中的大部分数据的框架。定义页面内容的代码包含 Liquid 标记和 HTML。您可以在 Draft 选项卡中看到它，其中包含 Developer Portal 页的主布局的代码。
在左侧的导航树中，在以下 Developer Portal > Content 下方，点每个子类别来浏览它：Drafts, Redirects, Groups, Logo, Feature Visibility, 和 ActiveDocs.
在左侧的导航树中，单击 Developer Portal 下的导航树，单击 Visit Portal，这是最后一个条目。
新的浏览器选项卡显示 3scale 提供的 Echo API 开发者门户的开发版本的网站。您可以使用此开发版本来查看 3scale 原生开发人员门户。然后，您可以迭代地自定义和查看对原生开发人员门户所做的更改，以创建自己的开发人员门户。
您知道，这是开发人员门户的开发版本，因为它在顶端的 Draft|Published 右侧有一个深灰色的面板。Draft 视图支持迭代/递增改进。当 Draft 版本查找并的行为方式时，您可以发布它。
右侧的面板列出了提供当前页面内容的元素：
1. 页面主页
2. Layout Main layout
3. Partial Submenu
4. Partial analytics
点 Page Homepage。新的浏览器标签页会显示 Developer Portal 编辑环境，其中包含 Page 'Homepage' 用于编辑。
返回到 Echo API 开发人员门户的开发版本，再单击右上角的 SIGN IN，它会显示 API 用户用来登录到您的开发人员门户的 SIGN IN 页面。
在右边的灰色面板中，模板列表下方，是一个用户名和密码，可用于模拟使用开发人员门户的签名：
1. 在 SIGN IN 页面中，在 USERNAME OR EMAIL 字段中输入 John，这是右侧灰色面板中列出的用户名。
2. 在 PASSWORD 字段中，输入 123456，这是灰色面板中列出的密码。
3. 点 Sign In 显示 Developer Portal，因为您的 API 用户会看到它。

后续步骤

继续探索原生开发人员门户，如您想要的那样。当您熟悉编辑环境和 Echo API 开发人员门户的开发版本时，请遵循修改 3scale 原生开发人员门户的步骤。

1.2. 修改 3scale 原生开发人员门户

探索 Echo API 开发人员门户后，在开始创建自己的开发人员门户前对它进行一些更改。这些实践步骤有助于为开发人员门户创建准备工作。

此流程将示例 3scale Echo API 登录页标题替换为通用 Swagger Petstore API 的标题。它还介绍了如何更新开发人员门户来显示 Petstore API 的文档。

步骤

在 3scale 管理门户中，展开顶部的上下文选择器，再单击 Audience。
在左侧的导航树中，展开 Developer Portal，再单击 Content。
在 Root 下，单击 Homepage，它是 Developer Portal 登录页面的内部标题，并更改 Developer Portal 开发版本中显示的登录页面标题：
1. 在 Page 'Homepage' 中，向下滚动以查看呈现登录页面的代码。
2. 在第 5 行，更改
```
<h1>Echo API</h1>
```
  至
```
<h1>Petstore API</h1>
```
3. 在页面底部，单击 Publish。
4. 在左侧的导航树中，点击 Developer Portal 下的导航树，单击 Visit Portal 以显示开发人员门户的开发版本，并可以看到登录页面标题现在是 Petstore API。
保留开发人员门户的开发版本，再单击位于顶部菜单栏中的 Documentation。Developer Portal 为 Echo API 显示 ActiveDocs。
返回到 3scale 管理门户并选择 Developer Portal > ActiveDocs 查看 Echo API 的条目。3scale 提供定义 Echo API 的 OpenAPI 文档。3scale 使用这个 OpenAPI 文档为 Echo API 显示 ActiveDocs。
导入定义 Swagger Petstore API 的 OpenAPI 文档：
1. 进入 https://petstore.swagger.io/v2/swagger.json，并将 JSON 内容复制到您的剪贴板中。
2. 返回到带有 Developer Portal > ActiveDocs 的 3scale 管理门户。
3. 在 ActiveDocs 页面中，点击 Create a new spec。
4. 在 Name 字段中输入 Petstore。
5. 选择 Publish?。
6. 点击 API JSON Spec 窗口，粘贴剪贴板中的 Swagger Petstore JSON 内容。
7. 点页面底部的 Create Spec。3scale 为 Petstore API 显示 ActiveDocs。
8. 在左侧的导航树中，单击开发人员门户下的 ActiveDocs。在 Echo API 之后，会有一个 Petstore 的第二个条目。
在 Developer Portal 中显示 Petstore API 的文档：
1. 在左侧的导航树中，单击开发人员门户下的内容。
2. 在 Root 下，单击 Documentation，这是 Developer Portal 文档页面的内部标题。
3. 在 Page 'Documentation' 中，向下滚动以查看呈现文档登录页面的代码。第 5 行标识开发者门户显示 ActiveDocs 的 OpenAPI 文档。第 5 行的默认值为：
```
{% assign spec = provider.api_specs.first %}
```
  默认行为是，您的开发人员门户在 Developer Portal > ActiveDocs 页面中显示 ActiveDocs 的 ActiveDocs，最初是 Echo API。此图突出显示了第 5 行：
4. 修改第 5 行，以将 provider.api_specs.first 更改为一个索引，用于识别 ActiveDocs 页面中的第二个条目：
```
{% assign spec = provider.api_specs[1] %}
```
  默认行为是，您的开发者门户只会显示 ActiveDocs 文档。要显示多个 OpenAPI 文档的 ActiveDocs，您必须在这个简单更改之外修改 Documentation 页面。
5. 在页面底部，单击 Publish。
在左侧的导航树中，单击 Developer Portal 下的导航树，单击 Visit Portal 以显示开发人员门户的开发版本。
在顶部菜单栏中，点 Documentation 查看 Swagger Petstore 文档。

后续步骤

通过更改原生的 Developer Portal 页面来创建开发人员门户，以便它们显示有关对 3scale 管理的 API 和 API 文档的访问信息。

1.3. 修改原生开发者门户的其他 3scale 功能描述

3scale 提供了许多用于自定义原生开发人员门户的功能，以创建自己的开发人员门户。

在开发开发人员门户期间，需要查看开发人员门户的任何人都必须指定访问代码。在 API 供应商执行必要的任务来打开您的开发者门户时，请保留此访问代码，但 API 用户访问代码可确保只有具有此代码的任何人都可以查看您的开发人员门户。访问代码位于 Domains & Access 页面中，该页面中可通过选择 Audience> Developer Portal > Domains & Access 来获得。

以下列表引入了一些修改原生开发人员门户的功能：

在 Developer Portal > Content 环境中，右上角的 New Page 下拉菜单可让您在 Developer Portal 中添加以下元素：
- Page - 开发者门户内容的基本单元。
- Layout - 多个页面可使用的模板。
- Partial - 可在其他部分、布局和页面中重复使用的内容。
- Section - 功能相当于一个目录。创建部分以组织开发人员门户内容。
- File - 您希望开发人员门户使用的资源，如样式表、镜像或脚本。
- Portlet - 外部 RSS 源、内容表或最新论坛文章。
您可以在 HTML、Markdown 或 Textile 中输入代码。代码编辑器支持代码突出显示、表格化、行号和其他功能。
您可以预览页面的草稿版本或发布版本。在页面的文本编辑器中，单击 Preview 会显示开发人员门户的开发版本。
preview 右侧有一个暗灰色的垂直拦。在黑色星形图的顶部，突出显示 Draft | Published 之一来指示您要查看的版本。这个栏包含到编辑环境的链接：
- 该页面。
- 页面使用的布局。
- 页面使用的任何部分。部分代码是在不同页面上的多个位置重复使用的代码。
开发人员门户的开发版本的 Draft 视图支持迭代/递增改进。当 Draft 版本外观和行为时，您可以发布它。当访问代码就位时，发布页面意味着您可以查看 API 用户是否活跃。当访问代码不再就位时，在 live Developer Portal 中发布该页面。
filter 字段允许您在 Developer Portal 环境中搜索资源。3scale 仅显示您要搜索的元素，这样可以更轻松地查找您想要进行的操作。过滤器字段在图标下方：
Developer Portal > Redirects 页面可让您将重定向从一个开发者门户 URL 设置为另一个。例如，如果您弃用了您创建的页面，您可以将请求重定向到新页面。
占位符是可编辑字段。例如，Developer Portal > Content > Login > New page 有几个占位符：
```
<input id="session_username" name="username" tabindex="1"
  autofocus="autofocus" type="text"
  placeholder="Authenticate with your email"
  class="form-control">
...
<input id="session_password" name="password" tabindex="2"
  type="password"
  placeholder="…and password"
  class="form-control">
```
此代码在 Developer Portal 中生成以下字段：
您可以更新占位符文本并发布它以在 Developer Portal 中看到更新。例如，您可以使用 电子邮件将 Authenticate 更改为 Authenticate email。发布页面后，您可以在 Developer Portal 中看到更新的提示，例如：

1.4. 3scale 布局和部分重复利用开发人员门户内容

在 Developer Portal > Content 环境中，当您在资源层次结构中向下滚动时，您可以看到 Layouts 和 Partials 的标题。布局和部分可让您在开发人员门户中重复使用内容：

布局将页面的基本结构定义为页面模板。使用特定布局的每个页面都包含布局定义的内容。正如您在布局下资源层次结构中所看到的那样，您的原生开发人员门户提供了一个 错误布局和主布局。您可以修改这些布局的代码，您可以创建布局。
您在开发人员门户中的多个位置使用的部分代码。例如，部分可以在多个页面上定义所有布局或侧边栏。您可以在页面、布局、其他部分或电子邮件模板中使用部分内容。在资源层次结构中，在 Partials 下，您可以看到原生开发人员门户提供的部分。有几部分用于收集分析、订阅应用程序计划、显示子菜单等。同样，您可以修改这些部分，您可以创建部分。
在页中，使用部分布局、部分或电子邮件模板来指定 include 命令以及部分名称。例如，要使用 子菜单 部分，可以指定
```
{% include “submenu” %}
```

布局和部分布局也有草案和发布状态以及版本历史记录。例如，您可以保存草案，发布案例，然后恢复到上次发布的版本。

要了解编辑和编写布局和部分代码的信息，请参阅 3scale Liquid Reference。

1.5. 在开发者门户中为 3scale 管理的 API 添加镜像和其他资产

通常，您需要使用自己的镜像、文件或其他资产来自定义原生开发人员门户。要做到这一点，将文件添加到 Developer Portal 内容库中，记录此环境中的路径，然后在代码中添加内容库中文件位置的链接。

先决条件

访问 Developer Portal 中要使用的镜像、文件或其他资产

步骤

在 Developer Portal 内容库中添加资产：
1. 在 Developer Portal > Content 环境中，展开 New Page 并选择 New File。
2. 在 Upload File 下，单击 Section 字段，以显示您可以在其中存储您要添加资产的目录列表，并点击适当的目录来选择它。例如，您可以选择 |- images。
3. 可选。在 Path 字段中，输入对您有用的任何额外路径级别。
4. 选择 Downloadable。
5. 单击 Choose File，导航到要添加的文件，选择它，再单击 Open。
6. 可选。在 Tag 列表 字段中，输入您要用来在代码中包含此新内容的 Liquid 标签，例如，输入 my-logo。
7. 点 Create File 将资产添加到 Developer Portal 内容库中。
记录下您所添加资产的路径。例如，如果您将 MyLogo.png 镜像添加到 images 部分，则路径为 /images/MyLogo.png。
要在代码中使用资产，请插入 HTML <a> 元素。例如：
```
<a href="/images/MyLogo.png"/>
```
另外，如果您为资产添加了 Liquid 标签，您可以通过指定标签在代码中使用资产，例如：
```
{% my-logo %}
```

1.6. 为 3scale 管理的 API 自定义原生开发人员门户的注意事项

在开始自定义原生开发人员门户以创建自己的开发人员门户前，您应该为基本元素、可重复使用的内容、页层次结构、页标题和品牌以及品牌制定计划。

基本开发人员门户元素 - 开发人员门户的计划应该包括：
- 站点地图：如何组织门户的框架。
- 顶部菜单栏：在每个页面上重复的导航。
- 侧面菜单栏：访问各部分中的各个页面。
- 页面布局指南：了解一致的外观和感觉。
- 可重复利用的内容 - 布局和部分确保开发人员门户网站的一致性。在开始创建页面前创建它们。
页面层次结构 - 从您的站点映射中的根级别开始，为每个顶部菜单项创建一个部分。
接下来，创建每个顶部菜单项所需的页面。当您创建页面时，请确保将其与正确的部分相关联。这会在 Developer Portal 中为 URL 路径创建一致的结构。要使用标记语言（如 Textile 或 Markdown）对页面进行编码，请展开页面 ADVANCED OPTIONS。Handler 字段标识标记语言。
页面标头和页脚 - 通常会在部分定义页面元素。当您只有几个布局时，您可能需要直接在布局中定义标头和页脚。
品牌 - 默认原生开发人员门户风格表 default.css 非常复杂。使用自定义（覆盖默认值）创建您自己的风格表，而不是扩展此样式表。
您可以像创建页面一样创建新的风格表。在高级页面设置中选择 css 部分和适当的 MIME 内容类型。然后，在您的布局中，链接到 default.css 后，向您的自定义风格表添加一个链接。例如，如果您创建 my-custom.css，您可以插入：
```
<link rel="stylesheet" href="/css/my-custom.css" />
```
您不能修改的内置功能包括：
- 分页
- 消息菜单
- 论坛 - 您只能更改布局。
- 支付 - 这些页面中只有几个文本字段可编辑。

1.7. 对于 3scale 管理的 API 允许访问开发人员门户的要求

在授予 API 使用者访问开发人员门户之前，API 供应商必须执行以下任务：这些任务可同时执行：

将 3scale 原生开发人员门户更改为具有您想要的外观和感觉：
- Libiquids：Developer Portal 演示了如何使用 Liquid 标记来显示和处理 3scale 与 API 相关的系统数据。liquid markup 是在 Developer Portal 页面添加逻辑的主要方法。
- 自定义开发人员门户布局描述了如何更改原生开发人员门户使其与您自己的品牌匹配。提供标准级联风格表(CSS)，为您的自定义提供简单的起点。
- 更改内置页面解释了如何使用 CSS 和 JavaScript 在系统生成的页面中修改或隐藏一个元素。作为原生开发人员门户的一部分提供的所有页面都被称为系统生成的页面。
熟悉 HTML、CSS、Liquid 和 web 站点的开发人员可修改原生 Echo API 开发者门户以创建您的开发人员门户。此开发人员可以在系统生成的页面中创建页面并修改代码，以创建您在 Developer Portal 中看到的任何 API 用户。
定义 3scale API 产品、后端和应用程序计划，并为产品分配策略。
3scale 产品是 3scale 资源，使您的 API 公开给消费者。在 Developer Portal 中，API 使用者读取产品文档并订阅使用产品提供的 API。3scale 产品有以下特征：
- 捆绑一个或多个后端，它们是您创建的内部 3scale API。
- 具有定义关于限制、定价和可用功能的产品使用规则的应用计划。
- 具有 APIcast 网关配置，用于在向 API 发送 API 使用者调用前如何处理 API 使用者调用。您添加到产品的策略会改变默认的 APIcast 网关行为。
请参阅管理门户指南。
导入定义并记录 3scale 管理的 API 的 OpenAPI 文档。
开发人员门户的基础是一个 OpenAPI 文档，用于定义您的 API。当您将 OpenAPI 文档导入到 3scale 中时，3scale 会创建或更新 ActiveDoc，以便立即为您的 API 功能文档。在 Developer Portal 中，API 使用者使用本文档来探索、测试并与 API 集成。
对于 OpenAPI 文档中定义的每个操作，导入文档会导致 3scale 创建方法和映射规则。方法和映射规则有助于强制强制对 API 使用者访问的限制和规则。
开发者门户中提供 API 的 3scale 指南包含使用 3scale 和 OpenAPI 文档的信息和流程。特别是，请参阅如何编写 OpenAPI 文档以用作 3scale 规格，并将 ActiveDocs 添加到 3scale。
配置 API 使用者如何注册以访问 3scale 管理的 API 的工作流。
使用您的开发人员门户，注册工作流是 API 消费体验的关键方面。工作流可从自助式服务到对谁获得访问权限的全权控制。帐户、服务和应用计划提供多种级别的粒度。在每个级别，您可以控制是否有您操作的批准授权，以及是否需要 API 消费者作出任何选择。
要获得最大自动化和自助服务，您可以删除所有批准步骤，并启用所有可能的默认计划。在注册后，您的开发人员门户可能会发布一个密钥，它提供您的开发人员门户的 API 使用者访问权限。
原生开发人员门户为用户提供、帐户和应用程序注册的常用字段。您可能需要在这些常用的字段中添加自定义字段。详情请参阅配置注册流和自定义注册表单字段。在自定义电子邮件模板前，请务必配置工作流。
实施 API 使用者身份验证。
对开发者门户的 API 使用者访问权限进行身份验证可保护开发人员门户资源和您的 API。您可以使用以下方法验证对开发人员门户的访问：
请参阅开发人员门户身份验证。
自定义 3scale 原生模板，以获取开发人员门户和 API 用户之间的电子邮件通信。
许多不同的事件需要开发人员门户和 API 用户之间的通信，包括在注册后提供帐户激活链接、密码恢复、服务费用、更改通知等。3scale 提供开发人员门户发送到 API 用户的每个典型电子邮件类型的模板。
在定义了注册工作流后，自定义电子邮件内容。这可让您与为开发者门户设置的工作流匹配。
请参阅电子邮件模板和 Liquids:电子邮件模板。
指定 API 使用者必须同意访问 3scale 管理的 API 的条款、条件和策略。
当您允许 API 用户注册和调用您的 API 时，您通常希望他们在授予访问权限前就您的条款、条件和策略达成一致。如果开发者门户提供多个服务，您可以有不同的术语和条件版本，例如：注册、使用特定应用程序或使用特定服务。
如果您要使用 API，您可能需要同意您的信用卡策略。
请参阅设置术语和条件。
设置 API 消费账单和信用卡网关。
3scale 计费流程每天运行。它为订阅付费服务的每个 API 使用者帐户创建发票。发票可以处于以下状态之一：打开、完成、待定、未付费、已取消、已取消。3scale 使用您配置为处理发票的支付网关。
3scale 计费流程可以在预付或后付模式下运行。3scale 中的计费基于日历月份，在月的第一天会发生特殊事件。
请参阅管理门户指南，Billing。

在 Developer Portal 变为 live 之前，您必须执行最后的任务是删除访问代码。仅在对开发者门户进行身份验证进行身份验证后执行此操作，并在您彻底测试了开发人员门户后，以确认其行为已符合预期。

要删除访问代码，显示 Developer Portal > Content 环境。在右下角，单击 Open your Portal to the world 并确认此操作。

1.8. 为 3scale 管理的 API 自定义开发人员门户的可选步骤

除了为 API 用户打开开发人员门户的要求外，您可能需要执行以下操作：

在开发者门户中提供多个 API。
您导入到 3scale 的每个 OpenAPI 文档为一个单独的 API 产品提供基础，也称为单独的服务。要将开发人员门户配置为提供多个服务，主要任务是创建一个页面，以便 API 消费者选择要订阅的服务或服务。
详情请查看多服务注册。
标记 Developer Portal 页面或页面部分，这只对您指定的 API 用户可见。
您可能需要拥有开发人员门户的一部分，只能被特定的 API 用户组访问。您可以限制对页面的访问、页面的一部分或菜单选择（通常对应于某个部分）。
限制访问部分的方便方式是将每个部分映射到 API 用户的逻辑组。例如，假设存在属于合作伙伴的 API 使用者。您可以创建名为合作伙伴的组，并只授予该组对特定部分的访问权限。
您可以根据状态的变化，为 API 用户提供对受限内容的访问。例如，当 API 使用者升级到新的应用程序计划其他页面时，可能会自动对 API 用户可见。
限制访问的另一种方式是需要 API 使用者才能登录来查看某些内容。
详情请查看限制内容。
实施 webhook。
Webhook 可让您将 3scale 与后台工作流紧密集成。当 3scale 系统中指定事件时，您的后台应用程序可以通过 webhook 消息获得通知。然后，应用程序可以使用这些数据（例如有关新帐户的信息）来填充开发人员门户。
详情请参阅 Webhooks。

1.9. 更新早于 2.8 的 3scale 版本中使用的开发者门户

在 3scale 2.8 中，外部资产从 Content Delivery Networks(CDN)移到 3scale 代码库。因此，从 3scale 2.8 开始，原生开发人员门户是使用 cdn_asset Liquid 标签创建的。如果要从早于 2.8 的 3scale 版本升级，您必须更新开发人员门户以使用带有 cdn_asset 标签的新资产。使用该标签时，从外部网站下载资产不再有依赖项。

先决条件

安装 3scale 2.8 或更高版本
使用 3scale 2.7 或更早版本创建的开发者门户

步骤

在 3scale 管理门户中，带有 Audience > Developer Portal > Content，在资源层次结构的顶部选择，点 </> 仅显示布局：
在布局下，单击 主布局。

在主布局的代码编辑器中，在第 17 行或第 17 行替换这一行：

{{ '//netdna.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.css' | stylesheet_link_tag }}

使用这个行：

{% cdn_asset /font-awesome/4.3.0/css/font-awesome.css %}

在第 19 行中，替换此行：

{{ '//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' | javascript_include_tag }}

使用这个行：

{% cdn_asset /jquery/1.7.1/jquery.min.js %}

向下滚动并单击 Publish。
进入资源层次结构的顶部，点显示部分。
在 Partials 下，单击 stats/chart。

在 stats/chart 的代码编辑器中，在 3 行或第 3 行替换这一行：

{{ '//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/ui-lightness/jquery-ui.css' | stylesheet_link_tag }}

使用这个行：

{% cdn_asset /jquery-ui/1.11.4/jquery-ui.css %}

向下滚动并单击 Publish。
可选。如果根据主布局或基于 stats/chart 部分创建的文件，您必须采用类似更新这些文件。

其他资源

3scale Liquid 参考中的 Liquid drops, tags, and filters

第 2 章自定义注册表单字段

了解如何添加自定义注册字段和有关此功能的不同选项。

默认情况下，3scale 提供用户/帐户/应用程序注册中常用的字段。您可能需要将自己的自定义字段添加到这些常见默认值中。

在管理门户中，进入 Audience > Accounts > Field Definitions，从中可查看默认表单字段并定义新表单字段。

新帐户/用户注册页面实际上是前两个部分的汇总。帐户字段将显示在顶部，后跟用户字段，后跟无需配置的密码字段。

尝试向帐户部分添加 3 个额外字段，即 2 用户注册部分和 1。单击 create，添加以下新字段定义，然后创建它。当然，所需的复选框将使在注册表单上强制使用。还有一些选项可用于使事情隐藏且只读。可能会添加一个隐藏字段，例如，当您需要新注册设置有不需要突出显示的字段时，如 access_restricted_areas，默认情况下为空。作为管理员，您可以稍后逐个用户将其更新为 true。您的页面逻辑可在中读取，以确定要显示的内容。例如，只读字段可能是浏览器位置，您可以在页面加载时使用 JavaScript 进行设置。

现在尝试向用户注册表单中添加下拉菜单。将它命名为"强制类型"。在 options 字段中添加这些逗号分隔的值：全职、部分时间、合同。下拉菜单将填充这些值。

现在，在帐户中添加预定义的字段。通常，您添加的字段不具有系统功能 - 它们只是保存您可在以后访问的数据。（请参阅受限内容。）

正常创建一个字段。然后在"名称"上方的下拉列表中，选择 po_number。通过此字段，发送至此开发人员帐户的 3scale 生成发票上会显示 PO 号。您的管理员可随时覆盖系统生成的字段。为字段取一个名称 - 类似于"PO number" - 并将它创建。

现在来看一下您的工作。您可以看到免费文本姓氏，并将工作类型下拉列表添加到 User 部分。PO 编号系统字段（同时也免费文本）已添加到帐户部分。

最后，这些自定义字段可以使用 3scale ActiveDocs 来设置；例如，应用创建。

第 3 章配置注册流

在本节中，您将看到要配置哪些设置来调整登录工作流。

注册工作流是您通过开发人员门户提供的开发人员体验的一个重要方面。这个过程包括完全自动化和自助服务，以及要求以各种级别全面控制访问对象的人员。

3scale 平台允许您通过组合帐户（可选）、服务（可选）和应用程序计划来为 API 建模。对于每个计划，您可以控制您是否拥有一个审批门。对于每个步骤，您还要确定是否有默认值，或者开发人员需要执行下一步并做出选择。

对于最大自动化和自助服务的极端情况，请删除所有批准步骤并启用所有可能的默认计划。这样，可以在注册后立即发布密钥来提供对 API 的访问。

3.1. 删除所有批准步骤

要删除批准，请转至 Audience > Accounts > usage Rules，然后在 Signup 部分中，确保 选中了 Developers 选项来注册。

另外，如果您启用了帐户和服务计划，请向下滚动页面，并确保在这两种情况下都 直接启用 Change plan:

3.2. 启用所有可能的默认计划

应用计划

另外，如果您启用了帐户和服务计划，也可以为它们选择默认计划

帐户计划（可选）

服务计划（可选）

3.3. 测试工作流

更改所需的设置后，前往开发人员门户以尝试作为新开发人员注册来测试结果。试验并进行必要的调整，以获得适合您的 API 的工作流。当您对工作流程很满意时，最好检查您的电子邮件通知，以确保它们能为您的开发人员提供正确的信息。

第 4 章多服务注册

在本节结束时，您将熟悉创建和自定义多服务注册页面的步骤。

如果您使用多个服务功能，您可以自定义注册程序，以允许客户订阅不同的服务。

4.1. 先决条件

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

强烈建议您阅读有关注册工作流的内容，以便您准备整个设置并了解其如何工作。

4.2. 简介

通过创建新的布局来开始这个过程，它将充当您的多服务注册页面的模板。进入 CMS 系统的 Layouts 部分，再创建新的布局。您可以将它命名为 多服务标记，以便可以轻松地将其与其他布局区分开来。在编辑器中，粘贴标准布局的一般结构（如主页或主布局）。现在删除您不需要的所有内容 - 所有容器、侧栏、附加框等。

在创建了布局的主干后，继续自定义用于注册的代码。

4.3. 多服务注册

4.3.1. 检索有关服务的信息

要检索有关构建正确登录链接所需的服务的所有信息，您必须循环遍历服务对象。服务是模型对象的一部分。

{% for service in provider.services %}
  .
  .
  .
{% endfor %}

4.3.2. 配置注册列

您已拥有访问服务对象的布局和循环。现在决定如何显示有关服务和注册链接的信息。例如，将它们分为若干列，并用服务描述和底部的注册链接来划分。每列都是一个 div 框，其中包含一个 service-column 类，用于包含所有必要的信息。

{% for service in provider.services %}
  <div class="service-column">
    <p>{{ service.name }}</p>
    <p>{{ service.description }}</p>
    .
    .
    .
  </div>
{% endfor %}

内部的容器充当自定义描述字段。service.name 是服务名称，本例中为容器的名称。

4.3.3. 配置订阅

现在，自定义服务注册的主要部分 - 用于创建注册链接，提取注册 URL 和服务 ID。从 URL 的对象以及您在循环中迭代的服务对象获取签名 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 %}
  </div>
{% 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;
}

在这个示例中，我们使用基于百分比的布局在包含 div 的尺寸上动态地分配该列基础的宽度。

现在，您应该已拥有一个正常工作且看好的多个服务订阅页面。恭喜！

如果您想以特定顺序显示列，请尝试使用条件表达式(if/else/case)条件条件表示服务名称或其他您已知的值。

第 5 章开发人员门户身份验证

按照以下步骤配置对开发人员门户的访问。

本文介绍如何启用和禁用开发人员门户上提供的不同类型的身份验证，以便开发人员注册或注册。

目前，3scale 支持多种向开发人员门户进行身份验证的方法，如下部分所述：

用户名/电子邮件和密码
通过 GitHub 进行身份验证
通过 Auth0 进行身份验证
通过红帽单点登录进行身份验证

默认情况下，在开发人员门户中仅启用一种身份验证类型，如果在 3scale.net 上注册了两种身份验证：

用户名/电子邮件和密码
通过 GitHub（使用 3scale GitHub 应用程序）进行身份验证 - 只有在您在 3scale.net 上注册时才会启用。

注意

较旧的 3scale 帐户（在 2015 年 12 月 14 日之前创建）可能需要遵循额外的步骤来启用 GitHub 和 Auth0 身份验证。

如果这适用于您，则需要将以下代码片段添加到登录和注册模板中，以便以两种形式启用此功能：

    {% include 'login/sso' %}

5.1. 启用和禁用用户名/电子邮件和密码

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

然而，在某些个别情况下，您可能想要删除此验证类型。要做到这一点，请按以下屏幕截图所示编辑 Login > New 模板：

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

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）后看到该回调 URL。
测试配置的验证流程是否按预期工作。

5.3. 通过 Auth0 启用和禁用身份验证

5.3.1. 备注

该功能仅适用于企业计划。

为了让开发人员使用 Auth0 进行身份验证，您首先需要具有有效的 Auth0 订阅。

默认情况下，不会启用通过 Auth0 进行身份验证。如果要将 Auth0 帐户与 3scale 搭配使用来管理对开发人员门户的访问，您可以按照以下步骤进行配置：

进入 3scale 管理门户，在 Audience > Developer Portal > SSO Integrations 中点Auth0。

在此配置屏幕上，您需要添加 Auth0 帐户的详细信息。输入客户端 ID、客户端机密和站点后，选中"Published"框并单击 Create Auth0 使其在开发人员门户上可用。

5.4. 通过红帽单点登录启用和禁用身份验证

注意

此功能仅适用于企业计划。

红帽单点登录(RH-SSO)是一个集成式登录解决方案(SSO)，当与 3scale 结合使用时，允许您使用任何可用的 RH-SSO 身份代理和用户联合选项来验证开发人员。

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

5.4.1. 开始前

在将红帽单点登录与 3scale 集成之前，您必须有一个有效的 Red Hat Single Sign-On 实例。有关安装说明，请参阅 Red Hat Single Sign-On 文档：安装 RH-SSO 7.2

5.4.2. 配置 RH SSO 以验证开发人员门户

执行以下步骤配置 Red Hat Single Sign-On：

如红帽单点登录文档中所述，创建一个域。
前往 Clients 并单击 Create 来添加一个客户端。
考虑以下字段和值填写表单：
- 客户端 ID ：为您的客户端键入所需的名称。
- Enabled ：切换到 ON。
- 需要同意 ：切换到 OFF.
- 客户端协议 ：选择 openid-connect。
- 访问类型 ：选择机密.
- 标准流启用 ：切换到 ON.
- 根 URL ：键入 3scale 管理门户 URL。这应该是您用来登录到开发人员门户的 URL 地址，例如： https://yourdomain.3scale.net 或您的自定义 URL。
- 有效的重定向 URL ：按以下方式再次键入您的开发人员门户 ： https://yourdomain.3scale.net/*
  所有其他参数都应留空，或切换到 OFF。
通过以下步骤获取客户端 secret：
- 转至您刚才创建的客户端。
- 单击 Credentials 选项卡。
- 在 Client Authenticator 字段中选择 Client Id 和 Secret。
配置 email_verified mapper.3scale 要求将用户数据的 email_verified 声明设置为 true。要将"电子邮件 验证" 用户属性映射到 email_verified 声明：
- 转到 客户端的映射器 选项卡。
- 单击 Add Builtin。
- 选择 已验证的电子邮件，然后单击 选中的 Add 以保存更改。
  如果您在 Red Hat Single Sign-On 本地数据库中管理用户，请确保该用户的 Email Verified 属性设为 ON。
  如果使用 User Federation，在之前为 3scale SSO 集成创建的客户端中，您可以通过将令牌名称设置为 email_verified 并将 claim 值设置为 true 来配置硬编码的声明。
（可选）配置 org_name 映射器。
当用户以 3scale 进行签名时，要求用户使用 Organization Name 值填写注册表单。要通过 Red Hat Single Sign-On 注册（不需要填写开发人员门户上的注册表），您需要配置额外的 org_name mapper：
- 转到 客户端的映射器 选项卡。
- 点 Create。
- 按如下所示填写 mapper 参数：
  - Name ：键入任何所需名称，如 org_name。
  - 需要同意 ：切换到 OFF.
  - mapper Type ：选择 User Attribute。
  - User Attribute ：键入 org_name.
  - Token Claim Name ：键入 org_name。
  - claim JSON 类型 ：选择 String。
  - 添加至 ID token: 切换到 ON。
  - Add to access token: switch to ON.
  - 添加到 userinfo: 切换到 ON。
  - multivalued ：切换到 OFF。
- 点 Save。
  如果红帽单点登录中的用户具有 org_name 属性，3scale 将可以自动创建帐户。如果没有，系统将要求用户在创建帐户之前指定组织名称。或者，也可以创建类型为 Hardcoded 声明 的映射器，将机构名称设置为所有使用红帽单点登录帐户登录的所有用户的硬编码值。
要测试集成，您需要添加用户。要做到这一点，请导航到 Users，单击 Add user，再填写必填字段。请注意，在红帽单点登录中创建用户时，电子邮件验证属性(email_verified)应设为 ON，否则用户将不会在 3scale 中激活。

使用红帽单点登录作为身份代理

您可以使用红帽单点登录作为身份代理，或将其配置为联合外部数据库。有关如何配置这些配置的详情，请查看 Red Hat Single Sign-On 文档 for identity brokering 和 user federation。

如果您决定使用红帽单点登录作为身份代理，并且希望开发人员能够跳过 RH-SSO 和 3scale 帐户创建步骤，我们推荐以下配置：在提供的示例中，我们使用 GitHub 作为我们的身份提供程序。

在 Red Hat Single Sign-On 中，在在 身份提供程序 中配置 GitHub 后，前往名为 Mappers 的选项卡，再单击 Create。
给它取一个名称，以便您可以识别它。
在 Mapper Type 中，选择 Attribute Importer。
在 社交配置文件 JSON 字段路径 添加公司中，该公司是 GitHub 上属性的名称。
在 User Attribute Name 中，添加 org_name，这正是我们在红帽单点登录中称为属性的方式。
注意
红帽单点登录需要名字和姓氏以及电子邮件作为必填字段。3scale 需要电子邮件地址、用户名和组织名称。因此，除了为机构名称配置映射程序，并让您的用户能够跳过两个注册表单外，请确保：
- 在 IdP 帐户中，它们设置了自己的姓名和姓氏。
- 在 IdP 帐户中，可以访问其电子邮件地址。例如.在 GitHub 中，如果您将您的电子邮件地址设置为私有，它就不会共享。

5.4.3. 配置 3scale 以验证开发人员门户

作为 API 提供程序，配置 3scale 以允许使用红帽单点登录(RH-SSO)对开发人员门户进行身份验证。

注意

默认情况下，不启用通过 RH-SSO 进行身份验证。RH-SSO 仅可用于企业 3scale 帐户，因此您需要要求客户经理通过 RH-SSO 启用身份验证。

先决条件

贵企业 3scale 账户已设置为启用 RH-SSO。
在配置 RH SSO 以验证开发人员门户后，您知道以下详情：
- 客户端 ：在 RH-SSO 中您的客户端的名称
- 客户端 secret ：RH-SSO 中的客户端机密
- realm ：您的 RH-SSO 帐户的域名和 URL 地址

步骤

在 3scale 管理门户中，选择 Audience > Developer Portal > SSO Integrations。
单击 Red Hat Single Sign-On。
指定您在第 5.4.2 节 “配置 RH SSO 以验证开发人员门户” 客户端、客户端 secret 和 realm 中配置的 RH-SSO 客户端的详情。
要保存更改，请点击 Create Red Single Sign-On

第 6 章 Developer Portal 的红帽单点登录

红帽单点登录(RH SSO)允许您管理多个独立系统的访问控制。遵循本指南后，您将能够允许登录到您的系统的用户自动登录您的 3scale 支持的开发人员门户，而无需提示重新登录。

本文介绍了如何使用网站的现有用户凭证自动登录到您的 3scale 支持的开发人员门户。

此功能适用于已拥有其 API 用户身份（用户名和密码）的 API 供应商，比如当 API 供应商也是身份提供程序时。

6.1. 在 3scale 平台中创建用户

首先，API 使用者必须在您的开发人员门户中有一个帐户。您可以使用帐户管理 API 将用户导入到 3scale，或手动创建用户。在管理门户的 3scale ActiveDocs 部分找到帐户管理 API，它位于管理门户的 Documentation（查询标记图标(?)右上角）下） → 3scale API Docs 部分。

6.2. 请求登录链接

用户存在后，您可以使用 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

此调用中有两个参数：username 用于指定您正在请求令牌的人员，以及令牌要过期的秒数，这是令牌的有效秒数（默认为 10 分钟）。

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

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

注意

您可以传递 user_id 或 username 来标识 3scale 用户。通常，您的系统和 3scale 门户的用户名相同。在这种情况下，使用用户名应该很容易，因为它不需要将任何额外信息存储在您的一侧。但是，如果您需要对 URL 进行一些配对和计算机处理，最好使用 user_id。

6.3. 使用自动登录重定向用户

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

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

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

注意

URL 地址需要取消转义。如果要在浏览器中手动尝试，请记得在浏览器中将 &amp 替换为 &amp。此外，令牌中的任何 % 编码也需要替换为其未转义的字符。

第 7 章受限内容

在这里，您可以了解如何在开发人员门户中包含仅对某些用户可见的内容。

您可能需要具有开发人员门户中的一些页面，这些页面只能供特定开发人员组访问，或者是某个菜单中某一页的一部分。通过下列两种技术可实现这两个目标。

7.1. 受限页

创建受限部分时，每个部分都映射到逻辑用户组会很有用。在本例中，假设有一组开发人员称为"合作伙伴"。

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

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

现在，每次需要为您的一个用户授予此部分的访问权限时，您只需将他们分配到此组。为此，请转至对应的帐户详细信息页面，然后转至"组权限"。完成后，选中您要允许的部分框。

7.2. 受限内容块

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

设置了自定义字段后，您现在可以在以下代码片段中将其封装在条件内，从而向合作伙伴显示特殊内容：

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

如果适合您的情况，则使用反向逻辑：

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

从此处开始，每当您想要向用户显示这些隐藏内容时，您只需要在帐户详情页面的合作伙伴字段中键入"true"。

7.3. 自动配置额外的字段

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

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

单击 Documentation，一个位于窗口右上角的问号图标(?)。
选择 3scale API 文档。
检查 Webhook 请求发送的消息，获取将访问受限内容的开发人员的新计划。
根据开发人员的新计划，通过调用 API 来更新 合作伙伴 字段授予对私有内容的访问权限。

7.4. 需要用户登录

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

使用 Liquid 标签非常容易实现。您要做的只是将仅可供登录用户使用的内容嵌套在以下条件中：

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

第 8 章电子邮件模板

在本节结束时，您将编辑和保存自定义电子邮件模板。

您可以与开发人员完全自定义所有标准电子邮件通信的内容，以便您密切匹配为开发人员门户设置的工作流。

8.1. 自定义电子邮件模板

8.1.1. 在电子邮件配置前定义工作流

有很多电子邮件模板选项，只有一部分与您的工作流相关。在开始编辑电子邮件模板之前，确保您对工作流感到十分满意，从而节省您的时间。这样，您只需编辑实际将使用的模板。

8.1.2. 测试您的工作流并确定活跃的电子邮件模板

对已完成的工作流执行空运行，确保测试所有可能的分支（如批准和拒绝）。然后，识别您的测试开发人员帐户收到的每个电子邮件通知，以确定下一步中要编辑的内容。

8.1.3. 编辑并保存自定义模板

首次编辑模板时，实际上您将"创建"自定义模板。然后，在随后的编辑中，您将保存更改。警告：没有版本控制。如果您想恢复更改，我们建议您创建一个本地副本。

您可以将附带标签用于电子邮件中的动态内容。我们尤其建议您在更改弹性标签时进行备份。

8.1.4. 对工作流中的所有模板重复此操作

完成这些相同的步骤，直到您涵盖工作流的所有可能分支。

8.2. 更多信息

在自定义电子邮件模板之前，最好完全完成和测试注册流程。
如果您要更改电子邮件模板中的任何弹性标签，请务必阅读参考文档。

第 9 章智利：开发人员门户

本节介绍 Liquid 格式化标签以及如何在 3scale 系统中工作，包括标记的不同元素、它们之间的连接以及在开发人员门户中如何使用标签的简短示例。

要了解 Liquids 的基本知识，请参阅 Liquid 参考。

9.1. 在 Developer Portal 中使用 Liquids

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

9.1.1. 启用 Liquids

所有部分和电子邮件模板都默认启用移动标记处理。在布局上启用它们的方式是选中 system_name 输入字段右侧的复选框。但是，要在页面上启用它们，您必须进入页面的高级选项部分。

展开 Advanced options 部分并选中 Liquid enabled 复选框。从现在开始，所有颠覆标记将由内部引擎处理，开发人员门户内置的编辑器还将添加代码高亮显示，以便转录。

9.1.2. 页、部分和布局的不同使用

动作的使用通常因页面、部分和布局稍有不同。在页面中，运动是单一使用的元素；而带有部分和布局的则是开发者门户的可重复使用元素。这意味着，您可以添加一些逻辑标签，并根据用户所在的页面更改布局，而不是应用对不同页面的多个布局或部分。

<!-- 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>

9.1.3. 与 CSS/JS 一起使用

移动标记不仅可与 HTML 一起使用，还可轻松将其与 CSS 和/或 JavaScript 代码组合，从而进行更多的控制。要启用样式表或 JS 中的指示，请将其创建为页，并按照您为正常页面启用相同步骤的步骤进行操作。完成后，您将能够在 CSS 中添加一些条件标记，或者在 JavaScript 中使用服务器端数据。只需记得将页面的内容类型设置为 CSS 或 JS。

9.2. 在电子邮件模板中使用动作

本节介绍如何使用弹性标记来自定义电子邮件模板。

9.2.1. Developer Portal 的不同

如前文所述，也可使用弹性标签来自定义发送给您的用户的电子邮件模板。前面提到的所有写作规则同样适用于电子邮件模板，但有些例外：

每个模板中没有可用的常见变量列表。相反，您必须使用前面提到的 {% debug:help %} 标签进行一些测试。
由于电子邮件本质上不同于网页，因此您可以有限或无法访问某些标签。例如，{{ request.request_uri }} 将不合理，因为电子邮件没有 URL。

9.3. 故障排除

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

9.3.1. 调试

如果某个操作无法按预期工作，但保存正确，请检查以下内容：

所有标签都正确关闭
您正在引用当前页面中可用的变量
您没有尝试访问数组 - 例如 current_account.applications 是一组应用程序
逻辑正确

9.3.2. 典型错误及其解决方法

如果因为引发错误而无法保存文档，这通常是因为一些标签或丢弃未正确关闭。检查所有 {% %} 和 {{ }} 标签是否已正确关闭，并且逻辑表达式（例如，如果表示等）已使用 endif 正确终止。通常情况如此，编辑器上面的页面顶部将显示错误，并显示描述性错误消息。
如果保存的所有内容都正确保存且您没有看到任何效果，请检查您没有引用空元素，且您没有使用逻辑标签来显示内容。{% %} 将不会呈现任何内容，除了标签中已经是比较复杂的一组标签和丢弃的别名的标签。
如果只显示 # 符号，这表示您已尝试显示一个数组的元素。检查有关 liquid 层次结构的部分。

9.3.3. 联系支持

如果您仍遇到问题，可以通过红帽客户门户网站打开一个新问题单。

第 10 章智利：电子邮件模板

3scale 提供通过您组织自己的消息传递和术语自定义电子邮件模板的功能。您还可以利用移动丢弃显示每个客户的个性化信息。

与开发者门户中如何使用动作丢弃类似，每个电子邮件模板都有自己的上下文。这意味着，从一个电子邮件模板中提供的动作丢弃不一定可用于其他电子邮件模板。

本参考概述了在哪些地点有变化丢弃，按主题分组的电子邮件模板及其支持的一组易用性丢弃。

10.1. 帐户管理

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

已确认买方帐户
经批准的买方帐户
买方帐户被拒绝

对于这些模板，您可以使用以下操作丢弃：

用户 sample 用户
域 NOT 字符串
帐户 AF 帐户
provider SAS Provider
support_email SAS String

另外，以下模板：

买方的密码恢复
可访问这些转变丢弃：
用户 sample 用户
provider SAS Provider
url ⇒ url

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

邀请
可以访问：
帐户 AF 帐户
provider SAS Provider
url ⇒ url

10.2. 信用卡通知

信用卡过期通知供应商
信用卡过期通知.

您可以使用以下操作丢弃：

user_account SAS 帐户
帐户 AF 帐户
provider_account SAS Provider
provider SAS Provider

10.3. 限制警报

供应商警报通知(>= 100%)
买方警报通知(>= 100%)
供应商警报通知(< 100%)
买方的警报通知(< 100%)

可以访问：

应用程序 svc 应用程序
帐户 AF 帐户
provider SAS Provider
Service sample Service
警报 SAS 警报

10.4. 应用程序

以下电子邮件模板全部处理应用和应用计划通知。

为供应商创建的应用程序

他们可以：

url ⇒ url

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

购买者的计划更改请求
计划供应商更改请求

他们可以：

应用程序 svc 应用程序
provider SAS Provider
帐户 AF 帐户
用户 sample 用户
plan ⇒ Plan
credit_card_url ⇒ credit_card_url

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

买方的应用程序计划已更改
为供应商更改应用程序计划
对于买家的应用程序试用期已过期

他们可以：

provider SAS Provider
帐户 AF 帐户
用户 sample 用户
plan ⇒ Plan

以及上述所有变化丢弃时，以下应用程序计划消息…

为买方暂停应用程序
面向买方的应用程序
申请因买方而被拒绝
为供应商取消的应用程序合同

额外操作丢弃是否列出

应用程序 svc 应用程序
Service sample Service

更多操作会丢弃应用程序密钥的以下电子邮件模板：

为买方创建的应用程序密钥
为购买者删除的应用程序密钥
键 SAS 键

10.5. 开票

以下电子邮件模板…

在收取供应商收费前审核发票

可以访问：

provider SAS Provider
url ⇒ String>

另外，以下 templates…

供应商的发票计费失败，无需重试
买方即将收取的发票
重试后供应商的发票收费失败
对不重试的买家的发票失败
成功向买方收取发票
重试的买方的发票失败

共享以下内容：

帐户 AF 帐户
provider SAS Provider
成本 SAS 成本
invoice_url ⇒ invoice_url
payment_url SAS pay_url

10.6. 服务

以下电子邮件模板：

为供应商的服务合同已取消
对于买方的服务试用期已过期
为供应商更改服务计划
服务合同为买方暂停

可以访问：

provider SAS Provider
帐户 AF 帐户
用户 sample 用户
plan ⇒ Plan

以及上述变化丢弃，以下服务模板…

为供应商创建的服务
为购买者提供的服务
买方的服务拒绝

列出额外的弹性丢弃：

Service sample Service
service_contract SAS 合同
订阅 SAS 合同

10.7. 注册

以下电子邮件模板…

供应商注册通知
买方注册通知

可以访问：

用户 sample 用户
provider SAS Provider
URL SAS activate_url

第 11 章自定义 Developer Portal 布局

您可以自定义整个开发人员门户的外观和感受，以匹配您自己的品牌。提供了标准 CSS 风格表，为自定义提供便捷的起点。要创建布局模板，请使用 major 布局 的代码作为起点。

在本教程中，您将在开发人员门户中添加自己的 CSS 自定义，并重新加载它以使新的风格更改变为现实。

11.1. 创建新的 CSS 文件

有默认的样式表 default.css。这非常大且复杂，因此最好为您自己的定制创建自己的样式表来覆盖默认值，而不是进行扩展。您会按照创建页面的方式创建新样式表（只需在高级页面设置中选择适当的 MIME 内容类型）。

选定布局为空非常重要。否则，页面布局 HTML 将模糊处理 CSS 规则。

11.2. 将样式表链接到您的页面布局

在到 bootstrap.cs 的链接后面添加每个布局模板中的自定义 CSS 链接（或者部分添加 HEAD 部分）。例如：

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

现在享受自己独特的品牌的美好！

11.3. 定义页面布局模板

常规理念是为您的门户中的每个不同的页面风格定义一个单独的布局。启动时有一个名为" 主布局 "的标准布局。在使用 Developer Portal 的专家之前，不要对此布局进行任何更改，因为所有系统生成的页面都使用这个布局。

通常，您希望在门户的主页中唯一风格。Main 布局 模板是您的自定义起点。要创建页面布局模板：

Open Main 布局，并将其代码复制到剪贴板中。
创建新布局，为它指定标题和系统名称，然后选择 "激活 "。
将 主布局 代码粘贴到您的新布局中。
通过从您的新布局中删除此行来删除侧边栏菜单：
```
{% include 'submenu'%}
```
自定义代码以创建布局模板。

第 12 章更改内置页面

在本节结束时，您将能够修改并配置系统生成的页面中任何元素的可见性。

系统生成的一些元素无法从 Developer Portal 修改，如 Signup、Dashboard 和 Account 页面。本指南说明了如何使用 CSS 和 JavaScript 自定义这些页面上的内容。

系统生成的页面遵循后端规则来访问和可见性，因此其 URL 必须特定于并硬编码值。客户门户网站中的知识库文章提供了系统生成的页面及其 URL 列表。

小心

3scale 系统生成的页面可能会有变化（尽管不频繁）。这些更改可能会破坏您遵循本指南实施的任何自定义设置。如果您可以避免使用这些黑客，请这样做。在继续之前，请确保您可以监控是否存在任何破坏性的更改，并进行必要的维护工作来保持门户正常运行。

12.1. 识别元素

首先也是最重要的事情是确定您想要隐藏的内容。为此，请使用 Firebug（或其他开发人员工具，如 Chrome 开发人员工具或 Opera Dragonfly）。选择所需的元素，在控制台中右键单击并选择复制 CSS 路径。这样，您可以保存精确的 CSS 路径，使其易于操作。请记住，如果该元素是边栏导航小部件的一部分，您还必须指定列表中的位置。为此，您可以使用"+"选择器（例如，选择第 3 个元素：ul + li + li + li）或 :nth-child(n)CSS3 伪类。

12.2. 修改或隐藏元素

现在，在确定了元素后，您可以更改它们的显示设置。根据元素的类型，您可以从两种可能的方法中选择：CSS 操作或 jQuery 脚本.CSS 的操作更为轻量、可靠，但不适用于许多页面中存在的某些元素（例如，管理门户仪表板侧边栏中的第 3 个元素也存在于帐户部分，但价值不同）。某些较复杂的实施需要使用 CSS3，而 CSS3 不受旧浏览器的支持。在接下来的两个步骤中，您将看到这两种方法。

12.3. 选项 A：CSS

例如，尝试从 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;
}

12.4. 选项 B：jQuery

如果您有一个比较复杂的元素隐藏，如侧边栏菜单元素，最好使用一些 jQuery。这些元素的 CSS 路径在 Dashboard 和 Account 部分是相同的，您不想在这两个部分中隐藏元素。因此，请根据 CSS 路径和内容选择元素。在本例中，假设您要从控制面板的侧栏中隐藏 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 选择器规格，请在此处查看：

第 13 章设置条款和条件

当您允许开发人员注册您的 API 时，您可能会希望让他们同意您的条款和条件，以便在授予他们访问权限前清除您的一些策略。

您希望开发人员遵守的条款和条件可能有不同的版本。在整个注册过程中，您可以在不同点轻松设置这些设置。例如：

注册条款和条件
应用程序条款和条件
服务/订阅条款和条件（仅在您拥有多个服务时才可用）

另外，如果您要收取使用 API 的费用，您可能需要使信用卡策略明确无误。3scale 提供了一种简单的方式来设置以下类型的信用卡策略 URL：

法律术语
隐私
退款

13.1. 条款和条件

工作流的这一部分可按照以下步骤在管理门户中轻松设置：

进入 Audience > Developer Portal > Signup，您会在其中看到一个空白页面来填充您的注册法律条款。您可以使用 HTML、JavaScript 和 CSS 的任何组合。还可以通过单击 Insert toggling code 提供一些切换代码。您在此框中写入的内容将出现在开发人员门户的 Signup 页面上的 Sign Up 按钮上。

填写了条款和条件后，请单击更新来保存条款和条件。

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

默认情况下，这会放置在 Signup 页面上，但它是一个部分(signup_licence)，它可以包含在 Developer Portal 上的任意位置。要从 Signup 页面删除它，只需从页面中删除 {% include 'signup_licence' %} 行。类似地，如果想在其他位置包含它，可以通过代码片段来使用相同的部分，该片段可以放在 Developer Portal 上的任意位置。

您可能还希望用户在创建新应用程序时接受另一组条款和条件（new_application_licence 部分） 和/或当他们订阅新服务时（service_subscription_licence 部分）。要设置这些设置，您可以按照上面概述的相同步骤进行操作。

13.2. 信用卡政策

您还可以定义位于不同策略的其他 URL。进入 Audience > Billing > Credit Card 策略 并设置您的策略页面位置的路径来设置它们。

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

完成后，您可以使用 URL 的移动丢弃来引用它们。例如：

<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>

就是它！

Language and Page Formatting Options

创建开发人员门户

优秀的开发人员门户必须确保采用您的 API。无需再创建您的密码。

让开源更具包容性

第 1 章 为 3scale 管理的 API 创建开发者门户概述

1.1. 为创建开发者门户提供 3scale 编辑环境

1.2. 修改 3scale 原生开发人员门户

1.3. 修改原生开发者门户的其他 3scale 功能描述

1.4. 3scale 布局和部分重复利用开发人员门户内容

1.5. 在开发者门户中为 3scale 管理的 API 添加镜像和其他资产

1.6. 为 3scale 管理的 API 自定义原生开发人员门户的注意事项

1.7. 对于 3scale 管理的 API 允许访问开发人员门户的要求

1.8. 为 3scale 管理的 API 自定义开发人员门户的可选步骤

1.9. 更新早于 2.8 的 3scale 版本中使用的开发者门户

第 2 章 自定义注册表单字段

第 3 章 配置注册流

3.1. 删除所有批准步骤

3.2. 启用所有可能的默认计划

3.3. 测试工作流

第 4 章 多服务注册

4.1. 先决条件

4.2. 简介

4.3. 多服务注册

4.3.1. 检索有关服务的信息

4.3.2. 配置注册列

4.3.3. 配置订阅

4.3.4. styling

第 5 章 开发人员门户身份验证

5.1. 启用和禁用用户名/电子邮件和密码

5.2. 通过 GitHub 启用和禁用身份验证

5.3. 通过 Auth0 启用和禁用身份验证

5.3.1. 备注

5.4. 通过红帽单点登录启用和禁用身份验证

5.4.1. 开始前

5.4.2. 配置 RH SSO 以验证开发人员门户

5.4.3. 配置 3scale 以验证开发人员门户

第 6 章 Developer Portal 的红帽单点登录

6.1. 在 3scale 平台中创建用户

6.2. 请求登录链接

6.3. 使用自动登录重定向用户

第 7 章 受限内容

7.1. 受限页

7.2. 受限内容块

7.3. 自动配置额外的字段

7.4. 需要用户登录

第 8 章 电子邮件模板

8.1. 自定义电子邮件模板

8.1.1. 在电子邮件配置前定义工作流

8.1.2. 测试您的工作流并确定活跃的电子邮件模板

8.1.3. 编辑并保存自定义模板

8.1.4. 对工作流中的所有模板重复此操作

8.2. 更多信息

第 9 章 智利：开发人员门户

9.1. 在 Developer Portal 中使用 Liquids

9.1.1. 启用 Liquids

9.1.2. 页、部分和布局的不同使用

9.1.3. 与 CSS/JS 一起使用

9.2. 在电子邮件模板中使用动作

9.2.1. Developer Portal 的不同

9.3. 故障排除

9.3.1. 调试

9.3.2. 典型错误及其解决方法

9.3.3. 联系支持

第 10 章 智利：电子邮件模板

10.1. 帐户管理

10.2. 信用卡通知

10.3. 限制警报

10.4. 应用程序

10.5. 开票

10.6. 服务

10.7. 注册

第 11 章 自定义 Developer Portal 布局

11.1. 创建新的 CSS 文件

11.2. 将样式表链接到您的页面布局

11.3. 定义页面布局模板

第 12 章 更改内置页面

12.1. 识别元素

12.2. 修改或隐藏元素

12.3. 选项 A：CSS

12.4. 选项 B：jQuery

第 1 章为 3scale 管理的 API 创建开发者门户概述

第 2 章自定义注册表单字段

第 3 章配置注册流

第 4 章多服务注册

第 5 章开发人员门户身份验证

第 7 章受限内容

第 8 章电子邮件模板

第 9 章智利：开发人员门户

第 10 章智利：电子邮件模板

第 11 章自定义 Developer Portal 布局

第 12 章更改内置页面

第 13 章设置条款和条件