README

3scale 集成插件，用于 PHP 应用程序。3scale 是一个 API 基础设施服务，负责处理 API 密钥、速率限制、分析、计费支付和开发者管理。包括可配置的 API 仪表板和开发者门户 CMS。更多信息请访问 http://www.3scale.net/，支持信息请访问 http://support.3scale.net/。

教程

• 插件设置: https://support.3scale.net/docs/deployment-options/plugin-setup
• 速率限制: https://support.3scale.net/docs/access-control/rate-limits
• 分析设置: https://support.3scale.net/quickstarts/3scale-api-analytics

安装

从 github 下载源代码： http://github.com/3scale/3scale_ws_api_for_php 并将其放置在项目可访问的位置。

使用方法

需要 ThreeScaleClient.php 文件（假设您已将库放置在包含路径中）

require_once('lib/ThreeScaleClient.php')

然后创建客户端的一个实例

$client = new ThreeScaleClient();

注意：除非您指定 ThreeScaleClient();，否则您将需要指定一个 provider_key 参数，该参数已被服务令牌取代

$client = new ThreeScaleClient("your provider key");

由于对象是无状态的，您只需创建一个并全局存储即可。

然后您可以在客户端执行调用

$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));

$response = $client->report(array(array('app_id' => "app's id"],'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));

注意：service_id 从 2016 年 11 月起是强制性的，无论是使用服务令牌还是使用提供者密钥时都如此

授权

要授权特定应用程序，请调用 authorize 方法，传入 application id 和 service id，以及可选的应用程序密钥

$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));

如果您已配置（已弃用）提供者密钥，则应使用以下方法

$response = $client->authorize("the app id", "the app key", "service id"));

然后，在返回的对象上调用 isSuccess() 方法以查看授权是否成功

if ($response->isSuccess()) {
  // All fine, proceeed.
} else {
  // Something's wrong with this app.
}

如果提供者和应用程序 ID 都有效，则响应对象包含有关应用程序状态的其他信息

//Returns the name of the plan the application is signed up to.
$response->getPlan()

如果计划已定义使用限制，则响应包含按指标和使用限制周期分解的使用详情

// The usageReports array contains one element per each usage limit defined on the plan.
$usageReports = $response->getUsageReports();
$usageReport  = $usageReports[0];

// The metric
$usageReport->getMetric() // "hits"

// The period the limit applies to
$usageReport->getPeriod()       // "day"
$usageReport->getPeriodStart()  // 1272405600 (Unix timestamp for April 28, 2010, 00:00:00)
$usageReport->getPeriodEnd()    // 1272492000 (Unix timestamp for April 29, 2010, 00:00:00)

// The current value the application already consumed in the period
$usageReport->getCurrentValue() // 8032

// The maximal value allowed by the limit in the period
$usageReport->getMaxValue()     // 10000

// If the limit is exceeded, this will be true, otherwise false:
$usageReport->isExceeded()      // false

如果授权失败，则 getErrorCode() 返回系统错误代码，而 getErrorMessage() 返回可读的错误描述

$response->getErrorCode()       // "usage_limits_exceeded"
$response->getErrorMessage()    // "Usage limits are exceeded"

Authrep

要授权特定应用程序，请调用 authrep 方法，传入 application id 和 service id，以及可选的应用程序密钥

$response = $client->authrep("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));

然后，在返回的对象上调用 isSuccess() 方法以查看授权是否成功

if ($response->isSuccess()) {
  // All fine, proceeed.
} else {
  // Something's wrong with this app.
}

如果提供者和应用程序 ID 都有效，则响应对象包含有关应用程序状态的其他信息

//Returns the name of the plan the application is signed up to.
$response->getPlan()

您还可以在 authrep 调用期间使用其他模式，例如 user_key 模式

$response = $client->authrep_with_user_key("user_key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));

报告

要报告使用情况，请使用 report 方法。您可以同时报告多个事务

$response = $client->report(array(
      array('app_id' => "first app's id",'usage' => array('hits' => 1)),
      array('app_id' => "second app's id", 'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));

"app_id"、"usage" 参数是必需的，还需要 service id 和 service token。另外，您还可以指定事务的时间戳

$response = $client->report(array(
  array('app_id'    => "app's id",
        'usage'     => array('hits' => 1),
        'timestamp' => mktime(12, 36, 0, 4, 28, 2010, new ThreeScaleClientCredentials("service id", "service token")));

时间戳可以是 Unix 时间戳（整数）或字符串。该字符串必须是可以由 strtotime 函数解析的格式。例如

"2010-04-28 12:38:33 +0200"

如果时间戳不是UTC时间，您必须指定时间偏移量。例如上面所用的 "+0200"（比世界协调时间快两小时）。

然后调用返回的响应对象的 isSuccess() 方法，以查看报告是否成功。

if ($response->isSuccess()) {
  // All OK.
} else {
  // There was an error.
}

如果发生错误，getErrorCode() 返回系统错误代码，而 getErrorMessage() 返回可读的错误描述。

$response->getErrorCode()    // "provider_key_invalid"
$response->getErrorMessage() // "provider key \"foo\" is invalid"

3scale服务管理API的定制后端

3scale服务管理API使用的默认URI是 http://su1.3scale.net:80。这个值可以被修改，这在插件与Red Hat 3scale API管理平台本地版本一起使用时很有用。

为了覆盖URL，在创建客户端实例时传递 自定义URI。

$client = new ThreeScaleClient(null, "http://custom-backend.example.com:8080");

插件集成

如果您有兴趣将插件与以下系统集成：

• Composer 请查看 packagist。这是由 daws.ca 技术团队友好维护的。

• Symphony2 请查看 tonivdv的3scaleBundle。这是由 Adlogix 技术团队友好维护的。

测试

运行测试： php test/all.php

法律

版权（c）2010 3scale networks S.L.，在MIT许可下发布。