3scale 中文文档教程

Question

3scale integration plugin for JavaScript/CoffeeScript/Node.js applications

3scale 是一种 API 基础设施服务，可处理 API 密钥、速率限制、分析、账单支付和开发人员管理。 包括可配置的 API 仪表板和开发人员门户 CMS。 http://www.3scale.net/ 上的更多产品资料，http://support.3scale.net/ 上的支持信息。

Installation

该模块通过包管理器 npm 交付，因此安装应该很简单：npm install 3scale

Requirements

从版本 0.6.0 开始，此插件需要使用 Node.js 版本 0.10.x或更高。

Synopsis

该插件支持对 3scale Service Management API 的 3 种主要调用：

• authrep grants access to your API and reports the traffic on it in one call.
• authorize grants access to your API.
• report reports traffic on your API.

3scale 支持 3 种身份验证模式：App Id、User Key 和 OAuth。 前两个在调用服务管理 API 时类似，它们支持 authrep。 OAuth 的不同之处在于它的用法需要两个调用：首先授权然后报告。

Usage

注意：从 2016 年 11 月开始，service_id 是强制性的。

Authrep

Authrep 是一种“一次性”操作，用于授权应用程序并同时报告相关事务。 此调用与常规 authorize 调用的主要区别在于，如果授权成功，将报告使用情况。 在 3scale 的支持网站 的活动文档页面上阅读有关 authrep 的更多信息。

这是一个示例，假设您正在使用 app_id/app_key 身份验证模式：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.authrep({ service_token: "your service token", service_id: "your service id", app_id: "your application id", app_key: "your application key", usage: { "hits": 1 } }, function(response){
  console.log(response);
});

/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port.This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.authrep({ service_id: "your service id", app_id: "your application id", app_key: "your application key", usage: { "hits": 1 } }, function(response){
  console.log(response);
});
*/

如果您在 3scale 中配置了 API 身份验证以使用 user_key 模式，这将是等同于上面的例子：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.authrep_with_user_key({ service_token: "your service token", service_id: "your service id", user_key: "your key", usage: { "hits": 1 } }, function(response){
  console.log(response);
});


/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port.This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.authrep_with_user_key({ "service_id": "your service id", "user_key": "your key", "usage": { "hits": 1 } }, function(response){
  console.log(response);
});

*/

如果你使用OAuth作为认证模式，这将等同于上面的例子：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.oauth_authrep({ service_token: "your service token", service_id: "your service id", app_id: "your Client id", usage: { "hits": 1 } }, function(response){
  console.log(response);
});


/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port.This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.oauth_authrep({ service_id: "your service id", app_id: "your Client id" , usage: { "hits": 1 } }, function(response){
  console.log(response);
});

*/

Authorize and Report

你可以选择使用authorize和report< /strong> 方法在两个单独的调用中执行相同的操作。 请注意，report 方法支持在一次调用中发送多个事务的使用情况。

如果您使用 app_id 和 `app_key 对的身份验证模式：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.authorize({ service_token: "your service token", service_id: "your service id", app_id: "your application id", app_key: "your application key" }, function(response){
  if (response.is_success()) {
    var trans = [{ service_token: "your service token", app_id: "your application id", usage: { "hits": 3 } }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.authorize({service_id: "your service id", app_id: "your application id", app_key: "your application key" }, function(response){
  if (response.is_success()) {
    var trans = [{ app_id: "your application id", usage: { "hits": 3 } }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});
*/

这是 user_key 身份验证模式的相同示例：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.authorize_with_user_key({ service_token: "your service token", service_id: "your service id", user_key: "your key" }, function(response){
  if (response.is_success()) {
    var trans = [{ service_token: "your service token", user_key: "your key", usage: { "hits": 3 } }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.authorize_with_user_key({ service_id: "your service id", user_key: "your key" }, function(response){
  if (response.is_success()) {
    var trans = [{ user_key: "your key", usage: { "hits": 3 } }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});
*/

对于 OAuth 作为身份验证模式：

var Client = require('3scale').Client;

//Create a Client with a given host and port when connecting to an on-premise instance of the 3scale platform:
client = new Client({host: "service_management_api.example.com", port: 80});

/* or create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client();
*/

client.oauth_authorize({ service_token: "your service token", service_id: "your service id", app_id: "your Client Id" }, function(response){
  if (response.is_success()) {
    var trans = [{ service_token: "your service token", app_id: "your application id", usage: {"hits": 3} }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

/* If you don't use service_token in the method, you'll be expected to specify a provider_key parameter in the Client instance, which is deprecated in favor of using service_token in the method.

Create a Client with a given host and port:
client = new Client("your provider key",{host: "service_management_api.example.com", port: 80});

or 

Create a Client with default host and port. This will comunicate with the 3scale platform SaaS default server:
client = new Client("your provider key");

client.oauth_authorize({ "service_id": "your service id", "app_id": "your application id" }, function(response){
  if (response.is_success()) {
    var trans = [{ app_id: "your application id", usage: {"hits": 3} }];
    client.report("your service id", trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});
*/

请注意，report 方法支持在一次调用中发送多个事务的使用情况。

var trans = [
              { service_token: "your service token", app_id: "your application id", usage: {"hits": 1} },
              { service_token: "your service token", app_id: "your application id", usage: {"hits": 1000} }
             ]

client.report("your service id", trans, function(response){
  console.log(response);
});

To test

要运行测试：npm test 或 vows test/* --spec 来自项目的根目录。 请注意，您首先需要使用自己的 3scale 键设置以下环境变量：

• TEST3SCALEPROVIDER_KEY
• TEST3SCALEAPP_KEY
• TEST3SCALEAPP_ID