管理员门户指南

Red Hat 3scale API Management 2.9

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

摘要

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

前言

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

部分 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.9
  • 按照开发人员门户文档中的配置 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 管理门户有两种类型的用户:

  • 管理员: 可以全面访问所有区域和服务,并可以邀请其他成员(如果计划允许)。
  • 成员: 虽然对产品区域具有有限的访问权限(例如,分析、开发者门户)以及(如果您是企业客户,还是服务)。

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

3.1. 导航至用户管理

要查看 3scale 安装的用户列表,请在管理门户页面中按照以下步骤执行:

  1. 在导航栏中,单击位于窗口右上角的齿轮图标。
  2. 从左侧菜单中导航到 Users > Listing

3.2. 发送邀请

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

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

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

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

3.3. 接受邀请

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

3.4. 授予新用户权限

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

  • 按区域:如作为分析、计费或开发人员管理。
  • 按服务 :选择哪些服务为您的所有服务提供成员的访问权限。注意 :这个功能仅适用于企业客户。

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

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

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

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

  • Developer accounts — Applications: 用于访问 Account management API
  • 分析:提供对分析 API 的访问权限
  • 账单:提供对 Billing API 的访问权限
按地区和服务的权利

第 4 章 通知

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

4.1. 通知类型

有不同类型的通知:

  • 帐户
  • 账单
  • 应用程序
  • 服务订阅
  • 使用警报

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 进行身份验证 - Billing、帐户管理和分析 - 并使用我们的 ActiveDocs(互动文档)尝试它们。了解有关 3scale 令牌 的更多信息.
    • 通知首选项 :选择您要收到的通知。注意:如果您是企业客户,并且如果您是成员,则根据地区和服务对其进行过滤。这意味着您只能订阅有关已获得访问权限的区域和服务通知。有关通知首选项的更多信息。

第 6 章 令牌

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

3scale 有两种类型的令牌: 访问令牌 (由用户创建)和 Service 令牌 (在 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 帐户的用户共享。

您可以在管理门户的 Dashboard: Account Settings(gear icon)> Personal > Tokens 中查找用户可访问的服务的服务帐户令牌。

部分 II. 多租户

第 7 章 多租户

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

7.1. Master 管理门户

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

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

7.1.1. 访问主管理门户

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

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

<MASTER_NAME>.<WILDCARD_DOMAIN>

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

Master Admin Portal 标记

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

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

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

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

    1. 机构/组名称
  6. 点击 Create

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

7.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 相比)。

7.2. 管理帐户

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

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

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

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

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

  • 应用程序
  • 用户
  • 邀请
  • 组成员身份
  • 机构/组名称

7.2.2. 通过 API 调用管理帐户

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

Master API 部分

7.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 添加的其他帐户将根据其名称分配一个子域。

7.4. 删除租户帐户

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

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

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

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

先决条件:

流程

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

7.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 行:仅当您计划删除帐户或暂停删除时,才会在后台进程中删除租户。如果帐户处于 批准 状态,则不会继续删除。

7.5. 恢复租户帐户

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

恢复帐户后:

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

先决条件:

  • 登录您的 master admin 帐户。

流程

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

部分 III. 服务发现

在后续章节中,您将找到有关服务发现的信息:3scale 功能,可帮助您从 OpenShift 集群导入服务。

第 8 章 服务发现

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

8.1. 关于服务发现

通过使用服务发现,您可以扫描以查找在同一 OpenShift 集群中运行的可发现 API 服务,并将关联的 API 定义自动导入到 3scale 中。

您还可以随时更新 API 集成和 Open API 规格,以便稍后与集群重新同步它们。

服务发现提供以下功能:

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

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

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

8.1.1. 可发现服务的标准

如果要 3scale 在 OpenShift 集群中查找 API,则 API 必须满足以下条件:

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 对象的更多信息,请参阅 关于网络策略

8.2. 配置 OpenShift 以启用服务发现

作为 3scale 管理员,您可以使用或不使用 Open Authorization(OAuth)服务器来配置服务发现。

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

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

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

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

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

作为 3scale 系统管理员,您可以使用 OpenShift 内置的 OAuth 服务器来单独验证和授权 3scale 来发现 API。

先决条件

  • 您必须将 3scale 2.9 部署到 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

其他备注

如需有关 OpenShift OAuth 令牌的更多信息,请配置内部 OAuth 服务器

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

作为系统管理员,您可以使用 Red Hat Single Sign-On for OpenShift 来单独验证并授权 3scale 发现服务。

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

先决条件

  • 您必须将 3scale 2.9 部署到 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 以应用更改。

其他备注:

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

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

先决条件

  • 您必须将 3scale 2.9 部署到 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 所述。

8.3. 导入发现的服务

在 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. 从管理门户的控制面板,单击 New API
  3. 选择 Import from OpenShift

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

后续步骤

有关管理 API 的信息,请参阅 Red Hat 3scale API 管理文档

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

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

先决条件

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

流程

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

后续步骤

有关管理 API 的信息,请参阅 Red Hat 3scale API 管理文档

8.5. 更新服务

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

先决条件

  • 该服务之前从集群中导入。

流程

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

部分 IV. Access control

第 9 章 定义 API(Methods 和 Metrics)

您可以通过在 API 产品和后端级别添加方法和指标来定义 API。API 产品是一个或多个 API 后端的捆绑包。通过产品级别,方法和指标允许您为任何产品应用程序计划设置限制和定价规则。在后端级别,可以使用方法和指标来设置捆绑后端任何产品的应用程序计划的限制和定价规则。

在产品和后端级别,指标 都适合跟踪您的 API 的使用。Hits 是每个 API 中存在的内置指标,用于跟踪对您的 API 发出的点击。您可以通过在 Hits 指标下定义 Methods,实现对 API 使用跟踪的精细。向方法报告流量会自动增加方法和 Hits 指标的计数器。您可以为 API 后端的每个端点或端点和 HTTP 方法组合定义单独的方法。请参阅 Mapping 规则 部分,了解如何将 API 的端点映射到此处定义的方法。

对于除点击外的 API 测量使用情况,您可以定义一个新的Metric(指标数据),并在不同的单元中报告使用情况。一个单位应该可以量化并应用适合您的业务目标的意义,如兆字节、CPU 时间、API 返回的元素数等等。3scale 默认不会不包括除 hits 之外的指标(如 CPU 时间或 mb ),这些指标数据需要使用用户配置的外部服务定期调用端点来获得。

方法和指标也是打包 API 的方法和指标:每个应用程序计划都允许您为每个方法和指标定义不同的使用限值和定价规则。请参阅 API analytics 部分,了解更多有关报告到指标和方法的使用的信息。

其它资源

有关 API 产品和后端的详情,请参阅 开始使用 3scale

9.1. 添加方法和指标

要在产品或后端添加新方法,请按照以下步骤执行:

  1. 导航到 [Your_product_name] > Integration > Methods & Metrics or [Your_backend_name] > Methods & Metrics
  2. 单击 New method 链接,它位于方法列表上方的右侧。
  3. 指定参数:

    • 友好名称是方法的简短描述,它显示在 3scale 管理门户的不同部分中。此名称对于产品必须是唯一的。
    • 系统名称是用于通过 3scale 服务管理 API 报告使用情况的方法名称。它还必须是唯一的,且它应该仅包含字母数字字符、下划线 _、连字符 - 和正斜杠 /,没有空格。除此之外,您可以自由地确定系统名称是什么,它可以与端点(/status)完全相同,或者可以包括方法和路径(GET_/status)。
    • Description 字段可用于更加详细地描述方法,它是可选的。

      新方法详情
  4. 最后,单击创建方法

您稍后可以更改该方法的定义。只需单击方法名称(在列中的 Method 中),更新字段并单击"更新方法"。

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

要创建新指标,请单击 New metric 并提供所需参数。在指定单元时,使用单调式 noun(如 "hit"),因为它将在分析图表中自动复数。

这些新方法和指标将在您的当前和未来的计划中可用。现在,您可以通过进入 [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit] 为每个计划编辑限制和定价规则。

9.2. 自动导入方法和指标

如果您的 API 具有很多端点,我们提供了在 3scale 上自动创建方法和指标的另外一种方法:

第 10 章 应用计划

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

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

默认情况下,当您创建 3scale 帐户时,会给出两个计划: Basic 和 Unlimited。您可以保留并编辑这些设置,也可以自行创建。您可以根据需要创建更多计划。

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

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

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

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

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

选择默认应用程序计划:

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

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

第 11 章 映射规则

通过添加方法和指标 定义 API 后,您可以将 API 端点或路径映射到您在定义页面中定义的方法。要做到这一点:

  1. 导航到 [Your_product_name] > Integration > Mapping Rules
  2. 单击 Add Mapping Rule 链接。
  3. 选择 HTTP 方法、模式、指标(或方法)及其递增。
  4. 单击 创建映射规则 按钮。
  5. 要验证映射规则,请导航到 [Your_product_name] > Integration > Methods & Metrics。每一方法和指标在映射列中应具有一个复选标记。

    Mapping Rules verified

第 12 章 调配付费计划

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

12.1. 决定您的定价模式

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

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

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

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

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

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

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

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

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

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

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

12.3. 创建进一步的定价层

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

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

12.4. 配置付费计划

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

12.5. 其他参考资源

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

第 13 章 置备速率限制

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

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

13.1. 配置应用程序计划

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

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

13.2. 设置速率限值

设置速率限值:

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

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

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

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

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

13.4. 更多信息

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

部分 V. 账单

第 14 章 配置 Billing 设置

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

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

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

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

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

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

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

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

14.3. 货币(收费和网关)

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

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

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

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

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

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

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

14.6. YAML 配置

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

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

    • Braintree
    • Stripe

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

14.6.2. 验证新国家

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

流程

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

14.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 包括年、月和发票编号。示例:2018-02-00000013
yearly
YYYY-XXXXXXXX,即仅包括年和发票编号。示例: 2018-00000001

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

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

14.8. 信用卡政策

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

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

14.9. 信用卡网关

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

  • Braintree
  • Stripe

14.9.1. 条带集成(推荐)

完成这些步骤后,您要将 Stripe 配置为您帐户的支付网关。这将使开发人员输入他们的信用卡详细信息,并根据计算的发票,自动通过 Stripe 访问您的 API。

如果您为付费 API 启用信用卡付款,则一个关键步骤是设置您的 支付网关。您可以将多个替代支付网关用于 3scale 帐户。在这里,我们将介绍 Stripe 的步骤。

14.9.1.1. 先决条件

在开始这些步骤前,您将需要打开一个 Stripe 的帐户。

14.9.1.2. 从 Stripe 获取您的 API 密钥

登录到您的 Stripe 帐户,并在 https://dashboard.stripe.com/account/apikeys 获取您的 API 密钥。您需要两个键:一个"secret",以及一个"可发布"一个。当您准备好启动慈善时,请使用"test"设置。

条带集成

14.9.1.3. 在 3scale 中配置设置

您需要告诉 3scale 使用这些 API 密钥。要做到这一点,登录到 3scale 管理门户,然后进入 Audience > Billing > Charging & Gateway

账单页

如果 Charging Enabled 标志未激活,请启用它并单击 Save。

启用收费

您应该会在页面底部附近看到一个名为 Gateway 的下拉列表。将其更改为条带.

账单网关

下拉菜单下的表单应更改为显示两个字段。插入您的 Stripe API 密钥并点 Save。

条状账单网关

更改支付网关时,您可能会看到一些警告。这是预期的。读它们并接受它们(如果出现)。

支付网关现已设置,但您的用户可能还没有使用它,因为它没有配置 CMS。前往开发者门户,然后单击名为 pay Gateway / Show on the left navigation 窗格的模板。

开发人员门户 - Billing

如果还没有存在,在 {% "braintree_blue" %} 前添加以下代码:

{% when "stripe" %}
 <p><a href="{{ current_account.edit_stripe_billing_address_url }}">Edit billing address</a></p>

 {% if current_account.has_billing_address? %}
   {% stripe_form "Edit Credit Card Details" %}
 {% else %}
   <p>After entering billing address, the option to enter credit card will be enabled.</p>
 {% endif %}

最后,单击 Save and Publish。您的用户现在应该可以使用 Stripe 网关来支付。

注意

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

14.9.2. Braintree 集成

以下是设置 Braintree 网关以收费使用 API 的步骤。

14.9.2.1. 从 Braintree 获取您的 API 密钥

您需要使用 Braintree 打开一个客户。您需要一个网关和 Merchant 帐户加上 Vault。作为可选的额外选择,您可以选择允许 American Express 卡作为支付方式。

首先,登录到您的 Braintree 帐户。然后,在 Account > MyUser 区域中找到您的 API 密钥:

Braintree 设置

API 密钥页面仍然隐藏私钥,因此请选择查看它的选项:

Braintree 键

最后,您有 3scale 账单设置所需的公钥、私钥和 Merchant ID:

Braintree 键

14.9.2.2. 在 3scale 中配置设置

您需要告诉 3scale 使用这些 API 密钥。要做到这一点,登录到 3scale 管理门户,再进入 Audience > Billing > Charging & Gateway

确保账单页面中指定的货币类型与 Braintree merchant 帐户中使用的货币类型相符。

账单

如果 Charging Enabled 标志未激活,请启用它并单击 Save。

Billing charging enabled

您应该会在页面底部附近看到一个名为 Gateway 的下拉列表。将它更改为 Braintree(Blue Platform)。

Billing Gateway

下拉菜单下的表单应更改为显示两个字段。插入 Braintree 键并点 Save。

Ogone billing gateway

更改支付网关时,您可能会看到一些警告。这是预期的。读取并接受(如果它们显示)。

您的用户现在应该能够使用 Braintree 网关支付费用。

注意

要将 Braintree 中的数据映射到 3scale 上的数据,您可以使用名为 customer.id 的 Braintree 字段,它由 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID]组成。

14.9.2.2.1. 故障排除

如果您的帐户处于沙盒模式,并且您遇到任何问题,您必须将其更改为生产。

第 15 章 定价

本节论述了您可以向开发人员支付使用 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.

15.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 请求通过映射规则映射到这些指标和方法。

15.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 十进制位置的数字。

15.3. 更新现有的定价规则

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

第 16 章 账单

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

16.1. 列出发票

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

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

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

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

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

16.2. 发票视图

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

16.2.1. 发票详情

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

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

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

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

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

16.2.2. 编辑发票

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

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

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

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

16.3. 发票状态

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

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

16.4. 自动计费流程

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

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

16.4.1. 在每个月的第一天

Postpaid

  • 上个月的 Bill 变量成本:该成本作为开放发票的项包括。
  • 完成上个月的开票
  • Bill 固定于当前月份的成本: 为当前 月在 Open 状态创建新发票。

Prepaid

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

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

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

16.4.2. 每天

  • Bill 到期的试用以及尚未计费的新合同:正在为当前月份创建开放状态的 Invoices。
  • 预付费 :最后将所以处于开发状态的发票的状态改为 Finalized
  • 问题发票:状态更改为 Pending.

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

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

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

16.4.3. 自动和手动发票

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

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

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

16.4.4. 月中升级

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

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

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

  • Billing 的模式:PrepaidPostpaid
  • 当计划更改时

16.4.4.1. 预付账单

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

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

    描述Cost

    固定费用('Plan A')

    200

    退款('Plan A')

    -200

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

    300

    总计

    300

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

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

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

      示例: 在每月第一天为 Plan A(200$)注册的客户,然后在每月的中间升级到计划 B(300$)。将生成以下发票:

      描述Cost

      固定费用('Plan A')

      200

      总计

      200

      描述Cost

      退款('Plan A')

      -100

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

      150

      总计

      50

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

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

16.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 日之后,计算结果在发票(包括单独退款和收费)中更清楚地反映,而总成本则与以前相同。

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

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

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

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

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

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

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

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

16.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 提供程序。

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

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

16.7. VAT 速率/销售税

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

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

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

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

16.7.3. 为帐户设置 VAT 值

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

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

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

16.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 读取和写入。

16.8. 开发人员门户视图

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

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

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

注意

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

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

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

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

16.9. 信用卡流

16.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 %}

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

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

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

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

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

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

第 17 章 电子邮件通知

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

17.1. 供应商通知

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

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

注意:3scale 帐户的所有管理员用户如果订阅了账单,将收到关于账单的通知。

17.2. 开发人员电子邮件

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

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

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

17.2.1. 账单电子邮件地址

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

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

第 18 章 账单 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

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

第 19 章 添加开发人员

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

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

19.1. 创建新开发人员帐户

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

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

创建新开发人员帐户

19.2. 设置应用程序

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

将应用程序添加到新帐户

19.3. 通知开发人员

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

第 20 章 批准开发人员

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

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

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

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

20.2. 帐户批准

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

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

开发人员批准帐户注册

20.3. 服务批准

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

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

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

开发人员批准服务订阅

20.4. 应用程序批准

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

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

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

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

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

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

第 21 章 更改应用程序计划

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

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

注意

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

21.1. 更改帐户计划

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

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

开发人员更改帐户计划

21.2. 更改服务计划

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

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

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

更改服务计划

21.3. 更改应用计划

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

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

为多个应用程序更改计划

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

更改应用程序计划

21.3.1. 更多信息

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

第 22 章 联系开发人员

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

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

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

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

帐户视图

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

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

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

发送消息

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

22.3. 通过其他方法联系

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

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

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

第 23 章 自定义计划

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

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

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

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

23.1. 选择帐户

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

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

23.2. 选择应用程序

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

选择应用程序

23.3. 自定义应用计划

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

自定义计划

23.3.1. 更多信息

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

第 24 章 启用注册

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

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

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

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

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

第 25 章 查找应用程序

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

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

25.1. 获取您需要的信息

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

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

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

25.2. 搜索应用程序

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

查找应用程序第 1 部分.

25.3. 访问应用程序信息

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

查找应用程序第 2 部分

第 26 章 邀请开发人员

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

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

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

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

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

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

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

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

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

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

注意

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

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

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

第 28 章 挂起应用程序

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

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

28.1. 查找应用程序

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

28.2. 禁用应用程序

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

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

挂起应用程序
注意

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

28.3. 联系开发人员

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

联系开发人员

第 29 章 取消应用程序

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

选项 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 的操作。

第 30 章 删除 API

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

删除 API:

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

部分 VII. Analytics

第 31 章 API 分析

本指南旨在帮助您调整 API 分析,以跟踪您需要了解的项目,如检查一段时间内最常使用的应用程序和趋势。了解您的 API 如何使用是管理流量的关键步骤,配置峰值,以及识别大多数向 API 发送请求的用户。

3scale 通过您可以在这些级别中定义的方法和指标跟踪 API 分析:

  • 产品:除了映射到后端级别 Hits 指标及其方法的所有点击外,Hits 指标数据会计算到 Hits 本身以及到它的相关方法的击中数量。
  • 后端:3scale 将方法和指标注册到后端,就如同使用 API 后端从属于每个产品一样。您可以在产品级别上为应用程序计划中的后端指标设置限值和定价规则。
  • 应用程序:您可以获取在 3scale 中创建的每个应用程序的分析报告。

31.1. 先决条件

在使用本指南前,完成 Getting Started 部分的说明。

本指南假定您使用其中一个现有的 3scale 代码插件来执行集成。您可以遵循与其他集成方法类似的流程。检查文档中的 Operating APIcast 章节,以了解有关可用集成选项的更多信息。

31.2. 确定要跟踪的指标和方法

3scale 充当 API 产品统计的无限可扩展数据存储库,您可以跟踪 API 产品的实际指标。例如:

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

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

31.3. 创建指标和方法

选择指标后,在管理门户中注册:

  • 要在产品中添加方法和指标,请导航到 [Your_product_name] > Integration > Methods & Metrics
  • 要在后端中添加方法和指标,请导航到 [Your_backend_name] > Methods & Metrics

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

31.4. 设置报告

使用要跟踪的指标名称配置了 3scale 系统后,就可以调整插件设置来报告正确的指标。执行此操作的具体方式取决于所使用的插件或集成方法。默认情况下,插件仅报告 Hits (API 事务)指标。

要设置报告,请考虑以下内容:

  • 该应用应将适当的指标/方法名称传递到插件,具体由传入 API 调用决定。metric/method 值和所需的递增是插件公开的授权和/或报告方法的参数。
  • 当您报告特定 API 方法的流量时,在 metric 参数中使用 system name 方法。这会自动为报告的方法和 hits 指标增加计数器。
  • 您还可以使用 3scale Service Management API 报告流量。如需有关不同端点的更多信息,请参阅您的管理门户中的 3scale API ActiveDocs,位于 Documentation → 3scale API Docs 部分的管理门户中。

31.5. 检查后端的分析

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

先决条件

  • 创建 API 后端。
  • 将后端添加到 API 产品。

流程

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

    • 您将在图表中看到结果。如果没有报告流量,您会看到以下信息: 所选周期没有可用的数据

您还可以将数据下载到 CSV 文件中。为此,请点击 Download CSV 链接。

31.6. 检查应用程序的分析

API 和 3scale 建立连接后,您可以将流量发送到 API 产品,并在 API Analytics 仪表板中监视它。您需要现有的开发人员帐户和一个具有 API 凭据的应用程序才能执行本节中的步骤。按照以下步骤创建开发人员帐户并获取具有 API 凭证的应用程序:

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

    图 31.1. API 凭证

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

31.7. 控制谁查看分析

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

31.8. 通过 API 和电子邮件报告访问分析数据

除了 Analytics 部分中的使用图外,您还可通过以下方式访问分析数据:

  • Analytics API

    3scale Analytics API 是以 XML 或 JSON 格式提取 API 产品的所有分析数据的灵活方法。

31.9. 故障排除

如果分析部分的 usage chart 上没有显示流量,请执行以下检查。

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

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

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

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

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

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

  • 是否正确映射到指标?

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

    • 产品:进入 [Your_product_name] > Integration > Methods & Metrics
    • 后端:进入 [Your_backend_name] > Methods & Metrics

第 32 章 导出分析

本章论述了如何创建扩展内置 3scale 分析功能的脚本。

通过使用帐户管理和分析 API(仅限企业版),您可以创建脚本以检索您首选格式所需的信息。本章描述了特定的用例,但相同的方法可用于从 3scale 中获得您需要的数据。

32.1. 自定义脚本的原因

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

为了满足对 API 管理的需求,3scale 始终为您提供了访问所有数据的工具。但是,自定义脚本有一些成本 - 它采取一些资源来编写脚本。更为重要的是,自定义脚本为您提供了实施用例的总灵活性和控制。

32.2. 一个现实示例

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

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

32.3. 示例:客户要求

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

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

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

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

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

此问题的典型答案将是 后续的分析改进的一部分。(有趣的是通常就是这种情况。) 但如果您需要,这不会解决这个问题。我们在 3scale 上想要提供您完成所有工作的工具,而无需根据我们的发行时间表。

32.4. 实践实施

32.4.1. 获奖方法

这个方案通常可以更好地实现自定义工作。

  • tinker 有一个 ActiveDocs 的位。3scale ActiveDocs 位于您的管理门户中, Account Settings(位于右上角的 Gear 图标)> Integratione > 3scale API Docs。3scale 具有其所有 API 作为 ActiveDocs,以便您可以从浏览器中尝试它们。这样,您可以找到最能满足您需求的请求,获取请求(curl)并获取响应。一个示例…​

    DIY 分析

这是 API 请求的 ActiveDocs,用于获取在脚本上用于扩展分析的所有应用程序。

  • 在完成对 ActiveDocs 的研究后,请将请求置于脚本语言上后(我们的是最快的 Ruby)。
  • 重复上述操作,直到您拥有一个可以正常工作的脚本。例如扩展分析,该脚本 以 gist 用户身份提供。您可以在您的帐户中试用。

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

32.4.2. 逐步指南

以下是实现此客户所需自定义分析的步骤:

  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

    现在,您只需要将所有内容放在一起,脚本即完成。您有一个脚本,可获取 3scale 内置分析中尚未提供的信息。您还可以 以 gist 形式获得完整的脚本

32.5. 结论

3scale 是一个容易自我管理的系统。我们相信,任何人都应当能够扩展他们接受合同的任何服务的当前功能。正如我们想到的那样,我们可以覆盖所有基础,我们将始终是某方面的内容,无论它是超级特殊需求,还是只是因为我们正在构建其他功能。无论哪种情况,我们都想避免避免在无法立即阻止。我们为您提供数据的完全访问权限,以及能够与其配合使用的完整 API 工具集。

如果您有要与我们和 3scale 的用户共享的脚本,请将其发送给我们。我们很高兴收集并发布它们。

第 33 章 现成分析

本教程解释了如何查找有关应用程序流量的视觉信息。

使用 API 的每个应用在 3scale 系统中都有一个流量追踪,可以从管理门户查看,也可通过 API 进行恢复。

查看应用程序的流量分析:

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

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

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

    应用程序显示

    镜像中标记的项目与以下信息对应:

    1. 开发人员提供的应用的名称。
    2. 为应用程序捕获的元数据(学习如何设置在高级部分中捕获的数据)。
    3. 应用程序的状态 - 它是活动还是暂停?
    4. 应用具有的当前 API 标识符、密钥和证书。视图根据您要用于将 API 集成到 3scale 的身份验证方法而有所不同。
    5. 应用的流量统计摘要。
    6. 有关应用程序计划应用程序所基于的信息,以及应用哪个速率限值的信息。
  3. 单击应用程序名称上方的 Analytics 链接。此时会显示应用程序的使用图表。通过控制指标、方法和时间范围,您可以检查应用的不同类型的数据。

第 34 章 响应代码跟踪

本教程介绍了如何设置和使用响应代码在 3scale 系统中。

从您的 API 产品跟踪响应代码是查看客户端如何使用 API 的方法,并实时查看是否适用于所有服务器。

要启用响应代码跟踪功能,请在使用 DockerOpenShift 部署启动 APIcast 网关时将 APICAST_RESPONSE_CODES 环境变量设置为 1true

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

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。

响应代码屏幕

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