搜索

管理员门户指南

download PDF
Red Hat 3scale API Management 2.12

管理与红帽 3scale API 管理相关的方面。

Red Hat Customer Content Services

摘要

本指南提供管理红帽 3scale API 管理的信息。

前言

本指南将帮助您使用管理门户中可用的功能来管理您的 3scale 安装。

让开源更具包容性

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

部分 I. 帐户设置

第 1 章 帐户配置

创建帐户后,更新有关贵公司的基本信息。设置您所在的地点并添加联系信息。

注意
The account view is only visible to administrators, not to members.

1.1. 添加您的公司信息

创建新帐户后,按照以下步骤添加您的公司信息:

  1. 单击位于顶部导航栏右侧的齿轮图标。您将看到 Overview 窗口。
  2. 帐户详细信息 标题旁边,单击 Edit 链接。
  3. 填写您的帐户信息。

您此处指定的解决方案有两个目标:

  • 如果您正参与付费计划,我们将此地址用于计费目的。
  • 如果您使用计费和付款模块,此地址也是用户在发票上看到的地址。

1.2. 选择您首选的时区

在同一页面上,您还可以选择您将在所有系统上使用的时区。此设置会影响分析图形。但是,账单周期计算按照 UTC 时间进行。

第 2 章 3scale 管理门户的红帽单点登录

本指南提供有关如何通过 3scale 管理门户配置和使用红帽单点登录(RH-SSO)的信息。

2.1. 启用 RH-SSO 或 Auth0 成员身份验证

3scale 支持您的成员和管理员的单点登录(SS0)身份验证。

3scale 管理门户支持以下 SSO 提供程序,各自支持多个身份代理和成员联合选项:

注意

您可以启用多个 SSO 成员身份验证类型

只有已添加到 RH-SSO 或 Auth0 的用户才能通过 SSO 访问您的 3scale 管理门户。如果您希望进一步限制角色或用户组的访问权限,您应该在 RH-SSOAuth0 支持门户上的步骤教程中参考对应的步骤。

通过所选提供程序建立 SSO 后,您必须进行配置并在 3scale 管理门户中启用它。

2.1.1. RH SSO 先决条件

2.1.2. Auth0 先决条件

  • Auth0 订阅和帐户

2.1.3. 启用 RH-SSO

作为管理员,在 3scale 管理门户中执行以下步骤以启用 RH-SSO 或 Auth0:

  1. 确保您的首选 SSO 提供程序(在先决条件中突出显示)已正确配置
  2. 导航到 Account Settings 中的 SSO Integrations:

    • 单击页面右上角的齿轮图标
    • 导航到 Account Settings(齿轮图标) > Users > SSO Integrations,然后点击 New SSO Integration s。
  3. 从下拉列表中选择您的 SSO 提供程序
  4. 输入配置 SSO 时提供的必要信息:

    • 客户端
    • Client Secret
    • realm 或 Site
  5. Create Authentication Provider
注意

如果在测试过程中遇到回调 URL 不匹配,请将错误消息中显示的回调 URL 添加到您的 Auth0 允许回调 URL。

2.2. 通过 3scale 使用 RH-SSO

配置了 SSO 后,成员便可使用连接的 IdP 中的帐户凭据进行登录。

按照以下步骤,使用 SSO 登录 3scale 管理门户:

  1. 导航到 3scale 登录页面:

    https://<organization>-admin.3scale.net/p/login
  2. 使用您的 IdP 授权 3scale
  3. 如有必要,请输入任何所需信息来完成注册

成功注册后,您将在 API 供应商组织下拥有一个 member 帐户,并且会自动登录。

2.3. 将 3scale 登录重定向到 RH-SSO 选项

本节介绍通过 RH-SSO 重定向到身份提供程序(IdP)登录窗口。作为 3scale API 管理管理员,请完成以下步骤,通过可选的单点登录(SSO)登录页面访问 3scale 帐户。

2.3.1. 先决条件

  • 3scale 2.12
  • 按照开发人员门户文档中的配置 RH-SSO 部分所述,配置了 RH-SSO 实例和域。
注意

在您可以将 RH-SSO 与 3scale 集成之前,您必须有一个正常工作的 RH-SSO 实例。有关安装说明,请参阅 RH-SSO 文档:安装 RH-SSO 7.2

2.3.2. 所需的步骤

  1. 访问 并按照 3scale 文档的 3scale 管理门户部分在红帽单点登录下设置 RH-SSO 的说明进行操作。
  2. 为您的 RH-SSO 管理员提供 3scale URL,该 URL 将作为您安全登录的 RH-SSO 中重定向的基础。使用以下 URL 格式:

    https://<organization>-admin.3scale.net/auth/<system_name>/bounce
  3. <system_name> 可以通过管理门户的 SSO 集成详情页面获取:

    https://<organization>.3scale.net/p/admin/account/authentication_providers/<ID>
  4. keycloak_0123456aaaaa 也可以通过 OAuth 流测试字段的 Callback URL 中的 SSO 集成详情页面找到,如下所示:

    https://<organization>.3scale.net/auth/keycloak_0123456aaaaa/callback

第 3 章 邀请用户和管理权限

注意

invite(邀请) 功能仅适用于 Pro 和 Enterprise 客户。

为了共享管理 API 的工作负载,您可能需要邀请您组织的团队成员访问 3scale 管理门户。以下说明描述了如何向一个或多个团队成员授予 3scale 管理门户的访问权限。

通过 用户,我们是指您的团队成员。3scale 管理门户有两种类型的用户:

  • Admins:他们完全可访问所有区域和服务,并可邀请其他成员(如果计划允许)。
  • Members:这些产品对产品领域(如分析、开发人员门户)以及(如果您是企业客户)以及服务的访问权限有限。

如果您从单点登录(SSO)集成创建新的 3scale 用户,则此用户默认具有 member 角色,而不考虑 SSO 令牌内容。3scale 不会将其角色映射到 SSO 角色。

3.2. 发送邀请

从用户列表中,您可以邀请新的团队成员。发送邀请:

  1. 单击位于列表右上角的 Invite user 链接。
  2. 输入您要邀请的人员的电子邮件地址,然后单击 Send
  3. 作为发送的确认,您将在窗口右上角看到一条信息:Invitation was successfully sent..

将向您输入的地址发送邀请电子邮件。如果电子邮件未到达,请确保在收件人的电子邮件帐户中未将其标记为垃圾邮件。

另外,您可以在 Users > Invitations 中找到发送的邀请列表和状态。

3.3. 接受邀请

您的新管理员或成员必须单击邀请电子邮件中的链接,并填写表格以完成该流程。提交表格后,其帐户将被激活。

3.4. 授予新用户权限

您可以为团队成员授予两种主要的权利:

  • 按区域 :例如分析、计费或开发人员管理。
  • 按服务 :选择哪些服务可授予您所有服务中的成员的访问权限。:此功能仅适用于企业客户。

要授予新用户权限,请通过从用户菜单中选择新用户并单击 Edit 来编辑新用户。您有以下用户角色:

  • 更改其 Admin 权限将赋予他们控制管理门户的完整访问权限。
  • 更改Member权利后,您可选择团队成员可访问哪些区域和服务。

    • Member 身份,选择一个区域来列出与上述区域相关的所有可用服务。

授予对管理门户某些区域的访问权限后,成员只能访问等效的 API:

  • 开发人员账户 — Applications:提供帐户管理 API 访问权限
  • 分析:提供对分析 API 的访问
  • 账单:提供对 Billing API 的访问
按地区和服务的权利

第 4 章 通知

通知会发送给管理员和成员,以便更容易解析开发人员活动(新帐户)

4.1. 通知类型

有不同类型的通知:

  • 帐户
  • 账单
  • Applications
  • 服务订阅
  • 使用警报

4.2. 可见性

管理用户有权访问所有通知。

成员用户仅可以访问他们被授予访问权限的区域的通知。例如,如果某一成员有权访问计费部分,则他们只能访问与计费相关的通知。

对于 企业帐户,成员用户只能访问有关已授予访问权限的服务活动的通知。

4.3. 通过电子邮件订阅通知

订阅是个人的,仅可由接收这些通知的人员修改。编辑订阅:

  1. 导航到 Account Settings(导航栏中的 gear 图标) > Personal > Notification Preferences
  2. 选择您要接收的通知。
  3. 单击 Update Notification Preferences

4.4. Web 通知

除了电子邮件通知外,您还可以在仪表板中找到关于最近一次活动的信息:

帐户仪表板

第 5 章 个人设置

在个人设置中,您可以编辑您的首选项作为团队成员。如果您是管理员,您还将能够编辑帐户首选项。为此,请查看 帐户配置 教程。

编辑您的个人设置:

  1. 单击导航栏中的齿轮图标。
  2. 在左侧面板中,导航到 Personal。您可以在这里编辑 3 种类型的设置:

    • 个人详情 :名称、电子邮件、密码等.
    • 令牌 :创建访问令牌以针对 3scale API(账单、帐户管理和分析)进行身份验证,并使用我们的 ActiveDocs(交互式文档)尝试它们。了解有关 3scale 令牌 的更多信息.
    • 通知首选项 :选择您要接收的通知。备注:如果您是企业客户,并且如果您是成员,则根据地区和服务对其进行过滤。这意味着您只能订阅有关已获得访问权限的区域和服务通知。有关通知首选项的更多信息。

第 6 章 令牌

本教程包含有关 3scale 令牌的信息:它们是什么、工作方式以及如何创建它们。

3scale 具有两种类型的令牌:访问令牌 (由用户创建) 和服务令牌 (在 3scale 中创建新服务时自动创建)。

6.1. 访问令牌

访问令牌允许 API 提供程序管理员和成员对 3scale API(账单、帐户管理和分析)进行身份验证,并使用我们的 ActiveDocs(交互式文档)进行尝试。

访问令牌可以提供读写访问权限,或者提供只读访问权限。

要考虑的一个重要事项是访问令牌的工作方式,而这取决于成员的权利。管理员可以创建令牌,以对所有 3scale API 进行身份验证。成员将受限于其访问管理门户不同部分的权限。例如,如果某一成员无法访问 Billing 区域,他们将无法创建令牌来针对 Billing API 进行身份验证。

6.2. 创建访问令牌

可以在令牌页面中创建访问令牌。要创建令牌,请按照以下步骤执行:

  1. 单击导航栏中的齿轮图标。
  2. 导航到 Personal > Tokens
  3. 单击 Add Access Token
  4. 指定名称,选择一个或多个范围,然后选择令牌的权限。
  5. 若要保存新令牌,可单击 Create Access token

请注意,如果您是成员,您可能不会看到所有 API - 只是帐户管理员已授予的 API。

您可以根据需要创建任意数量的访问令牌。出于安全考虑,令牌不会存储在 3scale 中。在创建新令牌时,您将获得保存令牌的警报,以便您可以使用它向 3scale API 发出请求。

如果您丢失了令牌,我们建议将其删除 - 将禁用该令牌并呈现无效 - 然后创建一个新令牌。

6.3. 使用访问令牌

在使用访问令牌对 3scale API 发出调用时,结果将按您可访问的服务过滤。

例如,在部署 APIcast 自我管理时,您需要访问令牌,以便 APIcast API 网关可以使用帐户管理 API 拉取服务配置。

它的工作方式是,如果您的组织在 3scale 上设置了三个服务,并且作为成员,您有权访问服务 1,但不能 2 和 3,并且您也可访问帐户管理 API,当您创建令牌并对帐户管理 API 发出请求时,您只能获取正在使用服务 1 的应用程序。

遵循同一示例,如果您可以访问帐户管理 API,但在进行调用时可以访问零个服务,您将收到"access denied"错误。

6.3.1. 服务令牌

服务令牌用于对 3scale 服务管理 API 进行身份验证。当在 3scale 中创建新服务时,服务令牌会自动生成,并且每个服务都是唯一的。它们由 3scale 帐户的用户共享。

您可以在管理门户仪表板中找到用户可访问的服务令牌:帐户设置(绿色图标) > Personal > Tokens

部分 II. 管理开发人员帐户

第 7 章 添加开发人员

以下是添加新的开发人员帐户以访问您的 API 的步骤。

如果您已将工作流配置为手动邀请开发人员,这涵盖了如何添加新开发人员。

7.1. 创建新开发人员帐户

  1. 遵循管理门户上 Audience 部分中的帐户链接。
  2. Create

作为管理员,您甚至可以跳过一些必填字段。如果要安全地邀请用户访问 帐户,您也可以跳过密码字段。但是,此主要 admin 帐户上的电子邮件必须在所有用户之间唯一。

创建新开发人员帐户

7.2. 设置应用程序

如果要为帐户预配置应用密钥,您也可以代表开发人员添加应用。否则,请将此保留为开发人员要执行的初始步骤之一。

将应用程序添加到新帐户

7.3. 通知开发人员

您可以手动向开发人员发送电子邮件邀请,或者按照步骤使用 邀请开发人员 功能。

第 8 章 批准开发人员

本节介绍如何批准注册工作流中的任何步骤。

当您使用手动批准步骤实施注册工作流后,您有几个选项:审批流程根据触发器和批准的内容稍有不同。如果您收到电子邮件通知,请按照以下部分中的说明操作。否则,它取决于您要批准帐户、服务还是应用程序。

8.1. 接受电子邮件通知的批准

如果您(作为管理员)收到其中一个开发人员有待批准项目的电子邮件通知,您可以将项目的 URL 复制到浏览器中,然后它会把您直接转至页面进行批准。

8.2. 帐户批准

要搜索特定帐户或过滤处于"pending"(用于批准)状态的所有帐户,请导航到 Audience > Accounts > Listing。要仅显示待处理的帐户,请在 State 下拉列表中选择 "Pending", 然后单击 搜索

您可以在每行上直接进行单独批准,或者一次选择几行并执行批量批准。

开发人员批准帐户注册

8.3. 服务批准

要搜索服务的特定订阅或过滤处于 "pending"(用于批准)状态的所有订阅,请导航到 Audience > Accounts > Subscriptions

要查看订阅,请在 Audience > Accounts > usage Rules 中启用服务计划。

您可以一次选择一个订阅或多个订阅并执行批量批准。

开发人员批准服务订阅

8.4. 应用程序批准

搜索应用程序或过滤处于"待处理"(用于批准)状态的所有应用程序:

  1. 导航到 Audience > Applications > Listing
  2. State 下拉列表中选择 "Pending", 然后单击 搜索

您可以一次选择一个应用程序或多个应用程序并执行批量批准。

开发人员批量批准应用程序

您也可以从开发人员帐户的详情页面开始,选择您要从那里批准的应用程序,然后对应用程序详情页面进行批准。

开发人员单个应用程序批准 1
开发人员单个应用程序批准 2

第 9 章 更改应用程序计划

在本节后,您将能够更改帐户、服务或应用的计划。

作为管理员,您可以随时更改开发人员的计划,或更改开发人员发起的计划更改请求。

注意

根据正在更改的计划类型,变更计划步骤略有不同。

9.1. 更改帐户计划

要搜索或过滤特定的帐户,请导航到 Audience > Accounts > Listing

您可以一次选择一行或多行,然后更改计划。

开发人员更改帐户计划

9.2. 更改服务计划

要搜索或过滤服务的特定订阅,请导航到 Audience > Accounts > Subscriptions

只有在 Settings 页面中启用了 Service Plans 时,才可查看订阅。

您可以一次选择一个或多个订阅,并更改计划。

更改服务计划

9.3. 更改应用计划

要搜索或过滤特定应用程序,请导航到 Audience > Applications > Listing

您可以一次选择一个或多个应用程序,并更改计划。

为多个应用程序更改计划

另一种场景是从开发人员帐户的详情页面开始。从那里您选择要更改计划的应用程序。在应用程序详情页面上,您可以更改计划。

更改应用程序计划

9.3.1. 更多信息

如果不需要更改到其他标准计划,您只想更改一个特定的应用,您可以使用 自定义计划 功能。

第 10 章 联系开发人员

本指南说明了如何确定哪个开发人员帐户管理特定的应用,然后通过 3scale 和外部与它们通信。

在 API 操作期间,您可能需要联系使用 API 的开发人员。

10.1. 在系统中找到相关的应用程序和帐户

如果您已经知道管理相关应用的帐户和开发人员,请在 Audience > Accounts > Listing 的 Accounts 页面中导航至其帐户,如下所示。

帐户视图

如果您只具有应用程序 ID 或 API 密钥,您可以使用 Audience > Accounts > Listing 中的 Accounts 页面中的搜索框来查找相关帐户。有关查找应用程序的更多信息,请访问 此处

10.2. 向开发人员发送内部消息

在帐户配置文件页面中如下方所示,单击消息图标。

发送消息

此处创建的消息将同时发送到帐户系统仪表板,帐户中的所有开发人员都将看到该仪表板,并通过通过电子邮件发送给开发人员帐户中具有管理员状态的人员。

10.3. 通过其他方法联系

如果紧急情况和电子邮件不太可能足够快用于您的目的,您还可以使用注册时开发人员提交的联系信息,该信息可以:

  • 在公司账户页面(一般联系信息,但可能包括电话号码)
  • 关于用户自己文件的开发人员/用户特定信息

请注意,注册后,您可以将联系人电话号码填写为必填字段。

第 11 章 自定义计划

完成本节后,您将为特定开发人员自定义应用计划。

应用程序计划是将标准策略应用到开发人员社区的不同部分的好方法。但是,您始终能够灵活地为具有唯一要求的任何个人开发人员自定义标准计划。

定制计划后,您将丢失到原始计划的链接。如果您更改原始计划,自定义计划不会继承任何这些更改。因此,您应该小心使用这种自定义功能,然后再使用太多无法有效管理的自定义计划。

开发人员希望在不升级到下一个定价层的情况下增加其当前的限值,因为当前账单周期已在进行中。通过增加限值和仅收取变量成本,自定义可能是一种解决这种情况的好方法。这还有助于促进以下账单月的升级:

11.1. 选择帐户

查看您感兴趣的开发人员帐户详情页面:

  1. 导航到 Audience > Accounts > Listing
  2. 选择 Developer 帐户
选择帐户

11.2. 选择应用程序

选择您要自定义的计划应用程序。

选择应用程序

11.3. 自定义应用计划

选择"自定义"选项。这提供了 页面,您可以在其中为此帐户拥有的应用自定义所有计划元素。

自定义计划

11.3.1. 更多信息

在执行此步骤自定义计划之前,请先考虑是否与新的标准计划(可以在开发人员门户中显示时隐藏)上的更好效果。然后,您只需 更改标准计划 即可获得重复使用的好处(如果这适用于多个开发人员合作伙伴)。

第 12 章 启用注册

通过实施自助服务或手动模式来配置开发人员注册。

您可以配置工作流,使开发人员能够自助服务,或者仅通过手动邀请进行。自助服务注册由开发人员通过开发人员门户完成,而手动邀请则由您的管理员通过管理门户来处理。

默认情况下,开发人员自行启用注册。如果启用了开发人员自助服务,则需要管理员批准后才能激活开发人员帐户。

要做到这一点,请导航到 Audience > Accounts > Settings > Usage Rules

启用自助服务开发人员注册

第 13 章 查找应用程序

在本指南结束时,您将能够根据其名称、API 密钥或应用标识符在管理门户中快速查找应用。

在 API 操作期间,您可能需要查找关于正在快速访问 API 的应用的信息 - 无论是出于支持目的,还是为了更改配置,或者因为应用行为不当且需要禁用。

13.1. 获取您需要的信息

要查找应用程序,您需要其所属帐户的名称或应用程序的名称。如果您没有此信息,您可以验证访问日志。要执行搜索,请导航到 Applications(Audience > Applications > Listing)。

如果按标识符搜索验证类型,您需要以下信息:

  • 对于 API 仅键验证模式:API 键
  • 对于应用程序 ID 和应用程序密钥验证模式:应用程序标识符(不支持通过应用密钥进行搜索)
  • 对于 OpenID Connect 身份验证模式: client_id(不支持对 secret 进行搜索)

13.2. 搜索应用程序

要搜索给定应用程序,请导航到 Applications 页面(Audience > Applications > Listing),并使用以下镜像所示的搜索框。

查找应用程序第 1 部分.

13.3. 访问应用程序信息

返回结果后,单击您要访问的应用程序,然后您将进入该应用程序的主页,其中包括如下图中所示的信息。

查找应用程序第 2 部分

第 14 章 邀请开发人员

完成这些步骤后,您将向开发人员帐户添加新的开发人员用户。

在手动创建开发人员帐户时,您可以通过管理门户邀请开发人员用户访问该帐户:

  1. 进入 Audience > Accounts > Listing
  2. 选择涉及的帐户。
  3. 选择"安装",然后单击 Invite user
开发人员邀请用户

第 15 章 从服务取消订阅开发人员

作为管理员,您可以取消订阅服务的开发人员。如果服务已弃用,您可能需要为一个特定的开发人员或多个开发人员执行此操作。

15.1. 从服务取消订阅单个开发人员

从他们通过管理门户订阅的服务中取消订阅单个开发人员:

  1. 在 Admin Portal 的 Dashboard 中,导航到 Audience > Accounts > Listing > [select a account] > Service Subscriptions
  2. 为您要从中删除开发人员的服务选择 Unsubscribe

15.2. 从服务取消订阅多个开发人员

执行批量操作,从已弃用或删除的服务中取消订阅多个开发人员:

注意

这个方法只适用于已删除或暂停的服务。您无法对活动服务执行批量取消订阅操作。

  1. 在 Dashboard 中,导航到:Audience > Accounts > Subscriptions
  2. 进行批量状态更改。
  3. 使用服务下拉菜单,确定您要取消订阅开发人员的服务。
  4. 使用左侧的复选框,选择您要取消订阅的开发人员。
  5. 选择 Change State > Suspend 来挂起所选开发人员订阅。

请记住,需要启用服务计划。

第 16 章 挂起应用程序

本指南说明了如何为应用禁用所有密钥和访问令牌。

如果应用滥用您的 API 并影响其他流量,您可能需要在联系涉及的开发人员之前迅速暂停其操作,以要求他们修改代码或配置。

16.1. 查找应用程序

您可以从 帐户 或应用程序选项卡找到 应用程序,或者按 此处 所示搜索。

16.2. 禁用应用程序

找到应用程序并查看应用程序摘要页面后,点击"状态"值旁边的挂起图标。此操作将立即从 API 禁用应用,并暂停所有密钥正常工作。控制系统将拒绝使用这些应用密钥的调用。

修改有问题的行为后,可以使用同一按钮取消暂停应用。

挂起应用程序
注意

如果您在代理中使用缓存,则暂停可能不是即时的,而是需要简短的超时。

16.3. 联系开发人员

如何联系应用的开发人员将依赖于您的工作流和策略。在同一页面中,您可以单击帐户名称,该名称将使您进入帐户视图,从中可以识别拥有该应用的帐户的关键管理员。您可以通过电子邮件或单击显示的发送消息按钮联系他们,这将为用户生成仪表板消息。

联系开发人员

第 17 章 取消应用程序

要通过管理门户删除应用程序,您需要按照以下步骤执行:

选项 1 :从 [Your_API_name] 的所有应用程序列表中删除应用程序。

  1. 在控制面板中,单击 [Your_API_name]
  2. 单击 Overview 选项卡。
  3. Overview 页面的左侧面板中,单击 Applications
  4. 选择 Listing
  5. 单击某个应用程序。
  6. 您将看到包含应用详细信息的页面。点 Edit
  7. 若要删除应用,可单击 Delete
  8. 您将看到确认消息。单击确定 以确认删除。

选项 2 :根据特定应用计划删除应用。

  1. 在管理门户中,点 Dashboard
  2. 选择 API
  3. 发布的应用程序计划 下,选择一个应用程序。
  4. 单击某个应用程序。
  5. 您将看到包含应用详细信息的页面。点 Edit
  6. 若要删除应用,可单击 Delete
  7. 您将看到确认消息。单击确定 以确认删除。

或者,您还可以通过 3scale API Docs 删除应用,以及名为 Application Delete 的操作。

第 18 章 删除 API

您可以通过删除其服务来删除 API。删除服务会移除 API 的应用、应用程序计划、指标、定价规则、功能、服务计划和订阅。

删除 API:

  1. 导航到 [Your_product_name] > Overview > Edit
  2. 在 Service delete 部分中,单击链接以删除该服务。

部分 III. Access control

作为 3scale API 提供程序,您可以通过指定方法控制对 API 的访问,方法是:指定方法捕获各个使用详情、定义指标、将方法和指标与映射规则关联,以及创建设定价格和使用限值的应用计划。应用计划使用为方法和指标收集的数据来强制实施使用量限制。

第 19 章 指定方法并添加用于捕获使用详情的指标

应用程序计划为消费者访问 API 设置限制和定价规则。要启用限制和规则的执行,请在 API 中指定方法,用于收集单个使用量数据或添加指标。为每个指定方法和每个自定义指标添加一个映射规则。映射规则指定要捕获的使用情况数据的详情。

您可以为产品和后端指定方法或添加指标。对于产品,这能够在产品的应用计划中设定限制和定价规则。对于后端,这会为捆绑该后端的任何产品在应用程序计划中设置限制和定价规则。

指定捕获单个调用数量的方法。这为跟踪 API 的使用提供了更精细的粒度。向方法报告流量会自动增加方法和 Hits 指标的计数器。您可以为 API 后端的每个端点指定方法,或者端点和 HTTP 方法的组合。请参阅 Adding map 规则到方法和指标,以了解如何将 API 的端点映射到此处添加的方法。

指标可用于跟踪产品和后端的 API 使用情况。hits 是每个 API 存在的内置指标。它跟踪对您的 API 的调用数量。要捕获 Hits 之外的 API 的使用,请定义一个以不同单位报告使用的指标。单元应该可扩展,并对您的业务目标(如兆字节、CPU 时间或 API 返回的元素数量)具有意义。默认不提供 Hits 以外的指标,如 CPU 时间或 mb。使用由用户配置的外部服务调用的端点来获取这些指标。

方法和指标是打包 API 的构建。通过每个应用程序计划,您可以为每个指定方法和每个指标定义不同的使用限值和定价规则。请参阅 API 分析,以了解更多有关指标和方法报告的使用情况的信息。

19.1. 在产品和后端中添加方法

向产品或后端添加方法意味着您要在 API 中指定您想要捕获各个使用详情的方法。应用计划为您提供了为您添加到产品或后端的每种方法设置限制的功能。将方法或指标添加到产品的过程类似于向后端添加方法或指标。

步骤

  1. 导航到 [Your_product_name] > Integration > Methods & Metrics[Your_backend_name] > Methods & Metrics
  2. 单击 Add a method
  3. Friendly name 字段中,输入方法的简短描述。此名称显示在 3scale 管理门户的不同部分中。对产品而言,友好名称必须是唯一的。

    重要

    在更改方法的系统名称或删除它们时,请小心。如果有指向方法先前系统名称的映射规则,这些更改可能会破坏您已部署的 3scale 集成。

  4. System name 字段中,在 API 中输入方法名称,以用于通过 3scale Service Management API 报告使用情况。

    您决定系统名称的格式。此名称可以和端点(/status)类似,或者可以包含方法和路径(GET_/status)。但是,系统名称必须符合这些规则:

    • 产品或后端中的唯一
    • 仅包含字母数字字符、下划线 _、连字符 - 或正斜杠 /
    • 无空格
    • 对于后端 API,系统名称包含一个数字字符串,用于标识它们所映射到的后端。您无法修改此后端标识符。
  5. 可选:在 Description 字段中,输入方法的更详细描述。
  6. 单击 Create Method

验证步骤

  • 添加的方法在应用计划中可用。

后续步骤

  • 进入 [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit] 来编辑每种方法的限制和定价规则。

19.2. 在产品和后端中添加指标

添加指标指定您要捕获到 API 的所有调用的使用单元。应用计划提供了为添加到产品或后端的每个指标设置限值的功能。将方法或指标添加到产品的过程类似于向后端添加方法或指标。

步骤

  1. 导航到 [Your_product_name] > Integration > Methods & Metrics[Your_backend_name] > Methods & Metrics
  2. Metrics 选项卡。
  3. Add a metric
  4. Friendly name 字段中,输入指标的简短描述。此名称显示在 3scale 管理门户的不同部分中。对产品而言,友好名称必须是唯一的。

    重要

    在更改指标的系统名称或删除它们时,请小心。如果有指向指标先前系统名称的映射规则,这些更改可能会破坏您已部署的 3scale 集成。

  5. System name 字段中,在 API 中输入指标名称,以用于通过 3scale Service Management API 报告使用情况。

    您决定系统名称的格式。但是,系统名称必须符合这些规则:

    • 产品或后端中的唯一
    • 仅包含字母数字字符、下划线 _、连字符 - 或正斜杠 /
    • 无空格
    • 对于后端 API,指标的系统名称包含一个数字字符串,用于标识它们所映射到的后端。您无法修改此后端标识符。
  6. 单元 字段中,输入单元。

    • 使用单点名词,例如 hit。单数将变为分析图表中的复数。
  7. 可选:在 Description 字段中,输入更为详细的指标描述。
  8. 单击 Create Metric

验证步骤

  • 添加的指标在应用程序计划中可用。

后续步骤

  • 前往 [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit] 来编辑每个指标的限制和定价规则。
  • 进入 [Your_product_name] > Integration > Mapping Rules,将指标映射到一个或多个 URL 模式。请参阅 Adding map 规则到方法和指标

19.3. 导入方法和指标的替代方案

如果您的 API 有多个端点,可以通过两种方式自动指定方法并将指标添加到 3scale 产品和后端:

19.4. 添加映射规则到方法和指标

映射规则是映射到之前在产品和后端中创建的方法指标的操作。

注意

之前创建的方法中需要映射规则,但对于指标数据是可选的。

步骤

  1. 导航到 [Your_product_name] > Integration > Mapping Rules
  2. Create mapping 规则
  3. Verb 字段已预先填充 HTTP 方法 GET,但您可以从下拉列表中选择其他选项。
  4. Pattern 字段中,添加一个以正斜杠 / 开头的有效 URL。URL 可以来自您在大括号 {} 中指定的通配符。
  5. Metric 或 method to increment 字段中,从之前创建的方法或指标之一中进行选择。
  6. Increment by 项会预先填充 1,但您可以根据自己的具体情况进行修改。
  7. Create mapping rule 按钮。

验证步骤

  • 要验证映射规则,请导航到 [Your_product_name] > Integration > Methods & Metrics。每一方法和指标在映射列中应具有一个复选标记。

19.5. 其他资源

第 20 章 应用计划

应用计划定义了您可能要允许的 API 用户的不同访问权限集。它们可以决定速率限值中的任何内容,哪些方法或资源可以访问以及启用了哪些功能。

20.1. 如何创建应用程序计划

默认情况下,当创建 3scale 帐户时,会为您提供两个计划:基本和无限。您可以保留并编辑这些设置,也可以自行创建。您可以根据需要创建更多计划。

要创建新应用程序计划,请按照以下步骤执行:

  1. 进入 [Your_product_name] > Applications > Application Plans
  2. 单击 创建应用计划 按钮。
  3. Create Application Plan 页面中,为您的新计划输入名称和系统名称(系统名称必须是唯一的)。
  4. 如果您要在访问 API 之前要求应用程序获得批准,请选择 Applications require approval? 复选框。

创建计划后,您可以调配 速率限值 并设置 支付计划

20.2. 设置默认应用程序计划

创建完所有计划后,您可以在注册应用程序的人员选择默认计划。

选择默认应用程序计划:

  1. 进入 [Your_product_name] > Applications > Application Plans
  2. Default Plan 下的下拉列表中选择一个计划。

如果没有指明默认的应用计划,当新用户签名以访问您的 API 时,默认情况下不会创建应用程序。换句话说,用户将无法访问您的 API。

第 21 章 调配付费计划

使 API 货币化的一个最常见方法是根据使用情况定义订阅费用,无论是产品还是后端。本节重点介绍如何使用应用计划调配定价层以及如何设置付费计划。还可以在帐户、产品和后端级别应用定价规则 - 这些主题在高级指南中介绍。

21.1. 决定您的定价模式

第一个决策是区分定价模式中的分层。层可以由卷或使用情况、API 功能、对其他资源的访问或这些资源的组合驱动:

  • 卷/使用情况.区分不同分层的最常见方法是基于卷,因为卷通常与客户的值以及服务成本紧密相关。您可以对产品调用应用全局点击数,或在方法级别上更精细地测量。卷驱动程序 在全局 hits 指标级别或按键下的单个方法应用。多个定价规则可应用于任何指标。请注意,点击计算用一个月的计费周期累计。
  • 功能.您可以根据层启用或禁用对产品部分的访问。这是区分标准和高级的好方法。
  • 资源.您还可以根据对为客户提供值的其他资源的访问来创建层,或者驱动基础架构中的成本 - 例如,已消耗的千兆字节的带宽、用户数或事务值。资源驱动程序 与卷驱动程序类似,但应用于自定义指标。

在决定价格驱动程序后,您必须确定是否基于平板费率订阅、可变费率或一次性前期收费。上述所有三个定价驱动程序均与一个脱机或每月平价订阅兼容。如果您根据点击量或资源消耗决定您的定价,那么您的定价当然会有一个可变因素。

21.2. 使用您的定价规则配置应用程序计划

您可以创建新应用计划或编辑现有应用程序计划。在创建新应用程序计划时,您可以输入任何前期费用或无格式费率订阅。

创建新应用程序计划或编辑现有应用程序

在编辑应用程序视图中,您可以输入或修改前期收费和订阅。

接下来,设置您在 第 21.1 节 “决定您的定价模式” 中选择的定价驱动程序:

  1. 进入 [Your_product_name] > Overview > Applications > Application Plans
  2. 单击应用计划名称。
  3. 转至 指标、方法、限值和定价规则。此处的定价可以按照总点击量、方法粒度或任何自定义指标来定义。

如果其中一些已作为指标存在,您可以编辑该项目。

完成设置定价规则后,单击 更新应用程序计划

21.3. 创建进一步的定价层

您可以使用单个应用计划定义 API 付费计划。通常,如果所有定价规则都由卷或资源驱动程序定义,则情况通常是如此。但是,如果您要为开发人员社区的不同部分提供单独的计划,请添加更多应用程序计划。

执行此操作的最简单方法是从应用计划概览页面复制第一个应用计划。这样,它将预先填充所有现有的指标和定价规则。第一次创建完整计划时,计划复制功能的保存时间就越高。

21.4. 配置付费计划

为了调配计划,开发人员必须创建新应用程序并选择新付费计划之一。您还可以从管理控制台代表他们执行此操作。对于任何现有应用程序,还可以从现有计划更改为新付费计划之一。

21.5. 其他参考资源

与扁平化定价计划相结合,通常使用速率限值来区分不同的分层。这在 规定速率限值中解释

第 22 章 置备速率限制

速率限制允许您限制对 API 资源、产品和后端的访问。您可以使用应用计划为不同的开发人员段配置不同的限值。

达到速率限值后,这些限制将控制开发人员在向 3scale 后端发出授权请求调用时收到的响应。

22.1. 配置应用程序计划

如果您尚未定义应用计划,请首先创建一个。否则,请选择您要为 设定速率限值的计划,然后单击 edit

有关创建应用程序计划的详情,请参阅 应用程序计划

22.2. 设置速率限值

设置速率限值:

  1. 进入 [Your_product_name] > Overview > Applications > Application plan
  2. 点击您要配置的应用程序计划的名称。
  3. 向下滚动到 Metrics, Methods, Limits and Pricing Rules
  4. Limits
  5. 配置产品或后端级别的限制。
  6. 当您完成设置所需的限值后,点 Update Application plan 保存您的更改。

22.3. 将新速率限制置于操作中

现在您已经定义了速率限值,现在会出现以下情况:

  • 如果您已经配置了警报,将使用新的限制来决定通知的发送时间。
  • 当您超过 3scale 后端的调用数时,会考虑限制,您会看到相关的错误消息。有关 APIcast 错误消息的详情,请参阅配置错误消息

当您的速率限制正常运行后,您会看到达到仪表板限制的用户,以便快速轻松地检查潜在计划升级候选者。如需有关软限制和硬限制的更多信息,请参阅使用 高级路径配置 API 访问策略 中的入门指南

22.4. 更多信息

除了设置速率限制外,您还可以为同一指标设置变量定价规则 - 请参阅 置备已付计划

部分 IV. 账单

第 23 章 配置 Billing 设置

本文档描述了 Billing 功能如何在红帽 3scale API 管理中工作。

账单设置划分为计费 网关信用卡政策,两者均可在管理门户的 Audience > Billing 中找到。

23.1. 计费模式(收费和网关)

3scale 的账单基于日历月份,可以 预先支付支付

  • 在预付模式下,所有固定费用和设置费用均在月份开始时计费,或者在任何代理账单期开始时计费。变量成本始终在下月的开始计算和计费。
  • 在美元支付模式下,所有固定费用及可变成本将在下个月开始计费。

如需更多详细信息,请参阅自动计费流程

23.2. 启用计费(收费和网关)

此设置可启用信用卡交易。出现此设置时,将通过选定的支付网关收取所有到期发票的费用。如果您关闭此设定,将开具账单并发出发票,但不会进行实际付款交易。

23.3. 货币(收费和网关)

选择进行计费和信用卡交易的货币。请确定您的支付网关支持选定的货币。此设置是全局的,适用于所有发票和交易;无法为不同的开发人员帐户设置不同的规定。

23.4. 发票注脚(计费和网关)

每张 PDF 发票的底部会显示在 Invoice footnote 字段中介绍的文本。您可以使用此字段为您的客户提供有关计费和计费策略的附加信息。

如果更改了 footnote 的文本,则它不会自动应用到已生成 PDF 的发票。但是,可以通过重新生成 PDF 发票来应用更改。

23.5. 文本显示 VAT/Sales Tax 是否为 0%(收费和网关)

此字段用于向 PDF 发票中添加文本消息,以防 VAT/ Sales Tax 为 0% 的帐单帐户。仅当 VAT/ Sales Tax 明确设置为 0 时,才会显示此行,否则不会显示该行。此文本也将显示在管理门户的 Invoice 页面上。

有关此设置的更多信息,请参阅 VAT/ Sales Tax 部分

23.6. YAML 配置

借助 currencies.yml 文件,您可以为 3scale 部署配置一个货币列表。3scale 使用基于 ISO 4217 的三字母货币代码。

重要
  • 确保付款网关支持选定的货币。
  • 3scale 与信用卡交易的以下支付网关集成:

    • Braintree
    • Stripe

23.6.1. 更改 OpenShift 中的区域配置

要更改配置,请执行以下操作:

步骤

  1. currencies.yml 内容添加源作为 system 配置映射。以下示例演示了如何为默认的货币列表添加一个额外的货币ARS - Argentine Peso

    oc patch configmap system --type merge -p "{\"data\": {\"currencies.yml\": \"production:\n  'USD - American Dollar': 'USD'\n  'EUR - Euro': 'EUR'\n  'GBP - British Pound': 'GBP'\n  'NZD - New Zealand dollar': 'NZD'\n  'CNY - Chinese Yuan Renminbi': 'CNY'\n  'CAD - Canadian Dollar': 'CAD'\n  'AUD - Australian Dollar': 'AUD'\n  'JPY - Japanese Yen': 'JPY'\n  'CHF - Swiss Franc': 'CHF'\n  'SAR - Saudi Riyal': 'SAR'\n  'ARS - Argentine peso': 'ARS'\n\"}}"
    注意

    要查看 currencies.yml 配置文件的内容示例,请访问默认的 YAML 文件:currencies.yml。该文件显示新的 3scale 部署的默认配置:

    base: &default
      'USD - American Dollar': 'USD'
      'EUR - Euro': 'EUR'
      'GBP - British Pound': 'GBP'
      'NZD - New Zealand dollar': 'NZD'
      'CNY - Chinese Yuan Renminbi': 'CNY'
      'CAD - Canadian Dollar': 'CAD'
      'AUD - Australian Dollar': 'AUD'
      'JPY - Japanese Yen': 'JPY'
      'CHF - Swiss Franc': 'CHF'
      'SAR - Saudi Riyal': 'SAR'
    production:
      <<: *default
    preview:
      <<: *default
  2. system-(app|sidekiq) DeploymentConfigsystem-config 卷中包括新的 ConfigMapcurrencies.yml。这将在相关容器内挂载新内容并激活新配置。

    export PATCH_SYSTEM_VOLUMES='{"spec":{"template":{"spec":{"volumes":[{"configMap":{"items":[{"key":"zync.yml","path":"zync.yml"},{"key":"rolling_updates.yml","path":"rolling_updates.yml"},{"key":"service_discovery.yml","path":"service_discovery.yml"},{"key":"currencies.yml","path":"currencies.yml"}],"name":"system"},"name":"system-config"}]}}}}'
    oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES
    oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES
    unset PATCH_SYSTEM_VOLUMES

23.6.2. 验证新国家

要验证 3scale 管理门户中是否包括了这个问题,请执行以下操作:

步骤

  1. 前往 Audience > Billing > Charging & Gateway
  2. 检查 Currency 下拉列表中是否包括了相应的列表。
  3. 选择您要使用的货币.

23.7. 发票 ID(计费和网关)的计费期间。

3scale 中的发票有两种标识符:

实际 ID
唯一标识数据库中的发票。这是一个数字 ID,显示在发票 URL 中(即 https://<dashboard_domain>/buyers/accounts/<acount_id>/invoices/<invoice_id>),在 Billing API 中用作发票 ID。
友好 ID
显示在发票上,是用户友好的标识符。对于每个 3scale 帐户应是唯一的,尽管在技术上可以具有重复友好的标识符。如果 3scale 识别重复标识符,您会看到类似如下的警告信息:This invoice id is already in use and should probably be changed.如果友好标识符显示为 fix 的时间超过 24 小时,请联系支持。

此设置定义了发票 Friendly ID 的格式:

monthly(默认)
YYYY-MM-XXXXXX,即 ID 包括年、月和发票编号。Example:2018-02-00000013
yearly
YYYY-XXXXXXXX,即仅包括年和发票编号。Example:2018-00000001

将发票识别符的计费期从 monthly 改为 yearly 的唯一影响是更改友好的标识符格式。此修改不会更改计费周期。3scale API 管理仅支持每月账单。如果您的会计部门有此要求,则可以按年将发票格式改为每年。

如果您每年需要向客户收取计费费用,则需要手动处理计费 - 您可以创建新发票并添加具有年度成本的行项。如果您更喜欢使用年费,您可能还希望将应用程序计划设置为免费,以确保每月自动生成发票和/或自动收取发票。

23.8. 信用卡政策

您可以在此处配置指向以下页面的路径:

  • 法律条款页面
  • 隐私页面
  • 退款页面

第 24 章 用于付款的信用卡网关

作为 3scale API 提供商,定义信用卡的支付网关,以货币化 API 订阅。

24.1. 3scale 支持的信用卡网关

3scale 与信用卡交易的以下支付网关集成:

  • Braintree
  • Stripe

在线支付服务必须在收集信用卡数据时显示强制要求。规定是客户授予您借出其支付方式的权限记录。规定应明确表明,提供的支付方式将用于收集随后的服务付款。有关 stripe 和 Braintree 要求的更多信息,请参阅 其他资源 下面列出的相应支付网关的外部文档链接。

其他资源

24.2. 将 Stripe 配置为信用卡网关

作为 3scale API 提供程序,配置管理门户和开发人员门户,将忽略作为付款网关,以通过使用条带作为信用卡网关从订阅中接收 API 付款。

先决条件

  • 您必须有一个 Stripe 帐户。

    • 条带建议您为每个业务或项目使用单独的 Stripe 子帐户。
    • 有关 多个帐户,请参阅 Stripe 文档。
  • 您必须具有 Stripe 管理员权限。

步骤

要将 3scale 配置为使用 Stripe 作为支付网关,请按照以下步骤执行:

24.2.1. 使用 3scale 管理门户中的 Billing API 范围生成访问令牌

  1. 在 3scale 管理门户中,前往 Account Settings > Personal > Tokens
  2. 使用 Billing API 范围创建一个 Read and Write 令牌:

    1. 单击 Add Access Token
    2. 为令牌指定一个名称。
    3. 选择范围:Billing API
    4. 选择权限级别:读取和写入.
    5. 单击 Create Access token
    6. 复制访问令牌。

      • 确保您将访问令牌复制到文件文本。访问令牌之后不会显示。
    7. 要完成令牌生成,请单击 I have copied the token

返回至流程.

24.2.2. 从 stripe 获取密钥和 webhook secret

注意
  • 在 Stripe 中配置 Webhook 是必需的。
  • 使用 webhook 通知 3scale 付款已成功。
  • 3scale 然后更新发票的状态,并防止进一步尝试收费。

在您自己的帐户中,获取 Secret 密钥发布密钥

  1. 打开资源面板。
  2. 按照 stripe 文档中的说明查找您的 API 密钥
  3. 复制 Secret 密钥发布密钥

仍在您的 stripe 帐户中,创建一个 Webhook Signing Secret:

  1. 前往 Developers > Webhooks
  2. Add endpoint
  3. 使用以下端点 URL 填写:

    https://<Your-provider-admin-domain>/api/payment_callbacks/stripe_callbacks?access_token=<value-of-access-token>
  4. Events to send 中,添加 payment_intent.succeeded
  5. 单击 Add endpoint
  6. 单击以显示您刚才创建的 webhook 的签名机密并记下此机密。这是 Webhook 签名 Secret

返回至流程.

24.2.3. 在 3scale 管理门户中配置计费

在 3scale 管理门户中:

  1. 前往 Audience > Billing > Charging & Gateway
  2. 选择 Charging enabled,点 Save
  3. Credit Car gateway > Gateway 中,选择 Stripe 作为网关。
  4. 添加 Secret KeyPublishable KeyWebhook Signing Secret,您从 第 24.2.2 节 “从 stripe 获取密钥和 webhook secret” 中的 stripe 帐户获取。
  5. 点击 Save

返回至流程.

24.2.4. 在 3scale 开发人员门户中编辑信用卡详情

  1. 使用开发人员帐户登录 3scale 开发人员门户。
  2. 进入 Settings > Credit Card Details
  3. 添加以下信用卡详细信息:信用卡号码、到期日期和 CVC。
  4. Save details

返回至流程.

24.2.5. 更新收费失败的电子邮件回复的文本

对于 SCA 付款的修复,3scale 2.10 中需要手动更新 invoice_messenger_unsuccessfully_charged_for_buyer.text.liquid 电子邮件的文本。

  1. 在 3scale 管理门户中,转至 Audience > Messages > Email Templates
  2. 选择 Invoice charge failure for buyer with retry
  3. Override
  4. 更新模板消息:这是在不成功收费的电子邮件响应中使用的完整文本:

    Dear {{ account.name }},
    
    Thank you for using our service.
    
    We're sorry to inform you that your last payment was declined.
    This may have been caused by a few common reasons:
    
    - A new authentication policy enforced by your bank
    - An expired credit card
    - Insufficient funds on the account
    
    To continue using your service, verify the status of your credit card and update or re-enter the credit card details at {{payment_url}}.
    
    If you need help, don't hesitate to contact us at {{ provider.finance_support_email }}.
    
    Best regards,
    The {{ provider.name }} API Team
  5. 单击 Create Email Template

通过这些步骤,您已更新了电子邮件模板,以便收费失败的电子邮件回复。

返回至流程

24.3. 将 Braintree 配置为信用卡网关

作为 3scale API 提供程序,使用 Braintree 配置管理门户和开发人员门户作为支付网关,以使用 Braintree 从订阅您的 API 接收付款。

先决条件

  • 您必须有一个带有 Braintree 的帐户。
  • 如果要确保对带有 3D Secure(3DS)的客户进行安全签出,您必须在 Braintree 帐户中启用 3DS,然后才能为 3scale 启用 3DS。

    • 默认情况下,3scale 和 Braintree 都将 3DS 设为 off(禁用)。

步骤

要使用 Braintree 配置 3scale 作为支付网关,请按照以下步骤执行:

从 Braintree 获取密钥和 Merchant 标识符

在您的 Braintree 帐户中,获取 公钥Merchant ID私钥。有关获取这些值的更多信息,请参阅 其他资源 中列出的 Braintree 文档。

返回至流程

在 3scale 管理门户中配置计费

在 3scale 管理门户中:

  1. 前往 Audience > Billing > Charging & Gateway
  2. 选择 已启用 Charging
  3. 选择货币.

    • 3scale Billing 页面中指定的货币类型必须与 Braintree merchant 帐户中使用的货币类型匹配。
  4. 点击 Save
  5. Credit Car gateway > Gateway 下,选择 Braintree 作为网关。
  6. 添加 Public KeyMerchant ID 和从 从 Braintree 获取密钥和 Merchant 标识符 中的 Braintree 帐户 获取 的私钥。
  7. 要启用 3DS,请选择 3D Secure Enabled
  8. 单击 Save change

返回至流程

在 3scale 开发人员门户中编辑信用卡详情

作为 3scale API 消费者,在 3scale 开发人员门户中添加或编辑信用卡详情。若要将财务详细信息与已签发信用卡的实体匹配,此窗口中列出的所有字段均是必需的。

  1. 使用开发人员帐户登录 3scale 开发人员门户。
  2. 进入 Settings > Credit Card Details
  3. 单击 Add Credit Card Details 和 Billing Address 链接。
  4. 添加付款详细信息:名字、姓氏、电话。
  5. 添加信用卡详细信息:信用卡号码、到期日期和 CVC。
  6. 添加账单地址详细信息:公司、街道地址、zip/邮政编码、城市和州/地区。然后,选择国家/地区。
  7. Save details
  8. 如果出现提示,请完成购买的双因素验证(2FA)。例如,如果您的银行启用了 SMS 2FA 选项,则必须使用此方法完成验证过程。

返回至流程

其他资源

24.4. 允许通过开发人员门户支付被拒绝的发票

作为 3scale API 供应商,允许通过开发人员门户支付被拒绝的发票。要启用这些付款,请在管理门户中更新 Invoice s 模板。请注意,这个步骤适用于 Developer Portal 的现有实例。

先决条件

  • 您必须具有 3scale 的管理员权限。
  • 您必须有一个带有 stripe 或 Brain tree 的帐户。

步骤

要允许通过开发人员门户支付被拒绝的发票,请按照以下步骤操作:

  1. 在 3scale 管理门户中,转至 Audience > Developer Portal > Content
  2. 编辑 Root > Invoices > Show template
  3. 替换这些代码行:

    <a href="{{ urls.invoices }}">
      <i class="fa fa-chevron-left"></i>
        Cancel
        </a>
        {{ invoice.period_begin | date: '%B, %Y' }} Invoice

    在这个片段中:

    <div class="clearfix">
      <a href="{{ urls.invoices }}">
        <i class="fa fa-chevron-left"></i>
          Cancel
        </a>
        {{ invoice.period_begin | date: '%B, %Y' }} Invoice
        {% if invoice.pay_now? %}
          <a href="{{invoice.url}}/payment" class="pull-right btn btn-success pay-invoice-btn">Pay invoice</a>
        {% endif %}
    </div>

24.5. 信用卡网关问题故障排除

作为 3scale API 供应商,使用 stripe 或 Braintree 作为支付网关,您可以使用这些信用卡网关排除某些问题。

Stripe

  • 要将数据与 3scale 上的数据映射,您可以使用名为 metadata.3scale_account_reference 的 stripe 字段,该字段由 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID] 组成。

Braintree

  • 如果您的 Braintree 帐户处于沙盒模式,并且您遇到任何问题,您必须将其更改为生产环境。
  • 对于存储在 3scale Developer Portal 中但不启用 3D Secure(3D)的信用卡,这些是将 3scale 与 Braintree 集成的建议解决方案:

    1. 3scale API 提供程序:遵循 在 3scale 管理门户中配置计费 中列出的步骤。
    2. 3scale API 用户:遵循 在 3scale 开发人员门户中编辑信用卡详情 中列出的步骤。
  • 要将 Braintree 中的数据与 3scale 上的数据映射,您可以使用名为 customer.id 的 Braintree 字段,该字段由 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID]组成。

第 25 章 定价

本节论述了您可以向开发人员支付使用 API 的不同方法。

设置费用
是订阅服务时应用的一次性收费,切换至另一计划时不收取额外费用。它仅在订阅的第一个月出现在发票/信用卡中。可以在应用计划、服务计划和帐户计划上配置.
每个月的成本
是每月定期收取的费用。如果订阅在半月中发生,则按比例分配。有时它称为"固定费用"。可以在应用计划、服务计划和帐户计划上配置.
变量成本
是从应用计划中所配置的各个方法/指标的定价规则获得的成本。它们基于您的 API 的使用情况,因此不能提前知道,只有在计费周期结束时才会知道。仅适用于应用计划.

示例

If you have a plan with monthly cost of $10, but want to charge your developer a $5 setup fee. The initial charge would be for $15, while all subsequent charges would be for $10.

25.1. 定价规则

定价规则定义每个 API 请求的成本。同一指标的多个定价规则在适用定价规则时划分了范围。定价规则基于日历月份,计数器在每月第 1 天的 00:00 UTC 重置。

示例 1

Until 100 calls per month (from 1 to 100) each API call can be charged at $0.04, and starting from the call 101 (from 101 to infinity) the calls are charged at $0.10.

示例 2

The first 1000 calls are not charged (cost $0), because they are included in the plan which has a monthly fixed cost. Starting from call 1001, each call is charged at $0.50.

示例 3

Calls from 1 to 100 are charged at $0.30, 100 to 500 – at $0.40, and 500 and further – at $0.50.

注意

为指标和方法定义定价规则。实际的 API 请求通过映射规则映射到这些指标和方法。

25.2. 设置定价规则

  1. 前往 [Your_API_service] > Applications > Application Plans
  2. 选择现有应用计划或创建新应用计划。
  3. Metrics, Methods, Limits and Pricing Rules 部分中,点 Pricing(x) 打开定价部分。
  4. 单击新定价规则.
  5. 设置每个单元的值,并点击 Create 定价规则

重复最后两个步骤,以创建所有必要的定价规则范围。

将 To 字段留空,将规则设置为 " to infinity"。

指标成本的最大十进制数设置为 4,如果添加的数字包含更多十进制数,则该值将舍入到带有 4 十进制位置的数字。

25.3. 更新现有的定价规则

  1. 单击"编辑"
  2. 对每单元字段的内容、To 和成本进行必要的调整。
  3. 单击 Update 定价规则。

第 26 章 账单

计费流程在开发人员帐户下创建发票(如果已订阅任何付费服务)。发票通过配置的支付网关收取。

26.1. 列出发票

Audience > Billing > Earning by month 部分,您可以找到您的到期和收到的付款概述,根据情况计算,计算为当月发出的所有发票的总和:

总计
所有发票(不包括取消的)
处理中
打开、最终化和待处理发票
到期未支付
失败和未支付的发票
已付
已支付的发票

单击具体月,您可以列出该月的所有发票。

您还可以通过转至 Audience > Billing > Invoices 来查看发票列表,您可以在其中按 ID(友好 ID)、帐户名称以及按月份和状态过滤发票。

特定开发人员帐户的发票也可在 Audience > Accounts > Listing > [selected account](其中 X 是帐户拥有的发票数)的面包屑导航页面的 X Invoices 下找到。

26.2. 发票视图

如果单击发票列表中的发票友好 ID,您将看到发票的详细信息。

26.2.1. 发票详情

标题包括发票的月份和年份,还显示了发票是手动创建的还是由自动化账单流程创建,例如 2018 年 2 月(手动创建)

以下 详细信息 块显示了发票的友好 ID、发票状态、发票完成和发出的日期,以及到期和付款的时间。如果 PDF 已经生成,则会显示下载 PDF 的链接。

Issued byIssued to 部分表示 API 提供程序的名称和地址,以及相应的 developer 帐户。

以下将显示带有 line items 的部分,包括 VAT/Sales Tax 的计算、总成本,以及"Text 表示 VAT/Sales Tax 是否已配置 0%" 的文本,它也会在此处显示。

在发票的 Transactions 部分中,您可以看到所有信用卡交易尝试的列表,包括交易的状态、时间戳、参考号、支付网关提供的消息和数额。您可以使用参考号在支付网关管理员控制台中找到事务。

26.2.2. 编辑发票

如果发票处于 Open 或 Finalized 状态,您可以编辑发票的一些详细信息。

单击发票视图右上角的 Edit 链接,您可以更改友好的 ID 和计费周期。

您还可以添加和删除发票项目(计算成本除外 - 总成本、VAT/销售税、总 VAT/销售税)。要添加新行项,请单击"添加"并填写"名称"、"质量"(不会影响成本)、描述和成本。

发票视图底部的链接可以触发对发票的操作 - 根据发票的当前状态,可以采取不同的操作,例如生成 PDF、问题发票 Cancel 发票、Regenerate PDF、Charge、Mark 等。这些操作(PDF 相关)将更改发票的状态。

26.3. 发票状态

发票可处于以下状态之一:

Open
已创建发票,但尚未完成自动计算。
Finalized
发票中增加了所有当前计费周期费用。
待处理
发票已发送给开发人员,正在等待付款。
Unpaid
发票的收费失败,但等待自动重试。
Paid
发票已被成功收费。
失败
发票的收费不成功,不会再尝试自动重试。
Cancelled
被管理员取消。

26.4. 自动计费流程

在 3scale 中,账单流程每天运行。它生成发票,并根据计费流程更改其状态,并使用配置的支付网关来执行费用。

Pre paid 和 Post付费模式的计费流程略有不同,因为 3scale 的账单基于日历月,当月第一天发生特殊事件。

26.4.1. 在每个月的第一天

Postpaid

  • 上个月的账单变量成本:该成本作为开票的单行项目包括。
  • 完成上个月的开票
  • 帐单当前月的固定成本:为当前月份处于 Open 状态的新发票创建一个新发票。

Prepaid

  • 账单固定成本(当前月)
  • 账单变量成本(上个月)

向 API 管理员发送有关本月初最终发票的通知,以便他们可以审查发票并进行必要的调整。

除上述操作外,每天执行的所有操作也在每月第一天执行。

26.4.2. 每天

  • 账单过期的试用期以及尚未计费的新合同:为当前月份创建处于 Open 状态的发票。
  • Prepaid:完成所有 Open 发票:状态更改为 Finalized.
  • 签发发票:状态更改为 Pending

    • 发票通常在发票完成后签发 2-3 天。发票的 "Issued On" 日期设置为当前日期,"Due On" 日期(当发票被收费时)将设定为 Issued On 再加 2 天。
    • 向开发人员发出发票时,他们会收到电子邮件通知,并可以在开发人员门户中看到出具的发票。
  • 计费发票

    • 如果 Due On 日期是今天或更早的,则 UnpaidPending 状态的发票将收取费用。
    • 如果付款失败,发票状态将更改为 未支付。在 3 天后将再次尝试。3 次重试失败后,发票状态将更改为 Failed,并且不再重试计费。
  • 通知过期的信用卡

    • 信用卡即将过期的开发人员帐户会收到电子邮件通知。

26.4.3. 自动和手动发票

自动计费流程生成的发票在发票 标题中有一个(自动创建) 标签。例如:2019 年 1 月的发票(自动创建)

手动生成的发票将在发票详细信息页面上标有(手动创建)

自动账单流程可使用当前月份处于 open 状态的现有发票来创建额外行项,但仅限自动创建的发票。手动创建的发票不会通过自动计费流程更新。

26.4.4. 月中升级

如果在月中升级了某个应用程序(或帐户/服务订阅),则每月的成本将按月中的剩余天数进行相应调整。应用计划中配置的限值没有按比例来划分。

如果应用程序从免费升级到付费计划,下次运行账单时将生成一个新发票,包括按指数的每月成本。

当应用程序从付费计划升级到更为昂贵的支付计划时,行为取决于以下几个因素:

  • Billing 模式:PrepaidPostpaid
  • 当计划更改时
26.4.4.1. 预付账单
  1. 如果申请计划 在同一计费日(账单日从创建时间 8: UTC 开始) 更改,且 之前未开具发票,则旧计划的固定成本将包含在发票中,并附带 'Refund' 行项。旧计划的固定成本也添加到发票中。

    Example:客户在每月第一天注册计划 A(200$),并在当日升级到 B 计划(300$)。在这种情况下将生成一个发票,其中将包含以下行项目:

    描述Cost

    固定费用('Plan A')

    200

    退款('Plan A')

    -200

    应用程序升级("Plan A"至"Plan B")

    300

    总计

    300

    请注意,如果客户在当月的另一天注册,则按比例计算 200 美元的成本和退款。

  2. 如果在已为此应用程序 签发发票后 更改了应用程序计划:

    • 如果 升级,开发人员将签发两张发票:一个用于初始收费,另一发票用于升级。

      Example:客户于本月中第一天注册计划 A(200$),然后在该月中部升级到计划 B(300$)。将生成以下发票:

      描述Cost

      固定费用('Plan A')

      200

      总计

      200

      描述Cost

      退款('Plan A')

      -100

      应用程序升级("Plan A"至"Plan B")

      150

      总计

      50

      在第二张发票中,当在账单期间进行升级时,将按比例计算重新支付成本(100$)和新成本(150$)。

    • 目前不支持退款应用 降级 (更改为具有较低成本的计划)。
26.4.4.2. 邮付账单

在 Post付费账单模式中,将发出单一发票,其中将包括 Refund应用程序升级行项目。

重要:2018 年 4 月 20 日 引入了此行为,并进行了以下更改:

  • 修复了一个程序错误,其中在创建申请的当日升级时,发票中不包含初始收费(用于初始应用程序计划)。
  • 在以前的版本中,应用程序升级中仅添加一行项,包括新计划成本和旧计划成本之间的差异。例如,在以上 预付账单 部分中描述的情景 2(从 Plan A - 200$ 升级到 Plan B - 300$),第二个生成的发票将是:
描述Cost

应用程序升级("Plan A"至"Plan B")

50

总计

50

其中 50$ 是本月剩余新计划与旧计划之间的按比例成本之间的差异(150$ - 100$)。

2018 年 4 月 20 日之后,计算结果在发票(包括单独退款和收费)中更清楚地反映,而总成本则与以前相同。

26.5. 启用/禁用每个帐户的计费/计费/计费

自动化账单流程为订阅付费服务的所有开发人员帐户生成发票。

计费可以在全局范围内启用或禁用。请参阅配置账单设置,但也可以启用或禁用每个开发人员帐户的计费和计费。要做到这一点,进入帐户页面并点击对应的按钮(启用/禁用):

  • 每月账单已启用/禁用
  • 每月收费已启用/禁用

如果收费被停用,并且启用了计费,开发人员将被签发发票,但不会收取费用。这在您单独处理计费时很有用(例如,电汇)。

如果两者均被禁用,则不会发布或收取开发人员费用。

如果账单被禁用,并且启用了收费,则不会向开发人员支付任何新的发票,但所有未付发票(PendingFailed)仍会收费。

在此 Billing Status 块中,您还可以查看是否在帐户上配置了信用卡详细信息。如果配置了信用卡详细信息,则显示卡到期月份和年份。信用卡详情的存在可能会影响开发人员门户注册时的流程并计划更改(请参阅 第 26.9 节 “信用卡流”)。

26.6. 试用期的计划

可以为付费计划设定试用期(按天数计),以延迟收取指定天数的费用。

您可以在应用程序列表中看到应用程序的试用周期状态([Your_product_name] > Applications > Listing),在 State 列中显示 "live - 试用过期",并在 Trial days left 字段中的应用程序详情页面中看到应用程序。

在试验期间,应用可以无限制地使用计划定义的所有功能和使用限制。

一旦设定了试用期,便无法取消或延长试用期。升级至其他计划将不会重置试用日计数器。

试用期到期 10 天前,将向开发人员帐户发送电子邮件通知,通知即将开始的试用期。此电子邮件的模板可在 Audience > Messages > Email Templates 中配置:"Application trial period expired for buyer",对于具有试用期的服务计划,"Service trial period expired for buyer"。开发人员应保留在当前计划中,或者切换到另一个计划;或者,如果他们决定取消订阅,请联系 API 提供程序。

试用期结束后,开发人员将按照当前应用程序或服务的计划所设定的成本收取自动账单运行时间(请参阅 第 26.4 节 “自动计费流程”)。请注意,在试用期到期后,申请 不会被 阻止或暂停,并且将继续工作。

虽然技术上可以为免费计划设置试用期,但建议不要这样做,因为该功能会失去有用性。

26.7. VAT 速率/销售税

增值税务(VAT)是一种税款,适用于在欧盟内部销售的产品和服务。在其他国家/地区也有类似的税款,例如销售税。收取客户使用 API 服务的 API 供应商通常还需要收取税款,并将其反映在发票中以符合现有法规。

3scale 账单配置后,可以在发票中自动包含 VAT。

26.7.1. 配置 VAT 速率字段

VAT 费率是将应用于发票总成本的数字(以百分比表示)。要配置 VAT 费率,请从 Dashboard,按照管理门户中的以下步骤操作:

  1. 前往 Audience > Accounts > Fields Definitions
  2. 单击 帐户 部分中的 Create
  3. 在 [new field] 下拉列表中选择 vat_rate
  4. Label 设置一个值。
  5. 配置复选框,指明对于开发人员,该字段应为 Required, Read onlyHidden

    注意 :"选择"字段仅接受字符串,因此无法使用此字段。

  6. Create

26.7.2. 配置 VAT 代码字段

VAT 代码是 VAT 标识号。要配置 VAT 代码,请遵循管理门户中的以下步骤,从 Dashboard:

  1. 前往 Audience > Accounts > Fields Definitions
  2. 单击 帐户 部分中的 Create
  3. 在 [new field] 下拉列表中选择 vat_code
  4. Label 设置一个值。
  5. 配置复选框,指明对于开发人员,该字段应为 Required, Read onlyHidden
  6. Create

26.7.3. 为帐户设置 VAT 值

添加 VAT 代码和 VAT 速率字段后,您可以在开发人员帐户编辑表单下设置对应的值。根据字段中所选择的复选框,这些字段也可由开发人员在开发人员门户网站中可见和/或编辑。

VAT 代码可以是任意字符串。

VAT 速率必须是数字。接受整数或十进制数(例如:21、23.5 等),它们代表了将包含在 VAT 中的成本百分比。

26.7.4. VAT 的发票

为配置了非零 VAT 费率的开发人员帐户生成发票时,发票将包括以下行项目:

_Total cost (without <VAT rate>)_ +
_<VAT rate> Amount_ +
_Total cost (<VAT rate> <VAT rate value>% included)_

<VAT rate> 将替换为 VAT rate 字段设置的 Label,而 <VAT rate value> 是为签发发票的帐户配置的值。

VAT 代码将包含在带有该标签的 PDF 版发票中,该标签在 VAT 代码字段定义中作为标签指定。该值将对应于 developer 帐户详细信息中设置的值。

字段 vat_ratevat_code 也可由 3scale 帐户管理 API 读取和写入。

26.8. 开发人员门户视图

开发人员可以管理他们的信用卡信息,并在开发人员门户中查看他们的发票。

Audience > Developer Portal > Feature Visibility 中的 Finance 切换必须处于 可见 状态,以便开发人员查看 Developer Portal 中的与计费相关的元素。

登录的用户可以通过 Settings > Credit Card Details 更新信用卡详情。根据付款网关配置的支付网关,表单可能有所不同,用户可能需要先输入计费地址。

注意

信用卡详细信息不存储在 3scale 数据库中。这些详细信息由支付网关管理。信用卡号码的最后 4 位数字,到期日期和支付网关提供的参考信息存储在 3scale 数据库中。

开发人员只能在开发者门户上有一个信用卡。

无法从 Developer Portal 中删除信用卡详情。希望删除其信用卡详细信息的开发人员帐户用户需要请求 API 供应商从系统中删除信用卡详细信息。

要查看发票,用户可以转到 Settings > Invoices,可以从那里显示每个发票的详情,或下载发票 PDF。

26.9. 信用卡流

26.9.1. 注册一个付费计划

当开发人员签署付费计划时,他们需要先输入信用卡详细信息,然后才能查看应用凭证。开发人员第一次登录到开发人员门户后,它们将重定向到 Credit Card Details 页面。尝试访问任何其他开发人员帐户页面将导致再次重定向到 Credit Card Details 页面。

您可以通过自定义对应的 Developer Portal 模板,使用 Liquid 标签隐藏所有菜单项(Credit Card Details 选项卡除外)。

current_account Liquid drop 会公开方法 require_cert_card_now? 如果缺少信用卡详细信息,此方法将返回 true (但仅在管理门户中配置了 Billing 时),否则返回 false

您可以通过以下条件将它们封装在 子菜单中的任何菜单项和其他用户界面元素users_menu 部分:

{% unless current_account.requires_credit_card_now? %}
...
{%  endunless %}

26.9.2. 从免费升级到付费计划

对于计划更改现有应用,可以配置多个选项,包括开发人员直接更改计划或请求更改计划。如果应用程序从免费升级到付费计划,务必要确保开发人员在进行升级前输入信用卡详细信息。这可以在 [Your_product_name] > Integration > Settings,Application Plan change anging 部分配置:

如果开发人员有信用卡,否则请直接更改计划,否则:
- 仅请求计划更改
- 已付费计划的请求信用卡条目

如果您只想让开发人员请求更改,请选择第一个选项,并在输入信用卡详细信息后手动执行升级。

如果您希望开发人员在升级到付费计划之前输入信用卡详细信息,请选择第二个选项。在计划选择器小部件中,开发人员将看到一条消息"You not change plan,除非您输入指向信用卡详细信息表单的 Credit Card 详细信息"。

26.10. "Perling address"字段

当开发人员在开发人员门户中输入信用卡详细信息上的账单地址时,此地址将独立于"传统"帐户地址存储。

默认情况下,该法律地址会出现在 Issued to 字段中的 Invoices 中。但是,如果开发人员没有配置法律地址,而仅仅是计费地址,后者将用于发票。在这种情况下,组织名称被视为地址的一部分。

默认情况下,账单地址在管理门户或通过产品 API 不可见;但您可以添加如下:

  1. 前往 Audience > Accounts > Fields Definitions
  2. Account 块下,单击 Create
  3. 从下拉列表中选择"billing_address",添加标签,选中 Read only 复选框并单击 Create

现在,<billing_address> 字段会出现在帐户管理 API 和 Webhook 的 XML 模型中。对应的账单地址将在帐户和管理门户的帐户编辑页面中以只读方式显示。

开发人员可以在开发人员门户的"信用卡详细信息"部分中更改账单地址。管理员不能更改管理门户中的计费地址,但可以使用以下字段(作为"附加字段")通过帐户管理 API 的帐户 编辑 端点来执行此操作:

billing_address_name
billing_address_address1
billing_address_address2
billing_address_country
billing_address_city
billing_address_state
billing_address_zip
billing_address_phone

第 27 章 电子邮件通知

与计费相关的不同事件触发 API 提供程序和开发人员的电子邮件通知。

27.1. 供应商通知

3scale 帐户的用户(具有 Billing 权限的管理员和成员)可以订阅或取消订阅与 帐户设置相关的通知(右上角的gear图标) > Personal > Notification Preferences (Billing 部分):

所需操作:审核发票
在计费周期结束前几天前发送,以便您可以在发票发送给客户之前审核发票。
客户降级
当客户更改每月固定价格的计划时发送。
信用卡过期
当客户的信用卡即将到期时发送。
支付错误(重试)
付款失败时发送,导致未付款发票和重试。
支付错误(最终)
付款的最终重试失败时发送,导致发票失败。

备注:3scale 帐户的所有管理员用户如果已订阅,将接收关于计费的通知。

27.2. 开发人员电子邮件

发送到开发人员帐户的电子邮件通知可在 Audience > Messages > Email Templates 上配置。可用的电子邮件如下:

信用卡过期通知,用于买方
信用卡即将过期时发送。
成功向买方收取发票
发票成功收费后发送。
重试的买方的发票失败
发票收费失败时发送,并且发票处于故障状态,这意味着将再次退款。
对不重试的买家的发票失败
发票第 3 次失败,发票已转至未支付状态,不会再次申索。
即将对买家的发票收取费用
为开发人员签发发票时发送。

开发人员帐户的所有管理员用户将收到上述通知。

27.2.1. 账单电子邮件地址

您可以在 Finance support email 项的 Audience > Messages > Support email 字段中配置您的客户可以联系以解决账单(如 billing@example.com)的电子邮件地址。

电子邮件模板引用了带有 Liquid drop {{ provider.finance_support_email }} 的电子邮件地址。

第 28 章 账单 API

Billing API 提供了一种方式来自动化常见计费流程。

Billing API 的所有端点均可在管理门户的 Documentation(?)> 3scale API Docs > Billing API 下找到。

Billing API 需要有效的访问令牌,它满足以下要求:

  • 它应属于 provider 帐户的 admin 用户或具有"Billing"权限的成员用户
  • 它应包含"Billing API"范围

请注意,当需要发票 ID 作为参数时,它指的是发票 ID,而不是 友好发票 ID。

API 端点的 XML 响应大多自我解释,Invoice 的字段表示的信息与 web 和 PDF 表示法中的信息相同。

响应中的一些显著字段:

  • creation_type :对于手动创建的发票为 'manual',对于 3scale 自动账单流程创建的发票为 'background'
  • provider :API 提供程序(管理员帐户)的详细信息,对应于发票的 Issued by 部分。
  • buyer :开发人员帐户的详细信息,对应于发票的 Issued to 部分。

发票的 XML 表示法还包括 line-items 字段下的行项目列表。

除了预期名称、描述、数量和成本(价格)之外的一些项目(通常是自动创建的项目),您可以看到以下内容:

  • type :行项的类型,可以是以下值:

    • LineItem::PlanCost - 用于固定计划成本的行项
    • LineItem::VariableCost - 用于行项目的变量成本
  • metric_id :用于变量成本行项目 - 成本关联的指标 ID
  • contract_id :与成本相关联的服务或应用程序的 ID

部分 V. 服务发现:从 OpenShift 到 3scale

服务发现是一项 3scale 功能,可帮助您从 OpenShift 集群导入服务。OpenShift 服务的专用端点变为 API 后端,以及捆绑此 API 后端的新 API 产品。此外,基于 OpenAPI 规范(OAS)的服务规格作为 API 产品的 ActiveDoc 导入。

第 29 章 服务发现

通过 3scale 提供的服务发现功能,您可以从 OpenShift 导入 API 服务。

29.1. 关于服务发现

配置服务发现后,3scale 扫描在同一 OpenShift 集群中运行的可发现的 API 服务,并自动将关联的 API 定义导入到 3scale 中。另外,3scale 可以根据 OpenAPI 规范(OAS)更新 API 集成及其规格,以将其与集群重新同步。

服务发现提供以下功能:

  • 使用集群 API 查询已正确注解用于发现的服务。
  • 配置 3scale 以使用集群内部端点访问服务。
  • 将 API 服务规格导入 3scale ActiveDocs。
  • 支持 OpenShift 和红帽单点登录(RH SSO)授权流。
  • 使用红帽 Fuse,从 Fuse 版本 7.2 开始.

当您导入可发现的服务时,它会将其命名空间保存在它所属的项目内。导入的服务成为面向客户的新 API、产品及其相应的内部 API 后端。

  • 对于内部 3scale,3scale API 提供商可能拥有自己的命名空间和服务。发现的服务可以与 3scale 现有和本地服务共存。
  • Fuse 可发现服务部署到 Fuse 产品命名空间中。

29.2. 可发现服务的标准

如果在 OpenShift(OCP)集群中有 3scale 发现 API 服务,则 OCP 服务必须满足以下每个元素的条件:

Content-Type 标头

API 规格的 Content-Type 标头必须是以下值之一:

  • application/swagger+json
  • application/vnd.oai.openapi+json
  • application/json

OpenShift Service Object YAML 定义

  • OpenShift Service Object YAML 定义必须包含以下元数据:

    • discovery.3scale.net 标签:(必需)设置为 "true"。3scale 执行选择器定义以查找需要发现的所有服务时,它会使用此标签。
    • 以下注解:

      discovery.3scale.net/discovery-version:(可选)3scale 发现过程的版本。

      discovery.3scale.net/scheme :(必需)托管该服务的 URL 的 scheme 部分。可能的值有 "http" 或 "https"。

      discovery.3scale.net/port :(必需)集群中服务的端口号。

      discovery.3scale.net/path :(可选)托管服务的 URL 的相对基本路径。当路径位于 root("/")时,您可以省略此注解。

      discovery.3scale.net/description-path:该服务的 OpenAPI 服务描述文档的路径。

      例如:

          metadata:
            annotations:
              discovery.3scale.net/scheme: "https"
              discovery.3scale.net/port: '8081'
              discovery.3scale.net/path: "/api"
              discovery.3scale.net/description-path: "/api/openapi/json"
           labels:
              discovery.3scale.net: "true"
           name: i-task-api
           namespace: fuse
    • 如果您是一个具有管理特权的 OpenShift 用户,您可以在 OpenShift 控制台中查看 API 服务的 YAML 文件:

      1. 选择 Applications> Services
      2. 选择服务,如 i-task-api,以打开其 Details 页面。
      3. 选择 Actions> Edit YAML 以打开 YAML 文件。
      4. 查看完后,选择 Cancel

使用 ovs-networkpolicy 插件的集群

  • 要允许 OpenShift 和 3scale 项目之间的流量,带有 ovs-networkpolicy 插件的集群需要在其应用程序项目中创建 NetworkPolicy 对象。
  • 有关配置 NetworkPolicy 对象的更多信息,请参阅 关于网络策略

29.3. 配置 OpenShift 以启用服务发现的注意事项

作为 3scale 管理员,您有两个选项可用于配置服务发现:使用或不使用 Open Authorization(OAuth)服务器。

如果您使用 OAuth 服务器配置 3scale 服务发现,当用户签名到 3scale 时会出现这种情况:

  • 用户重定向到 OAuth 服务器。
  • 如果用户尚未登录到 OAuth 服务器,则会提示该用户登录。
  • 如果这是用户首次使用 SSO 实施 3scale 服务发现,OAuth 服务器会提示您授权执行相关操作。
  • 用户重定向到 3scale。

要使用 OAuth 服务器配置服务发现,有以下选项:

如果您在没有 OAuth 服务器的情况下配置服务发现,当用户签入到 3scale 时,该用户不会被重定向。相反,3scale 单服务帐户为集群提供无缝身份验证,以进行服务发现。所有 3scale 租户管理用户对集群具有相同的访问权限级别,同时通过 3scale 发现 API 服务。

29.4. 使用 OpenShift OAuth 服务器配置服务发现

作为 3scale 系统管理员,允许用户单独验证并授权 3scale 使用 OpenShift 内置 OAuth 服务器来发现 API。

先决条件

  • 您必须将 3scale 2.12 部署到 OpenShift 集群(版本 3.11 或更高版本)。
  • 若要将 3scale 部署到 OpenShift,您需要使用 3scale-amp-openshift-templates
  • 3scale 用户若要在 3scale 中使用服务发现,必须有权访问 OpenShift 集群。

步骤

  1. 为 3scale 创建 OpenShift OAuth 客户端。如需了解更多详细信息,请参阅 OpenShift 身份验证文档。在以下示例中,将 <provide-a-client-secret> 替换为您生成的 secret,并将 <3scale-master-domain-route> 替换为 3scale Master 管理门户的 URL。

        $ oc project default
        $ cat <<-EOF | oc create -f -
        kind: OAuthClient
        apiVersion: v1
        metadata:
         name: 3scale
        secret: "<provide-a-client-secret>"
        redirectURIs:
         - "<3scale-master-domain-route>"
        grantMethod: prompt
        EOF
  2. 打开 3scale 服务发现设置文件:

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 配置以下设置:

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: builtin
            client_id: '3scale'
            client_secret: '<choose-a-client-secret>'
  4. 确保用户有适当的权限来查看包含可发现服务的集群项目。

    要授予管理员用户(由 <user> 表示),对于包括了一个服务的 <namespace> 项目的查看权限可以被发现,使用以下命令:

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. 修改 configmap 后,您必须重新部署 system-appsystem-sidekiq pod 以应用更改。

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  6. 检查推出部署的状态,以确保它已完成:

    oc rollout status dc/system-app
    oc rollout status dc/system-sidekiq

其他资源

29.5. 使用 RH-SSO 服务器(Keycloak)配置服务发现.

作为系统管理员,允许用户单独验证 3scale 并授权 3scale 通过 使用红帽单点登录 OpenShift 来发现服务。

有关将 OpenShift 配置为使用 RH-SSO 部署作为 OpenShift 授权网关的示例,您可以参考此 工作流

先决条件

  • 您必须将 3scale 2.12 部署到 OpenShift 集群(版本 3.11 或更高版本)。
  • 若要将 3scale 部署到 OpenShift,您需要使用 3scale-amp-openshift-templates
  • 3scale 用户若要在 3scale 中使用服务发现,必须有权访问 OpenShift 集群。

步骤

  1. 在 Red Hat OAuth 服务器(Keycloak)中为 3scale 创建 OAuth 客户端。

    注意

    在客户端配置中,验证用户名是否映射到 preferred_username,以便 OpenShift 可以链接帐户。

  2. 编辑 3scale 服务发现设置。

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 验证是否已配置以下设置,其中 '<the-client-secret-from-Keycloak> 是创建 OAuth 客户端时自动生成的 Keycloak 的值。

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: rh_sso
            client_id: '3scale'
            client_secret: '<the-client-secret-from-Keycloak>'
  4. 确保用户具有适当的权限,可以查看包含可发现服务的集群项目。

    例如,要为 <namespace> 项目提供 <user> 视图权限,请使用这个命令:

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. 修改 configmap 后,您必须重新部署 system-appsystem-sidekiq pod 以应用更改。

其他资源

  • 令牌生命周期:默认情况下,会话令牌会在一分钟后过期,如 Keycloak - Session 和 Token Timeouts 所示。但是,建议将超时设为可接受值为一天。

29.6. 在没有 OAuth 服务器的情况下配置服务发现

要在不使用 OAuth 服务器的情况下配置 3scale 服务发现,您可以使用 3scale 单服务帐户对 OpenShift API 服务进行身份验证。

先决条件

  • 您必须将 3scale 2.12 部署到 OpenShift 集群(版本 3.11 或更高版本)。
  • 若要将 3scale 部署到 OpenShift,您需要使用 3scale-amp-openshift-templates
  • 3scale 用户若要在 3scale 中使用服务发现,必须有权访问 OpenShift 集群。

步骤

  1. 验证 3scale 项目是否为当前项目。

       $ oc project <3scale-project>
  2. 在编辑器中打开 3scale 服务发现设置。

       $ oc edit configmap system
  3. 验证是否已配置以下设置:

    service_discovery.yml:
       production:
          enabled: <%= cluster_token_file_exists = File.exists?(cluster_token_file_path = '/var/run/secrets/kubernetes.io/serviceaccount/token') %>
          bearer_token: "<%= File.read(cluster_token_file_path) if cluster_token_file_exists %>"
          authentication_method: service_account
  4. 为 3scale 部署 amp 服务帐户提供相关权限,以便查看包含可发现服务的项目:

    • 为 3scale 部署 amp 服务帐户授予 查看 集群级别权限。

      oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp
    • 应用更严格的策略,如 OpenShift - Service Accounts 所述。

29.7. 导入发现的服务

从 OpenShift 集群中,导入符合 OpenAPI 规范的新 API 服务。此 API 通过 3scale 进行管理。

先决条件

  • OpenShift 管理员为 OpenShift 集群配置了 Service Discovery。例如,OpenShift 管理员必须通过编辑 Fuse Online 自定义资源来指定 3scale 用户界面的 URL 来启用 3scale 发现。
  • 3scale 管理员为服务发现配置了 3scale 部署,如 About Service Discovery 所述。
  • 3scale 管理员已授予 3scale 用户或服务帐户(取决于配置的验证模式),以查看 API 服务及其命名空间。如需了解更多详细信息,您可以看到 授权 3scale 对 OpenShift 项目的访问权限
  • API 具有启用服务发现的正确注解,如 可发现服务的标准 中所述。
  • API 服务部署到安装 3scale 的同一个 OpenShift 集群上。
  • 您知道 API 的服务名称及其命名空间(OpenShift 项目)。

步骤

  1. 登录 3scale 管理门户。
  2. Admin Portal Dashboard 上的 API,点 Create Product
  3. 单击 Import from OpenShift

  4. Namespace 字段中,指定或选择包含 API 的 OpenShift 项目,如 fuse
  5. Name 字段中,键入或选择该命名空间中的 OpenShift 服务的名称,如 i-task-api
  6. Create Product
  7. 等待新 API 服务异步导入到 3scale。在管理门户的右上角会出现一条消息:The service will be imported shortly.You will receive a notification when it is done.

其他资源

29.8. 授权 3scale 对 OpenShift 项目的访问权限

作为 OpenShift 项目管理员,您可以在 OAuth 令牌无效时授权 3scale 用户访问命名空间。

先决条件

  • 您需要具有作为 OpenShift 项目管理员的凭据。
  • OpenShift 管理员为 OpenShift 集群配置了 Service Discovery。例如,对于 Fuse Online API,OpenShift 管理员必须将 Fuse Online 服务的 CONTROLLERS_EXPOSE_VIA3SCALE 环境变量设置为 true
  • 3scale 管理员已配置了 3scale 服务发现部署,如适用于 可发现服务的标准 中所述。
  • 您知道 OpenShift 项目的 API 服务名称及其命名空间。
  • API 服务部署到安装 3scale 的同一个 OpenShift 集群上。
  • API 具有启用服务发现的正确注解,如 可发现服务的标准 中所述。

步骤

  1. 单击 Authenticate 以启用此选项 链接。
  2. 使用命名空间管理员凭据登录 OpenShift。
  3. Allow selected permissions 授权 3scale 用户的访问权限。

其他资源

29.9. 更新服务

您可以使用集群中该服务的当前定义在 3scale 中更新(刷新)现有 API 服务。

先决条件

步骤

  1. 登录 3scale 管理门户。
  2. 导航到 API 产品的 Overview 页面。
  3. 点 Source 旁边的 Refresh 链接:OpenSource.
  4. 等待新 API 服务异步导入到 3scale。

部分 VI. 多租户

第 30 章 多租户

红帽 3scale API 管理允许多个 3scale 帐户独立实例存在于单个内部部署中。帐户彼此独立运作,不能互相共享信息。

30.1. Master 管理门户

主管理员通过主管理门户和 API 端点监控和管理 3scale 帐户。与标准 管理门户 类似,主管理门户包含关于部署的所有帐户的信息,并允许通过唯一的帐户页面管理帐户和用户。

如需帐户管理员操作的详细信息,请参阅 帐户 指南。

30.1.1. 访问主管理门户

要访问主管理门户,您需要在内部安装过程中使用专门为主管理门户定义的凭据和 URL。

主管理门户 URL 由 MASTER_NAME (模板中默认为master )和 WILDCARD_DOMAIN 组成:

<MASTER_NAME>.<WILDCARD_DOMAIN>

您可以通过 Master 标志来识别主管理门户。

Master Admin Portal 标记

30.1.2. 通过主管理门户添加帐户

要通过 Master 管理门户添加帐户,请按照以下步骤执行:

  1. 登录主管理门户
  2. 导航到 Accounts
  3. Create
  4. 指明用户所需的信息:

    1. 用户名
    2. 电子邮件
    3. 密码
    4. 确认密码
  5. 指明机构所需的信息:

    1. 机构/组名称
  6. Create

这些步骤后,Red Hat 3scale 根据 Organization/Group Name 字段为您的帐户创建一个帐户子域。另外,您可以看到包含您创建的帐户详情的页面。

30.1.3. 使用 Master 管理门户创建单一网关

使用 Master 管理门户,您可以通过配置 THREESCALE_PORTAL_ENDPOINT 环境变量为所有租户创建一个网关。这与 Hosted 3scale(SaaS)中的托管 APIcast 类似,通过 OpenShift 模板部署的默认 apicast-stagingapicast-production 网关以这种方式配置。

要使用 Master 管理门户创建单一网关,请按照以下步骤执行:

  1. 从 3scale 项目中的 system-master-apicast secret 中获取 ACCESS_TOKEN 的值。或者,您也可以在主管理门户中 创建新的访问令牌
  2. 部署 APIcast 时使用以下命令:

     THREESCALE_PORTAL_ENDPOINT="https://<ACCESS_TOKEN>@<public url to master admin portal>/master/api/proxy/configs"
    • url 的末尾看起来类似于 /master/api/proxy/configs,这是因为 master配置 保存在不同的端点中(与默认的 /admin/api/services.json 相比)。

30.2. 管理帐户

您可以通过主管理门户或通过 API 调用来管理帐户。

30.2.1. 通过主管理门户管理帐户

要通过主管理门户管理帐户,您需要执行以下操作:

  1. 登录主管理门户
  2. 进入 Accounts 页面。
  3. 选择您要管理的组或组织。

Accounts 页面中,您可以执行管理操作,如模拟 admin 帐户或暂停帐户。您还可以管理以下帐户属性:

  • Applications
  • 用户
  • 邀请
  • 组成员身份
  • 机构/组名称

30.2.2. 通过 API 调用管理帐户

您可以通过 Master Admin API 调用来管理帐户。有关这些调用的详情,请参考 Master API 部分,具体操作为:单击主管理门户右上角的问号(?)图标,然后选择 3scale API 文档

Master API 部分

30.3. 了解多租户子域

由于同一 OpenShift 集群域中存在多个帐户,各个帐户名称会将 OpenShift 集群域名作为子域预先填充。例如,集群中名为 user 且域为 example.com 的帐户的路由如下:

user.example.com

标准多租户部署包括:

  • 主管理员用户
  • MASTER_NAME 参数定义的 master 管理门户路由:

    <MASTER_NAME>.<WILDCARD_DOMAIN>
  • 帐户管理员用户
  • TENANT_NAME 参数定义的帐户管理门户路由:

    <TENANT_NAME>-admin.<WILDCARD_DOMAIN>
  • 帐户的开发人员门户路由:

    <TENANT_NAME>.<WILDCARD_DOMAIN>
  • 生产路由并暂存嵌入式 APIcast 网关:

    <API_NAME>-<TENANT_NAME>-apicast-staging.<WILDCARD_DOMAIN>
    <API_NAME>-<TENANT_NAME>-apicast-production.<WILDCARD_DOMAIN>
    This example illustrates the output users and routes of a standard multitenant deployment of 3scale:
    ----
    --> Deploying template "3scale-project/3scale-api-management" for "amp.yml" to project project
    3scale API Management
    ---------
    3scale API Management main system
         Login on https://user-admin.3scale-project.example.com as admin/xXxXyz123
         ...
         * With parameters:
          * ADMIN_PASSWORD=xXxXyz123 # generated
          * ADMIN_USERNAME=admin
          * TENANT_NAME=user
          ...
          * MASTER_NAME=master
          * MASTER_USER=master
          * MASTER_PASSWORD=xXxXyz123 # generated
          ...
    --> Success
        Access your application via route 'user-admin.3scale-project.example.com'
        Access your application via route 'master-admin.3scale-project.example.com'
        Access your application via route 'backend-user.3scale-project.example.com'
        Access your application via route 'user.3scale-project.example.com'
        Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
        Access your application via route 'api-user-apicast-production.3scale-project.example.com'
        Access your application via route 'apicast-wildcard.3scale-project.example.com'
        ...
    ----

master admin 添加的其他帐户将根据其名称分配一个子域。

30.4. 删除租户帐户

30.4.1. 通过管理门户删除帐户

通过这个过程,帐户会被计划删除,并在 15 天后删除。在调度删除期间:

  • 用户无法登录帐户。
  • 该帐户无法编辑,但主节点可以将帐户恢复为 批准 状态。

此外,租户的域(管理员域和开发人员门户)不可用,类似于实际删除。

先决条件:

步骤

  1. 要查看帐户列表,请导航到 Accounts
  2. 点击您要删除的帐户。
  3. 单击帐户名称旁边的 Edit
  4. 在帐户详情页面中,单击 Delete 图标。
  5. 确认删除。

30.4.2. 通过控制台删除租户

如果要删除具有即时效果的帐户,您可以通过控制台完成此操作:

  1. 使用以下命令打开控制台:

    oc rsh -c system-master "$(oc get pods --selector deploymentconfig=system-app -o name)"
    bundle exec rails console
  2. 使用以下行立即删除:

    tenant = Account.find(PROVIDER_ID)
    tenant.schedule_for_deletion!
    DeleteAccountHierarchyWorker.perform_later(tenant)

    每行的工作方式如下:

    • 第 1 行:查找帐户并将其保存在变量 租户 中。
    • 第 2 行:计划要删除的帐户。只有在您尚未通过管理门户计划删除时,才需要这样做。
    • 第 3 行:仅当您计划删除帐户或暂停删除时,才会在后台进程中删除租户。如果帐户处于 批准 状态,则不会继续删除。

30.5. 恢复租户帐户

恢复租户帐户意味着恢复计划删除的帐户。您可以在调度删除后最多恢复租户帐户 15 天。

恢复帐户后:

  • 所有以前的应用都存在。
  • 所有历史统计数据仍保留。
  • 所有有效的令牌再次有效。
  • 应用开始再次授权.

先决条件:

  • 登录您的 master admin 帐户。

步骤

  1. 要查看帐户列表,请导航到 Accounts
  2. 点击您要删除的帐户。
  3. 在帐户详细信息下,点击 Resume
  4. 单击确定以确认要恢复该帐户。

部分 VII. Analytics

第 31 章 实施 3scale API 分析以管理和优化 API 访问

通过实施 3scale API 分析来管理和优化 API 访问,您可以跟踪一段时间内的使用量趋势等项目。了解如何使用您的 API 是管理流量、配置峰值和识别向 API 发送最多请求的用户的关键步骤。

3scale 收集您可以在以下级别上定义的方法和指标的 API 分析:

  • 产品:hits 是跟踪 API 流量的内置指标。您可以在 API 中创建附加指标和指定方法以捕获分析。
  • 后端:3scale 将方法和指标注册到后端,就如同使用 API 后端从属于每个产品一样。您可以在产品级别上为应用程序计划中的后端指标设置限值和定价规则。
  • Application:您可以获取在 3scale 中创建的每个应用程序的分析报告。

先决条件

  • 您完成了入门说明

    通过使用 入门 指南,您可以使用现有的 3scale 代码插件之一来执行集成。

  • 或者,按照与其他集成方法类似的流程进行操作。请参阅文档中的操作 APIcast 章节,以了解更多有关可用的集成选项的信息。

31.1. 3scale API 指标和方法捕获 API 的使用

3scale 充当您的 API 产品统计的无限可扩展数据存储库。您可以使用指标和方法捕获 API 产品统计信息,以便您可以获得优化管理对 API 的访问所需的信息。例如:

  • Hits/transactions: 对 API 产品的调用。默认情况下,点击作为所有 API 的指标包括。命中可以是对 API 产品的整体调用,也可以划分成 API 产品的不同方法。
  • 数据传输:通过 API 产品上传和下载的 MB/GB 数据数量
  • CPU 小时 :与 API 产品调用相关的计算时间(或某些其他内部资源)
  • 返回的结果:返回的记录或数据对象的数量
  • 磁盘存储 :帐户使用的总磁盘存储

您可以跟踪与 API 产品相关的更多指标。3scale 可以跟踪任意数量的指标和方法,只要它是可随着时间递增的可数。

选择了要使用的指标后,请使用将指标 添加到产品和后端中所述的步骤在管理门户中注册。

您可以将指标和方法添加到您选择的产品或后端。为他们提供友好的名称和系统名称,3scale 在插件配置中使用。有关创建方法和指标的详情,请参阅指定 方法和添加用于捕获使用详情的指标

31.2. 配置 3scale 插件来捕获 API 指标

当 3scale 准备好使用您要跟踪的指标的名称时,您需要配置插件来报告这些指标。执行此操作的具体方式取决于所使用的插件或集成方法。默认情况下,插件只报告 Hits、API 事务、指标。

先决条件

  • 您必须已经为产品和/或后端配置了指标。

步骤

  1. 根据传入 API 调用确定,将适当的 metric/method 名称传递给插件。

    metric/method 值和所需的递增是插件公开的授权和/或报告方法的参数。

  2. 使用指标中的 System name 方法报告特定 API 方法的流量。

    这会自动递增报告方法和 Hits 指标的计数器。

  3. 在管理门户中,在 Account Settings > Integrate → 3scale API Docs 下,使用 3scale 服务管理 API 报告流量。

如需有关不同端点的更多信息,请参阅 3scale API 文档,位于管理门户的 Account Settings > Integrate → 3scale API Docs 部分。

31.3. 查看 3scale API 后端分析

您可以查看配置为后端的给定 API 的流量数据。流量 页面显示对端点的点击。

先决条件

步骤

  1. 在 Admin Portal 仪表板中,导航到 [Your_backend_name] > Analytics
  2. 选择报告的时间范围。您可以选择显示最后 24 小时、7 天、30 天、12 个月,或者表示一个时间。
  3. 可选:选择 Hits 以外的分析,方法或其他顶级指标。

    • 您将在图表中看到结果。如果没有要报告的流量,您将看到以下信息:选择期间没有可用的数据
  4. Download CSV 链接,将数据下载到 CSV 文件中。

31.4. 发送测试请求以确认用于捕获 API 指标的插件配置

在 API 和 3scale 之间建立连接,以便您可以将流量发送到 API 产品,并在 API 分析仪表板中观察其注册。

先决条件

  • 3scale 开发人员帐户
  • 使用 API 凭证的 3scale 应用程序

步骤

  1. 导航到 Audience > Applications > Listing,以查看现有应用程序的列表。
  2. 通过单击应用的名称来选择应用。
  3. 查找所选应用程序的 API 凭据。凭据取决于所选的身份验证类型,可以是用户密钥(API 密钥)、应用 ID 和应用密钥,或者客户端 ID 和客户端机密。

    有关可用身份验证模式的更多信息,请参阅身份验证模式

    图 31.1. API 凭证

    API 凭证
  4. 使用这些键以常规方式调用您的 API。例如,使用 cURL 从命令行使用 cURL 或通过 GET 方法从浏览器中获取 API 端点。进行的确切调用取决于 API 产品上的方法结构。这些调用的流量会出现在 API 产品的分析部分中。

后续步骤

默认情况下,使用量统计通过管理门户和通过开发人员门户创建应用程序的开发人员查看 API 提供程序。每个开发人员只能看到自己应用的用量统计。您可以隐藏开发人员门户中的分析视图,以进一步控制看到视图的人员。有关自定义开发人员门户的更多信息,请参阅创建开发人员门户

除了分析部分的使用情况图外,您还可以使用分析 API 访问分析数据。3scale 分析 API 是一种灵活的方式,能够以 XML 或 JSON 格式提取 API 产品的所有分析数据。

31.5. 3scale API 缺少分析时的故障排除技术

如果 [Your_product_name] > Analytics > Traffic 中的使用图表没有显示流量,请执行以下检查。

  • 授权/报告调用是否正确响应?

    所有插件调用 3scale 服务管理 API,它已预先确定的响应代码。对有效密钥的授权调用应返回 HTTP 代码 200 的响应。报告调用应该使用代码 202 响应。

  • 集成错误控制台中是否存在错误?

    3scale 检测到的集成错误日志可在 [your_product_name] > Analytics > Integration Errors 中找到。

  • 是否使用了正确的指标和方法名称?

    失败的最常见原因是报告调用中传递的方法和指标名称与管理门户 API 设置中创建的名称不匹配。检查您是否为各个指标/指标使用正确的 系统名称

  • 是否正确映射到指标?

    如果映射规则未正确映射到指标,您可能无法在分析中看到数据。检查 API 产品和 API 后端的映射规则是否已正确映射到指标:

    • 产品:在 Admin Portal Dashboard 中,导航到 [Your_product_name] > Integration > Methods & Metrics
    • 后端:在 Admin Portal Dashboard 中,导航到 [Your_backend_name] > Methods & Metrics

第 32 章 导出 3scale API 分析超过内置功能

创建扩展内置 3scale 分析功能的脚本,以便您可以检索默认情况下不在功能中提供的信息。

通过使用帐户管理和分析 API(仅限企业版),您可以创建脚本以检索您首选格式所需的信息。此处描述的用例可以用来帮助您自行获取 3scale 所需的数据。

自定义脚本的原因

3scale 不断改进 API 控制面板中提供的功能。但是,您可能比我们的发展计划领先,而且尚不支持非常具体的需要。

为了满足 API 管理需求,3scale 管理门户提供了访问所有数据所需的工具。它需要资源来编写脚本,但是自定义脚本可让您全面灵活性和控制来实施各种用例。

32.1. 使用 3scale 提取应用相关数据的示例

一个客户每周上千名新开发人员。该客户可以解决入职的某些方面,因为 3scale 提供关键配置、注册工作流和电子邮件通信等自动化需求。然而,有些问题无法与 3scale 相关,这对于他们而言非常重要。

由于客户入职许多人,公司需要采用直进的方式,根据他们与 API 的合作,对新开发人员进行分类,以便他们的运营和营销团队能够更有效地与新开发人员互动。至少需要的详细信息,3scale 提供的内置分析工具尚不提供此类功能。但是,可以使用 3scale 帐户和分析 API 提取数据,因为系统中所有数据都可用。

Example:客户要求

他们希望了解过去 10 天内有多少新开发人员注册了免费评估计划,划分了不同的方式。

首先,他们想要知道注册的开发人员数量,但从未使用过其 API。

其次,他们希望将已使用 API 的开发人员分成两个组:

  • 使用它的开发人员一段时间 - 比如 10 天的前半天,然后停止使用 API。这些开发人员尝试过,但不再活跃。
  • 始终使用 API 的开发人员.对于这些,他们想要了解增长百分比(或下降)。

此信息可在 3scale 内置分析中找到。问题是没有可以合并的视图,这导致整个体验非常繁琐。

32.2. 在自定义过程中提取 3scale 应用程序分析

要提取应用程序分析,首先要使用 ActiveDocs。3scale ActiveDocs 在您的管理门户中包括在 Account Settings > Integrate > 3scale API Docs 下。3scale 将其所有 API 都作为 ActiveDocs 提供,因此您可以从浏览器中尝试它们。这样,您可以找到最能满足您需求的请求,获取请求(curl)并获取响应。下图提供了一个 ActiveDocs 示例:

DIY 分析

这是 API 请求的 ActiveDocs,用于获取脚本将要提取分析的所有应用的 ActiveDocs。

  • 使用 ActiveDocs 完成研究后,使用所选脚本语言指定请求。这个示例使用 Ruby。
  • 重复上述操作,直到您拥有一个可以正常工作的脚本。例如扩展分析,该脚本 以 gist 用户身份提供。您可以在您的帐户中试用。

ActiveDocs 可让您快速了解 API 能够做什么。然后,需要了解您想要执行的任务需要哪 3 个或 4 个请求,并将脚本放在一起。

以下流程演示了实现示例客户所需自定义分析的步骤。

步骤

  1. 检索应用的完整列表。此操作需要分页。

    def api_call_applications_list(domain, provider_key)
      done = false
      res = Array.new
      page = 1
    
          while !done
        url = "https://#{domain}/admin/api/applications.xml?provider_key=#{provider_key}&page=#{page}&per_page=100"
        page += 1
        response = RestClient.get url
        raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
        document = Nokogiri::XML(response.to_str)    done = document.xpath("applications/@current_page").text == document.xpath("applications/@total_pages").text
        document.xpath("//application").each do |item|
          app = Hash.new
          app["created_at"] = DateTime.parse(item.xpath("created_at").text)
          app["plan_name"] = item.xpath("plan/name").text
          app["service_id"] = item.xpath("plan/service_id").text
          app["account_id"] = item.xpath("user_account_id").text
          app["id"] = item.xpath("id").text
          res << app
        end
      end
      return res
    end
  2. 过滤不符合标准的应用程序,即计划必须"评估"且必须更新 10 天。

    def filter_applications(domain, provider_key, plan_name, num_of_days)
      res = api_call_applications_list(domain, provider_key)
      res.each do |item|
        res.delete(item) if item["plan_name"] != plan_name
        res.delete(item) if item["created_at"] > (DateTime.now - num_of_days)
      end
      return res
    end
  3. 对于符合条件的每个应用程序,获得其使用,即应用程序在过去 10 天中的点击次数。

    def api_call_application_usage(domain, provider_key, application_id, metric, from, to, granularity)
      url = "https://#{domain}/stats/applications/#{application_id}/usage.xml?provider_key=#{provider_key}&metric_name=#{metric}&since=#{from}&until=#{to}&granularity=#{granularity}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      return document.xpath("//usage/data/values").text.split(",")
    end
  4. 将应用交叉引用帐户,因为开发人员的信息存储在帐户对象中。

    def api_call_account_read(domain, provider_key, account_id)
      url = "https://#{domain}/admin/api/accounts/#{account_id}.xml?provider_key=#{provider_key}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      account = Hash.new
      account["email"] = document.xpath("//users/user/email").text
      account["name"] = document.xpath("//users/user/first_name").text + " " + document.xpath("//users/user/last_name").text
      return account
    end
  5. 将所有内容放在一起以完成脚本。您有一个获取 3scale 内置分析中没有的信息的脚本。您还可以 以 gist 形式获得完整的脚本

第 33 章 查看应用程序的 3scale 内置流量分析

要识别需要支持和操作保证增强的帐户,请查看有关应用程序流量的可视化信息。使用 API 的每个应用在 3scale 系统中都有一个流量追踪,可以从管理门户查看,也可通过 API 进行恢复。

先决条件

  • 3scale 开发人员帐户
  • 使用 API 凭证的 3scale 应用程序

步骤

  1. 导航到您要查看分析的应用程序。

    您可以在 Audience > Accounts > ListingAudience > Applications > ListingApplications 选项卡下找到应用程序。或者,您也可以按照查找应用程序指南中介绍的步骤来 搜索应用程序

  2. 找到应用程序后,您将看到一个概览页面,其中包含有关应用程序的信息,如下图所示:

    应用程序显示
    表 33.1. 镜像中标记的项目对应于以下信息
    数字应用信息

    1

    开发人员提供的应用程序名称

    2

    为应用程序捕获的元数据(如何设置要在高级部分捕获的数据)

    3

    应用程序的状态 - 它是活动还是暂停?

    4

    应用具有的当前 API 标识符、密钥和证书。视图根据您要用于将 API 集成到 3scale 的身份验证方法而有所不同。

    5

    应用的流量统计概述

    6

    有关应用程序计划应用程序所基于的信息,以及应用哪个速率限值的信息。

  3. 单击应用程序名称上方的 Analytics 链接。此时会显示应用程序的使用图表。通过控制指标、方法和时间范围,您可以检查应用的不同类型的数据。

第 34 章 为您的 API 设置和评估 3scale 响应代码日志

要查看您的客户端如何使用 API,并实时查看您的服务器是否按预期运行,请设置并使用 3scale 中的响应代码日志。

步骤

  • 在启动使用 DockerOpenShift 部署的 APIcast 网关时,将 APICAST_RESPONSE_CODES 环境变量设置为 1true。这可实现响应代码跟踪。

示例

启用后,APIcast 网关会捕获上游服务为授权调用返回的 API 响应的 HTTP 状态代码,并将它们发送到服务管理 API(在 authrep 调用中)。Example:

https://su1.3scale.net/transactions/authrep.xml?service_token={SERVICE_TOKEN}&service_id={SERVICE_ID}&user_key={USER_KEY}&usage%5Bhits%5D=1&log%5Bcode%5D=200"

在本例中,发送log[code]=200,这意味着 API 用 200 状态代码响应。

验证

要验证集成,使用有效的 3scale 凭证对 API 产品执行调用,然后验证在 Analytics > Usage 页面中是否正确报告了调用。

注意
  • 响应代码跟踪不是所有响应的准确计数。
  • 此视图的值是在一段时间内提供趋势的可视化表示。
  • 响应代码跟踪和 3scale Auth 缓存模式:none 不是受支持的组合。
使用屏幕

如果一切进展顺利,请访问 Analytics >Response codes 页面。您应该可以看到一个图形,其中含有用颜色划分的最新流量,具体取决于响应是 2xx、4xx 或 5xx。

响应代码屏幕

图形工具可让您查看响应代码历史记录。您还可以检查响应代码统计信息的不同时段和不同粒度级别。单击时间选择栏,再定义符合您需求的时间周期和粒度。

法律通告

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.