Node.js API 미터링 개발 가이드

PaaS-TA-Guide-Major
Search…
PaaS-TA-Guide-Major
PaaS-TA Guide
Java API 서비스 미터링 개발 가이드
Java 서비스 미터링 개발 가이드
Node.js API 미터링 개발 가이드
Node.js API 미터링 개발 가이드
1. 문서 개요
1.1 목적
본 문서(node.js API 서비스 미터링 애플리케이션 개발 가이드)는 파스-타 플랫폼 프로젝트의 미터링 플러그인과 Node.js API 애플리케이션을 연동시켜 API 서비스를 미터링하는 방법에 대해 기술 하였다.
1.2 범위
본 문서의 범위는 파스-타 플랫폼 프로젝트의 Node.js API 서비스 애플리케이션 개발과 CF-Abacus 연동에 대한 내용으로 한정되어 있다.
1.3 참고자료
​https://docs.cloudfoundry.org/devguide/
https://docs.cloudfoundry.org/buildpacks/node/node-tips.html
https://nodejs.org/
http://expressjs.com/ko/
https://github.com/cloudfoundry-incubator/cf-abacus​
2. Node.js API 미터링 개발가이드
2.1 개요
API 서비스 및 해당 API 서비스를 사용하는 애플리케이션을 Node.js 언어로 작성 한다. API 서비스를 사용하는 애플리케이션과 API 서비스를 바인딩하고 해당 애플리케이션에 바인딩된 환경정보(VCAP_SERVICES)를 이용해 각 서비스별 접속정보를 획득하여 애플리케이션에 적용하여 API 서비스를 호출하는 애플리케이션을 작성 한다. 또한 API 서비스는 서비스 요청을 처리함과 동시에 API 사용 내역을 CF-ABACUS에 전송하는 애플리케이션을 작성 한다.
기능
설명
​
Runtime
미터링/등급/과금 정책
API 서비스 제공자가 제공하는 서비스에 대한 각종 정책 정의 정보. JSON 형식으로 되었으며, 해당 정책을 CF-ABACUS에 등록하면 정책에 정의한 내용에 따라 API 사용량을 집계 한다.
 정책은 서비스 제공자가 정의해야 하며, JSON 스키마는 다음을 참조한다.
 https://github.com/cloudfoundry-incubator/cf-abacus/blob/master/doc/api.md​
서비스 브로커 API
Cloud Controller와 Service Broker 사이의 규약으로써 서비스 브로커 API 개발에 대해서는 다음을 참조한다.
 https://github.com/OpenPaaSRnD/Documents/blob/master/Development-Guide/ServicePack_develope_guide.md#11​
​
서비스 API
서비스 제공자가 제공하는 API 서비스 기능 및 API 사용량을 CF-ABACUS에 전송하는 기능으로 구성되었다.
​
대시보드
서비스를 제공하기 위한 인증, 서비스 모니터링 등을 위한 대시보드 기능으로 서비스 제공자가 개발해야 한다.
​
CF-ABACUS
CF-ABACUS 핵심 기능으로써 수집한 사용량 정보를 집계한다.
 CF-ABACUS은 CF 설치 후, CF에 마이크로 서비스 형태로 설치한다. 자세한 사항은 다음을 참조한다.
 https://github.com/cloudfoundry-incubator/cf-abacus​
​
※ 본 개발 가이드는 API**서비스** 개발에 대해서만 기술하며, 다른 컴포넌트의 개발 또는 설치에 대해서 링크한 사이트를 참조한다.
2.2 개발환경 구성
Node.js 애플리케이션 개발을 위해 다음과 같은 환경으로 개발환경을 구성 한다.
CF release: v226 이상
nodejs_buildpack: nodejs_buildpack-cached-v1.5.18.zip 이상
Node.js: v5.11.1
npm: v3.8.6
2.2.1 Node.js 및 npm 설치
1.  Node.js 및 npm 설치
1
$ sudo apt-get install curl
2
​
3
## Node.js version 6.x를 설치할 경우
4
## Source Repository 등록
5
$ curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash –
6
​
7
## Node.js & Npm 설치
8
$ sudo apt-get install -y nodejs
9
​
10
    ## Node.js & Nmp 설치 확인
11
    $ node -v
12
    $ npm -v
Copied!
※ Windows 용은 다음 사이트에서 Node.js를 다운 받는다.
https://nodejs.org/ko/download/​
※ 개발도구
Node.js는 javascript기반의 언어로 Notepad++, Sublim Text, EditPlus등 문서편집기를 개발도구로 사용할 수 있다. 또한 Eclipse의 플러그인 Nodeclipse를 설치하여 사용할 수 있다. 그리고 상용 개발 도구로써는 WebStome 등이 있다.
2.2.2 CF-Abacus 설치
별도 제공하는 Abacus 설치 가이드를 참고하여 CF-Abacus를 설치한다.
2.3 샘플 API 서비스 브로커 및 대시보드 개발
별도 제공하는 서비스 브로커 개발 가이드를 참고하여 서비스 브로커 및 대시보드를 개발한다. https://github.com/OpenPaaSRnD/Documents/blob/master/Development-Guide/ServicePack_develope_guide.md#6​
2.4 샘플 API 서비스 개발
샘플 api 서비스는 서비스 요청이 있는 경우, 해당 요청에 대한 응답 처리와 api 서비스 요청에 대한 미터링 정보를 CF-ABACUS에 전송하는 처리를 한다.
1.샘플 API 서비스 형상
1
sample_api_node_service/
2
├── .apprc
3
├── .gitignore
4
├── manifest.yml
5
├── .npmrc
6
├── package.json
7
├── sampleApiService
8
└── src
9
    ├── app.js
10
    └── test
11
        └── test.js
Copied!
파일/폴더
목적
.apprc
앱 실행 환경 설정 파일
.gitignore
Git을 통한 형상 관리 시, 형상 관리를 할 필요가 없는 파일 또는 디렉토리를 설정한다.
manifest.yml
애플리케이션을 파스-타 플랫폼에 배포 시 적용하는 애플리케이션에 대한 환경 설정 정보
 애플리케이션의 이름, 배포 경로, 인스턴스 수 등을 정의할 수 있다.
.npmrc
Npm 실행 환경 설정 파일
package.json
node.js 어플리케이션에 필요한 npm의 의존성 정보를 기술하는데 사용 한다.
 npm install 명령을 실행시 install 뒤에 아무런 정보를 입력하지 않으면 이 파일의 정보를 이용하여 npm을 설치한다.
sampleApiService
서비스 앱 실행 스크립트
app.js
서비스 앱
 서비스 요청에 대한 라우팅 정보와 미터링 정보 전송 처리를 정의한다.
test.js
서비스 앱 단위 테스트 모듈
 mocha를 통한 서비스 앱의 단위 테스트를 정의한다.
2.4.1 샘플 API 서비스 애플리케이션 코드 구현
1.  Package.json 샘플 애플리케이션의 코드 구성에 대해 기술한다.
1
{
2
  "name": "sample-api-node-service",                           ## 앱 명
3
  "version": "0.0.1",                                        ## 앱 버전
4
  "description": "CF API Usage Service Metering Sample",
5
  "main": "lib/app.js",                                      ## 개발 소스의 메인
6
  "bin": {
7
    "sampleApiService": "./sampleApiService"
8
  },
9
  "files": [                                                ## 형상 관리 대상의 파일 또는 디렉토리를 기술
10
    ".apprc",
11
    ".npmrc",
12
    "manifest.yml",
13
    "src/",
14
    "sampleApiService"
15
  ],
16
  "scripts": {                                               ## npm run 명령어 또는 npm 명령어로 실행
17
    "start": "./sampleApiService start",                       ## npm start: 앱 실행
18
    "stop": "./sampleApiService stop",                       ## npm stop: 앱 중지
19
    "babel": "babel",                                          ## npm run babel: 개발 소스를 컴파일
20
    "test": "eslint && mocha",                                ## npm test: 개발 소스를 테스트
21
    "lint": "eslint",                                        ## npm run lint: 개발 소스 체크
22
    "pub": "publish",                                         ## npm run publish: 개발 소스를 퍼블리시
23
    "cfpack": "cfpack",                                       ## npm run cfpack: 컴파일한 개발 소스를 패키지화
24
    "cfpush": "cfpush"                                      ## npm run cfpush: 패키지화 한 개발 소스를 cf에 push
25
  },
26
  "author": "PAASTA", 
27
  "license": "Apache-2.0",                                    ## 라이선스 선언
28
  "dependencies": {
29
    "body-parser": "^1.15.2",                                 ## json parser 모듈
30
    "cors": "^2.8.1",                                         ## cross domain request 허용 모듈
31
    "express": "^4.14.0",                                     ## node.js 웹 프레임워크
32
    "abacus-oauth": "^0.0.6-dev.8",                            ## Secured Abacus와 통신을 위한 Oauth 모듈
33
    "request": "^2.74.0",                                    ## request 모듈
34
    "babel-preset-es2015": "^6.6.0",                         ## ECMA5를 ECMA6으로 변환하기 위한 모듈
35
    "commander": "^2.8.1",                                     ## 명령어 실행 모듈
36
    "underscore": "^1.8.3"                                   ## javascript에 사용할 수 있는 함수가 정의된 모듈
37
  },
38
  "devDependencies": {                                      ## 개발 환경에서 의존하는 패키지
39
    "abacus-babel": "file:../../tools/babel",                ## 개발 소스를 ECMA5 -> ECMA6으로 변환
40
    "abacus-cfpack": "file:../../tools/cfpack",                ## 개발 소스를 cf에 push 할 수 있도록 패키지화 하는 패키지
41
    "abacus-cfpush": "file:../../tools/cfpush",              ## 개발 소스를 cf에 push하는 패키지
42
    "abacus-coverage": "file:../../tools/coverage",            ## 개발 소스에 대해 테스트 소스의 coverage율 체크 패키지
43
    "abacus-eslint": "file:../../tools/eslint",              ## 개발 소스 코드 체크 패키지
44
    "abacus-mocha": "file:../../tools/mocha",                ## mocha 테스트 실행 패키지
45
    "abacus-publish": "file:../../tools/publish"              ## 개발 소스 퍼블리시 패키지
46
  },
47
  "engines": {
48
    "node": ">=5.11.1",                                     ## nodejs 버전
49
    "npm": ">=3.8.6"                                           ## npm 버전
50
  }
51
}
Copied!
2.  Manifest.yml 앱을 CF에 배포할 때 필요한 설정 정보 및 앱 실행 환경에 필요한 설정 정보를 기술한다.
1
applications:
2
- name: sample-api-node-service                                   # 애플리케이션 이름
3
  host: sample-api-node-service                                   # 애플리케이션 호스트명
4
  memory: 512M                                                    # 애플리케이션 메모리 사이즈
5
  disk_quota: 512M                                                # 애플리케이션 디스크 사이즈
6
  instances: 1                                                    # 애플리케이션 인스턴스 개수
7
  command: npm start                                              # CF에서의 애플리케이션 시작 명령어
8
  path: ./.cfpack/app.zip                                         # 배포될 애플리케이션의 위치
9
  env:
10
    CONF: default                                                  # 명령어 실행 환경 설정 정보
11
    DEBUG: s*                                                     # 디버그 출력 대상 설정
12
    NODE_TLS_REJECT_UNAUTHORIZED: 0 # SSL flag off
13
    API: https://api.bosh-lite.com                                 # CF API 서비스 엔드포인트
14
    COLLECTOR: https://localhost/v1/metering/collected/usage      # api 사용량 전송 엔드포인드 
15
    SECURED: true                                                # Secured Abacus 설정: false or true
16
    AUTH_SERVER: https://api.bosh-lite.com:443                    # oauth 서비스 엔드포인트
17
    CLIENT_ID: abacus                                            # oauth 권한 id
18
    CLIENT_SECRET: secret                                         # oauth id 비밀번호
19
    JWTKEY: |+                                                     # 앱을 secured mode로 서비스 하기 위해 유효성 체크를 위한 인증 서비스 공개키 
20
      -----BEGIN PUBLIC KEY-----
21
      MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHFr+KICms+tuT1OXJwhCUmR2d
22
      KVy7psa8xzElSyzqx7oJyfJ1JZyOzToj9T5SfTIq396agbHJWVfYphNahvZ/7uMX
23
      qHxf+ZH9BL1gk9Y6kCnbM5R60gfwjyW1/dQPjOzn9N394zd2FJoFHwdq9Qs0wBug
24
      spULZVNRxq7veq/fzwIDAQAB
25
      -----END PUBLIC KEY-----
26
    JWTALGO: RS256
Copied!
ENV 항목
아래에 기술한 항목 이외에 서비스에 필요한 항목을 추가할 수 있다.
ENV 항목
설명
DEBUG
애플리케이션 디버그 로그 출력 대상 설정
NODE_TLS_REJECT_UNAUTHORIZED
-
API
CF API URL
https://api.
COLLECTOR
Abacus Collector 앱의 사용량 수집 서비스 URL
 https:// /v1/metering/collected/usage
SECURED
Secured abacus를 운용할 경우, 반드시 true를 설정한다.
AUTH_SERVER
SECURED가 true인 경우 설정한다.
 - CF UAA를 Auth_server로 설정할 경우, https://api.
 - Abacus의 AuthServer를 Auth_server로 설정할 경우, abacus-authserver-plugin
CLIENT_ID
SECURED가 true인 경우 설정한다.
Abacus.usage 권한 id
CLIENT_SECRET
SECURED가 true인 경우 설정한다.
Abacus.usage 권한 비밀번호
JWTKEY
SECURED가 true인 경우 설정한다.
 - CF UAA를 Auth_server로 설정할 경우, CF 배포 manifest의 properties.jwt.verification_key 값을 설정
 - Abacus의 AuthServer를 Auth_server로 설정할 경우, Key 값을 설정
JWTALGO
SECURED가 true인 경우 설정한다.
 - CF UAA를 Auth_server로 설정할 경우, RS256 - Abacus의 AuthServer를 Auth_server로 설정할 경우, HS256
3.  App.js 애플리케이션의 기능 및 미터링 정보 전송 기능을 구현한다. 샘플 애플리케이션은 다음과 같이 기능을 구현하였다.
의존 모듈 선언
1
'use strict';
2
​
3
 // Implemented in ES5 for now
4
/* eslint no-var: 0 */                   // ECMA5로 개발할 경우, eslint 체크에서 var 사용 제한을 풀어준다.
5
​
6
var express = require('express');        // 웹 프레임워크 모듈
7
var request = require('request');        // request 모듈
8
var bodyParser = require('body-parser'); // request 정보를 json으로 변환하는 모듈
9
var cp = require('child_process');
10
var commander = require('commander');    // command 사용 가능 모듈
11
var oauth = require('abacus-oauth');     // oauth 모듈
Copied!
변수 선언
1
// Create router
2
var routes = express.Router(); // 앱 서비스 엔드포인트를 설정 할 미들웨어
3
​
4
// Abacus Collector App's URL
5
var abacusCollectorUrl = process.env.COLLECTOR; // api 사용량 전송 url (abacus)
6
​
7
// Abacus System Token Scope
8
var scope = 'abacus.usage.write abacus.usage.read'; // abacus를 secured로 설정할 경우, api 사용량 정보의 전송을 위한
9
token scope 설정 (scope 설정에 대해서는 abacus 설치 가이드 참조)
10
​
11
// 크로스 도메인 허용을 위한 헤더 설정
12
var accessControlAllowHeader = 'Origin,X-Requested-With,Content-Type,Accept';
13
​
14
// 아래의 항목은 더미로 설정한 미터링 대상 정보이다.
15
// 실제 서비스를 구현할 경우, 해당 항목을 제공하는 API 호출이나 프로퍼티 값 등을 통해
16
// 설정한다.
17
var resourceId = 'object-storage';
18
var measure1 = 'storage';
19
var measure2 = 'light_api_calls';
20
var measure3 = 'heavy_api_calls';
21
var serviceKey = '[cloudfoundry]';
Copied!
Secure Abacus 보안 구현
1
// abacus 토큰 초기화
2
var abacusToken = void 0;
3
​
4
// Secure 설정
5
var secured = function secured() {
6
  return process.env.SECURED === 'true' ? true : false;
7
};
8
​
9
// abacus에 api usage를 전송할 때, request header 설정
10
var authHeader = function authHeader(token) {
11
  return token ? { authorization: token() } : {};
12
};
13
​
14
… 중략 …
15
​
16
var sampleApiService = function sampleApiService() {
17
​
18
  var app = express();
19
​
20
  // Secured abacue의 경우, 앱 서비스를 시작할 때, abacus 토큰을 구한다.
21
  if (secured()) {
22
    /*
23
     AUTH_SERVER:   인증 서버 엔드포인트 https://hostname:port or 
24
                    https://hostname
25
     CLIENT_ID:     인증 서버 권한 아이디
26
     CLIENT_SECRET: 인증 서버 권한 비밀번호
27
     SCOPE:         토큰 scope
28
     */
29
​
30
    abacusToken = oauth.cache(process.env.AUTH_SERVER, process.env.CLIENT_ID,
31
      process.env.CLIENT_SECRET, scope);
32
​
33
    // abacus Token을 주기적으로 갱신한다.
34
    abacusToken.start();
35
  };
36
​
37
 // api 서비스 또한 secured 모드로 실행 할 수 있다.
38
 // secured 모드로 실행할 경우, route에 등록한 모든 서비스에 대해 유효성 체크를 실행하도록 구현한다.
39
 // 본 샘플에서는 abacus의 oauth 서비스의 유효성 체크를 사용하였다.
40
 // if (secured())
41
 //   app.use(/^\/plan[0-9]/,
42
 //     oauth.validator(process.env.JWTKEY, process.env.JWTALGO));
43
​
44
app.use(routes);
45
​
46
  return app;
47
};
48
​
49
… 후략 …
Copied!
COR 설정
1
// api 서비스는 요청한 서비스의 응답 처리 이외에 abacus에 대해 request 처리가 추가로 필요하므로 크로스 도메인을 설정 한다.
2
routes.use(function(req, res, next) {
3
  res.header('Access-Control-Allow-Origin', '*');
4
  res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
5
  res.header('Access-Control-Allow-Headers', accessControlAllowHeader);
6
  next();
7
});
Copied!
서비스 API 구현
1
/*
2
 Sample API 'Plan1'
3
 1. Caller의 요청에 API 서비스를 처리 응답 (Sample에서는 생략)
4
 2. abacus에 api usage 전송
5
 */
6
routes.post('/plan1', function(req, res, next) {
7
​
8
  // api 요청 시각 설정
9
  var d = new Date();
10
  var eventTime = Date.parse(d);
11
​
12
  // 사용량 미터링에 필요한 메타 정보 설정
13
  var orgid = req.body.organization_id;
14
  var spaceid = req.body.space_id;
15
  var instanceid = reqs.body.instance_id ? reqs.body.instance_id : reqs.body.consumer_id;
16
  var appid = req.body.consumer_id;
17
  var planid = req.body.plan_id;
18
  var credential = req.body.credential;
19
​
20
  // 실제 서비스에 실행에 필요한 메타 정보는 inputs에 설정
21
  // var inputs = req.body.inputs;
22
​
23
  // 서비스 이용 권한 체크, 해당 체크 내용은 제공할 서비스에 맞게 변형한다.
24
  if (credential.serviceKey != serviceKey)
25
    return res.status(401).send();
26
​
27
  // 필수 항목 체크
28
  if (!orgid || !spaceid || !appid)
29
    return res.status(400).send();
30
​
31
  // abacus에 리포팅할 api 사용량 정보를 작성한다. (JSON 형식)
32
  var usage =
33
    buildAppUsage(orgid, spaceid, appid, instanceid, planid, eventTime);
34
​
35
  // api 사용량 정보 체크
36
  if (usage.usage === null) return res.status(400).send();
37
​
38
  // api 사용량 전송을 위한 요청 정보 설정
39
  var options = {
40
    uri: abacusCollectorUrl,
41
    headers: authHeader(abacusToken),
42
    json: usage.usage
43
  };
44
​
45
  // api usage를 abacus에 전송
46
  request.post(options, function(error, response, body) {
47
​
48
    // abacus 전송 처리 판정
49
    if (error) console.log(error);
50
    else if (response.statusCode === 201 || response.statusCode === 200) {
51
      // console.log('Successfully reported usage %j with headers %j',
52
      //   usage, response.headers);
53
      res.status(201).send(response.body);
54
      return;
55
    }
56
    // abacus에 api 사용량을 중복 송신한 경우 발생
57
    else if (response.statusCode === 409) {
58
      // console.log('Conflicting usage %j. Response: %j',
59
      //   usage, response);
60
      res.sendStatus(409);
61
      return;
62
    }
63
    // 기타 400 / 500 계열의 오류 체크
64
    else {
65
      // console.log('failed report usage %j with headers %j',
66
      //   usage, response.headers);
67
      res.sendStatus(response.statusCode);
68
      return;
69
    }
70
  });
71
  return res;
72
});
Copied!
Abacus 전송 Json 생성
1
// abacus로 전송할 데이터 포맷을 만든다.
2
var buildAppUsage =
3
  function buildAppUsage(orgid, spaceid, appid, insid, planid, eventTime) {
4
​
5
    var appUsage = { usage: null };
6
​
7
    // sample api plan id가 'standard'
8
    if (planid == 'standard')
9
      appUsage = {
10
        usage: {
11
          start: eventTime,
12
          end: eventTime,
13
          organization_id: orgid,
14
          space_id: spaceid,
15
          consumer_id: 'app:' + appid,
16
          resource_id: resourceId,
17
          plan_id: planid,
18
          resource_instance_id: insid,
19
          measured_usage: [
20
            {
21
              measure: measure1,
22
              quantity: 1073741824
23
            },
24
            {
25
              measure: measure2,
26
              quantity: 1000
27
            },
28
            {
29
              measure: measure3,
30
              quantity: 0
31
            }
32
          ]
33
        }
34
      };
35
​
36
    return appUsage;
37
  };
Copied!
기타
1
// 앱 서비스를 위한 설정 정보
2
// PORT, HOST명 등을 설정한다.
3
var conf = function conf() {
4
  process.env.PORT = commander.port || process.env.PORT || 9602;
5
};
6
​
7
// Command line 인터페이스 설정
8
// package에 기술한 start, stop 스크립트를 실행할 수 있다.
9
// 앱 시작: npm start
10
// 앱 중지: npm stop
11
​
12
var runCLI = function runCLI() {
13
​
14
  commander
15
    .option('-p, --port <port>', 'port number [9602]')
16
    .option('start', 'start the server')
17
    .option('stop', 'stop the server')
18
    .parse(process.argv);
19
​
20
  // Start API server
21
  if (commander.start) {
22
    conf();
23
​
24
    // Create app and listen on the configured port
25
    var app = sampleApiService();
26
​
27
    app.listen({
28
      port: parseInt(process.env.PORT)
29
    });
30
  }
31
  else if (commander.stop)
32
​
33
    // Stop API App server
34
    cp.exec(
35
      'pkill -f "node ./sampleApiService"', function(err, stdout, stderr) {
36
        if (err) console.log('Stop error %o', err);
37
      });
38
};
39
​
40
// Export our public functions
41
module.exports = sampleApiService;
42
module.exports.runCLI = runCLI
Copied!
2.4.2 샘플 API 서비스 애플리케이션 미터링 연동 항목
1.  미터링 정보 전송 API 엔드포인
1
POST /v1/metering/collected/usage
Copied!
2.  API 서비스 미터링 전송 항목
항목명
유형
설명
예시
start
UNIX Timestamp
API처리 시작 시각
1396421450000
end
UNIX Timestamp
API처리 응답 시각
1396421451000
organization_id
String
API를 호출한 앱의 조직 ID
us-south:54257f98-83f0-4eca-ae04-9ea35277a538
space_id
String
API를 호출한 앱의 영역 ID
d98b5916-3c77-44b9-ac12-04456df23eae
consumer_id
String
API를 호출한 앱 ID
App: d98b5916-3c77-44b9-ac12-04d61c7a4eae
resource_id
String
API 자원 ID
sample_api
plan_id
String
API 미터링 Plan ID
basic
resource_instance_id
String
API를 호출한 앱 ID
d98b5916-3c77-44b9-ac12-04d61c7a4eae
measured_usage
Array
미터링 항목
-
measure
String
미터링 대상 명
api_calls
quantity
Number
해당 API 요청에 대한 API 처리 횟수
10
3.  API 서비스 미터링 전송 항목 예제
1
{
2
  "start": 1396421450000,
3
  "end": 1396421451000,
4
  "organization_id": "us-south:54257f98-83f0-4eca-ae04-9ea35277a538",
5
  "space_id": "d98b5916-3c77-44b9-ac12-04456df23eae",
6
  "consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
7
  "resource_id": "sample_api",
8
  "plan_id": "basic",
9
  "resource_instance_id": "d98b5916-3c77-44b9-ac12-04d61c7a4eae",
10
  "measured_usage": [
11
    {
12
      "measure": "api_calls",
13
      "quantity": 10
14
    }
15
  ]
16
}
Copied!
참고: https://github.com/cloudfoundry-incubator/cf-abacus/blob/master/doc/api.md​
2.5 API 서비스 연동 샘플 애플리케이션 개발
Api 서비스를 이용하는 애플리케이션으로 본 샘플은 웹 화면을 통행 단순히 api 서비스를 요청하는 기능만을 구현 하였다.
1.  API 서비스 연동 샘플 애플리케이션 형상
1
sample_api_node_caller/
2
├── .apprc
3
├── cfpush.sh
4
├── .eslintignore
5
├── .gitignore
6
├── manifest.yml
7
├── .npmrc
8
├── package.json
9
├── sampleApiCaller
10
├── src
11
│   ├── app.js
12
│   ├── bower_components
13
│   └── test
14
│       └── test.js
15
└── views
16
    ├── apiCaller.handlebars
17
    └── layouts
18
       └── main.handlebars
Copied!
파일/폴더
목적
.apprc
앱 실행 환경 설정 파일
cfpush.sh
Manifest의 org_id를 현재 target 설정된 org의 guid로 수정하고 패키지한 앱을 cf에 push 한다.
.eslintignore
Eslint 실행 시, 체크 제외 대상의 파일 및 디렉토리를 설정한다.
.gitignore
Git을 통한 형상 관리 시, 형상 관리를 할 필요가 없는 파일 또는 디렉토리를 설정한다.
manifest.yml
파스-타 플랫폼에 배포시 애플리케이션에 대한 설정이다. 애플리케이션의 이름, 배포 경로, 인스턴스 수 등을 정의할 수 있다.
.npmrc
Npm 실행 환경 설정 파일
package.json
node.js 어플리케이션에 필요한 npm의 의존성 정보를 기술하는데 사용 한다.
 npm install 명령을 실행시 install 뒤에 아무런 정보를 입력하지 않으면 이 파일의 정보를 이용하여 npm을 설치한다.
sampleApiCaller
서비스 호출 앱 실행 스크립트
app.js
서비스 호출 앱
웹 서비스 및 bind 한 api 서비스 호출에 대한 라우팅 정보를 정의한다.
bower_components
프론트엔드 라이브러리 디렉토리
test.js
서비스 앱 단위 테스트 모듈
mocha를 통한 서비스 앱의 단위 테스트를 정의한다.
views
샘플 API 서비스 호출 데모 화면
2.5.1 API 서비스 연동 샘플 애플리케이션 코드
1.  Package.json
샘플 애플리케이션의 코드 구성에 대해 기술한다.
1
{
2
  "name": "sample-api-node-caller",
3
  "version": "0.0.1",
4
  "description": "CF API Metering Caller Sample",
5
  "main": "lib/app.js",
6
  "bin": {
7
    "sampleApiCaller": "./sampleApiCaller"
8
  },
9
  "files": [
10
    ".apprc",
11
    ".eslintignore",
12
    ".npmrc",
13
    "cfpush.sh",
14
    "manifest.yml",
15
    "src/",
16
    "views/"
17
  ],
18
  "scripts": {
19
    "start": "./sampleApiCaller start",
20
    "stop": "./sampleApiCaller stop",
21
    "babel": "babel",
22
    "test": "eslint && mocha",
23
    "lint": "eslint",
24
    "pub": "publish",
25
    "cfpack": "cfpack",
26
    "cfpush": "./cfpush.sh"
27
  },
28
  "author": "PAASTA",
29
  "license": "Apache-2.0",
30
  "dependencies": {
31
    "body-parser": "^1.15.2",
32
    "cors": "^2.8.1",
33
    "express": "^4.14.0",
34
    "express-handlebars": "^3.0.0",       ## 핸들러 모듈
35
    "babel-preset-es2015": "^6.6.0",
36
    "request": "^2.74.0",
37
    "commander": "^2.8.1",
38
    "underscore": "^1.8.3"
39
  },
40
  "devDependencies": {
41
    "abacus-babel": "file:../../tools/babel",
42
    "abacus-cfpack": "file:../../tools/cfpack",
43
    "abacus-cfpush": "file:../../tools/cfpush",
44
    "abacus-coverage": "file:../../tools/coverage",
45
    "abacus-eslint": "file:../../tools/eslint",
46
    "abacus-mocha": "file:../../tools/mocha",
47
    "abacus-publish": "file:../../tools/publish"
48
  },
49
  "engines": {
50
    "node": ">=5.11.1",
51
    "npm": ">=3.8.6"
52
  }
53
}
Copied!
2.  Manifest.yml
앱을 CF에 배포할 때 필요한 설정 정보 및 앱 실행 환경에 필요한 설정 정보를 기술한다.
1
---
2
applications:
3
- name: sample-api-node-caller  # 애플리케이션 이름
4
  memory: 512M                  # 애플리케이션 메모리 사이즈
5
  disk_quota: 512M
6
  instances: 1                  # 애플리케이션 인스턴스 개수
7
  path: ./.cfpack/app.zip       # 배포될 애플리케이션의 위치
8
  command: npm start            # CF에서의 애플리케이션 시작 명령어
9
  env:
10
    DEBUG: a*
11
    ORG_ID: d6ce3670-ab9c-4453-b993-f2821f54846b
12
    SECURED: false
13
    #AUTH_SERVER: https://api.bosh-lite.com:443 
14
    #CLIENT_ID: abacus
15
    #CLIENT_SECRET: secret
Copied!
ENV 항목
아래에 기술한 항목 이외에 서비스에 필요한 항목을 추가할 수 있다.
ENV 항목
설명
DEBUG
애플리케이션 디버그 로그 출력 대상 설정
​
​
ORG_ID
Caller 애플리케이션을 배포할 조직 ID
​
​
SECURED
API 서비스를 Secured로 운용할 경우, 반드시 true를 설정한다.
​
​
AUTH_SERVER
SECURED가 true인 경우 설정한다. - CF UAA를 Auth_server로 설정할 경우, https://api. - Abacus의 AuthServer를 Auth_server로 설정할 경우, abacus-authserver-plugin
​
​
CLIENT_ID
SECURED가 true인 경우 설정한다.
Abacus.usage 권한 id
​
​
CLIENT_SECRET
SECURED가 true인 경우 설정한다.Abacus.usage 권한 비밀번호

​
​
3.  App.js
Api 서비스를 요청하는 애플리케이션을 구현한다.
의존 모듈 선언
1
'use strict';
2
​
3
// Implemented in ES5 for now
4
/* eslint no-var: 0 */
5
​
6
var express = require('express');
7
var request = require('request');
8
var bodyParser = require('body-parser');
9
var cp = require('child_process');
10
var commander = require('commander');
11
var handlebars = require('express-handlebars').create({ defaultLayout:'main' }); // 웹 서비스 뷰 처리 모듈
Copied!
변수 선언
1
// 크로스 도메인 요청 헤더
2
var accessControlAllowHeader = 'Origin,X-Requested-With,Content-Type,Accept';
3
​
4
var vcapApp = undefined;
5
var vcapService = undefined;
6
var dummyOrgId = undefined;
7
var vcapBindServices = undefined;
8
​
9
// vcap_application 정보 설정
10
vcapApp = JSON.parse(process.env.VCAP_APPLICATION);
11
​
12
// vcap_service 정보 설정
13
vcapService = JSON.parse(process.env.VCAP_SERVICES);
14
​
15
// 조직 guid 설정
16
dummyOrgId = process.env.ORG_ID;
Copied!
Secure Abacus 보안 구현
1
// api 서비스를 참고 하여 api service 요청 시, header에 token을 설정하는 처리를 구현한다.
Copied!
COR 설정
1
// api 서비스는 요청한 서비스의 응답 처리 이외에 abacus에 대해 request 처리가 추가로 필요하므로 크로스 도메인을 설정 한다.
2
routes.use(function(req, res, next) {
3
  res.header('Access-Control-Allow-Origin', '*');
4
  res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
5
  res.header('Access-Control-Allow-Headers', accessControlAllowHeader);
6
  next();
7
});
Copied!
서비스 API 구현
1
// VCAP_SERVICE에서 앱과 바인드한 서비스 정보를 가져온다.
2
// 복수의 서비스가 앱에 바인드 될 수 있다.
3
vcapBindServices = vcapService[Object.keys(vcapService)[0]];
4
​
5
var sampleApiCaller = function sampleApiCaller() {
6
​
7
  var app = express();
8
​
9
  // 웹 서비스 뷰 처리
10
  app.engine('handlebars', handlebars.engine);
11
  app.set('view engine', 'handlebars');
12
​
13
  // 크로스 도메인 처리
14
  app.use(function(req, res, next) {
15
    res.header('Access-Control-Allow-Origin', '*');
16
    res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
17
    res.header('Access-Control-Allow-Headers', accessControlAllowHeader);
18
    next();
19
  });
20
​
21
  // 뷰에서 참조하는 js 모듈을 미들웨어에 마운트 한다.
22
  app.use('/bower_components',
23
    express.static(__dirname + '/bower_components'));
24
​
25
  // 웹 서비스 메인을 미들웨어에 마운트 한다.
26
  app.get('/', function(req, res) {
27
    res.type('text/html');
28
    res.render('apiCaller');         // 뷰 생성
29
  });
30
​
31
  // to support JSON-encoded bodies
32
  app.use(bodyParser.json());
33
​
34
  // to support URL-encoded bodies
35
  app.use(bodyParser.urlencoded({
36
    extended: true
37
  }));
38
​
39
  /*
40
   Sample Web Service
41
   1. API 서비스를 요청
42
   */
43
  app.post('/sampleApiSerivceCall', function(req, res, next) {
44
​
45
    // 앱에 Bind한 서비스가 없는 경우
46
    if (typeof vcapBindServices !== 'object') {
47
      return res.status(502).send('unbind service called');
48
      next();
49
    };
50
​
51
    // API Service와 연동 할 서비스를 구한다.
52
    // 바인드된 복수의 서비스 중에서 연동 할 서비스 정보를 구한다.
53
    var bindApiService = vcapBindServices[0];
54
​
55
    // 위에서 구한 서비스 정보에서 서비스 url를 구한다.
56
    var serviceUrl = bindApiService.credentials.uri ?
57
      bindApiService.credentials.uri : bindApiService.credentials.url;
58
​
59
    // API Service에 요청 할 JSON 을 작성한다.
60
    var callEvent = buildSendData(req.body, bindApiService);
61
​
62
    // Set request options
63
    var options = {
64
      uri: serviceUrl,
65
      json: callEvent
66
    };
67
​
68
    // api Service에 요청하고 결과를 응답한다.
69
    request.post(options, function(error, response, body) {
70
​
71
      if (error) console.log(error);
72
      else if (response.statusCode === 201 || response.statusCode === 200) {
73
        // console.log('Successfully reported usage %j with headers %j',
74
        //   usage, response.headers);
75
        res.status(201).send(response.body);
76
        return;
77
      }
78
      else {
79
        // console.log('failed report usage %j with headers %j',
80
        //   usage, response.headers);
81
        res.sendStatus(response.statusCode);
82
        return;
83
      }
84
    });
85
    return res;
86
  });
87
​
88
  // Not found
89
  app.use(function(req, res) {
90
    res.type('text/plain');
91
    res.status(404);
92
    res.send('404 not found');
93
  });
94
​
95
  return app;
96
};
Copied!
Abacus 전송 Json 생성
1
// 서비스로 보낼 데이터를 JSON 형식으로 작성한다.
2
var buildSendData = function buildSendData(args, bindApiService) {
3
​
4
  return {
5
    organization_id: dummyOrgId,
6
    space_id: vcapApp.space_id,
7
    consumer_id: vcapApp.application_id,
8
    instance_id: vcapApp.instance_id ?
9
      vcapApp.instance_id : vcapApp.application_id,
10
    plan_id: bindApiService.plan,
11
    credential: bindApiService.credentials,
12
    inputs: args
13
  };
14
};
Copied!
기타
1
// 앱 서비스를 위한 설정 정보
2
// PORT, HOST명 등을 설정한다.
3
var conf = function conf() {
4
  process.env.PORT = commander.port || process.env.PORT || 9601;
5
};
6
​
7
// Command line interface
8
var runCLI = function runCLI() {
9
​
10
  commander
11
    .option('-p, --port <port>', 'port number [9601]')
12
    .option('start', 'start the server')
13
    .option('stop', 'stop the server')
14
    .parse(process.argv);
15
​
16
  // Start Caller server
17
  if (commander.start) {
18
    conf();
19
​
20
    // Create app and listen on the configured port
21
    var app = sampleApiCaller();
22
​
23
    app.listen({
24
      port: parseInt(process.env.PORT)
25
    });
26
  }
27
  else if (commander.stop)
28
​
29
  // Stop Caller App server
30
    cp.exec(
31
      'pkill -f "node ./sampleApiCaller"', function(err, stdout, stderr) {
32
        if (err) console.log('Stop error %o', err);
33
      });
34
};
35
​
36
// Export our public functions
37
module.exports = sampleApiCaller;
38
module.exports.runCLI = runCLI;
Copied!
4.  Views/apiCaller.handlebars
Api 서비스를 요청하는 웹 화면
1
<!DOCTYPE html>
2
<html>
3
<head>
4
<meta charset="utf-8">
5
<script src="bower_components/jquery/dist/jquery.min.js"></script>
6
<script type="text/javascript">
7
​
8
    $(document).ready(function() {
9
​
10
        $('#result_div').html('');
11
​
12
        var appUrl = document.URL;
13
        // 요청 서비스 입력 항목 설정
14
        var input_param1 = '서울';
15
        var input_param2 = '무교동';
16
​
17
        $('#send_btn').click(function(){
18
​
19
            $('#result_div').html('');
20
​
21
            var data = sendData( input_param1, input_param2 );
22
​
23
            $.ajax({
24
                url: appUrl + 'sampleApiSerivceCall',
25
                type:"POST",
26
                data:data,
27
                success:function(data)
28
                {
29
                    $('#result_div').html("posted.");
30
                },
31
                error:function(jqXHR,textStatus,errorThrown)
32
                {
33
                    $('#result_div').html(errorThrown);
34
                }
35
            });
36
​
37
        });
38
    });
39
​
40
    // 요청 서비스 입력 항목 설정, JSON 형식으로 작성한다.
41
    var sendData = function buildJSON( input_param1, input_param2 ) {
42
​
43
        return {
44
            input_param1: input_param1,
45
            input_param2: input_param2
46
        };
47
    };
48
​
49
</script>
50
</head>
51
<body>
52
<form id="form">
53
​
54
</form>
55
​
56
<h3>CF REMOTE SERVICE API CALL TEST</h3>
57
​
58
<button id="send_btn">SEND SERVICE API CALL</button>
59
<br>
60
​
61
​
62
<!--<h4>{{vcapService}}</h4>-->
63
​
64
</body>
65
</html>
Copied!
2.5.2 API 서비스 연동 샘플 애플리케이션 인터페이스 항목
1.  API 서비스 엔드포인트
1
GET|POST|PUT|DELETE <api_service_restful_api>
Copied!
2.  API 서비스 미터링 전송 항목
항목명
유형
설명
예시
org_id
String
API 서비스를 요청한 앱의 조직 ID
54257f98-83f0-4eca-ae04-9ea35277a538
space_id
String
API 서비스를 요청한 앱의 영역 ID
d98b5916-3c77-44b9-ac12-04456df23eae
consumer_id
String
API 서비스를 요청한 앱 ID
d98b5916-3c77-44b9-ac12-045678edabae
instance_id
String
API 서비스를 요청한 앱의 자원 인스턴스 ID
d98b5916-3c77-44b9-ac12-045678edabad
plan_id
String
앱의 요청한 API 서비스의 plan ID
basic
credentials
JSON
서비스 요청에 필요한 credential 항목을 설정한다.
credentials: {
      key: value,
      …
 }
inputs
JSON
서비스 요청에 필요한 입력 정보를 설정한다.
 inputs: {
      key: value,s
      ...
 }
3.  API 서비스 미터링 전송 항목 예제
1
{
2
  organization_id: 'd6ce3670-ab9c-4453-b993-f2821f54846b',
3
  space_id: 'ab63eaed-7932-4f24-804d-dccb40a68752',
4
  consumer_id: 'ff7476f9-f5b6-420c-96f0-ac39be43de8c',
5
  instance_id: 'ff7476f9-f5b6-420c-96f0-ac39be43de8c',
6
  plan_id: 'standard',
7
  credential: {
8
    'serviceKey': '[cloudfoundry]',
9
    'url': 'http://localhost:9602/plan1'
10
  },
11
  inputs: {
12
    key1: 'val1',
13
    key2: 'val2'
14
  }
15
}
Copied!
2.5.3 VCAP_SERVICES 환경설정 정보
파스-타 플랫폼에 배포되는 애플리케이션이 바인딩된 서비스별 접속 정보를 얻기 위해서는 애플리케이션별로 등록되어있는 VCAP_SERVICES 환경설정 정보를 읽어들여 정보를 획득 할 수 있다.
1.  파스-타 플랫폼의 애플리케이션 환경정보
서비스를 바인딩하면 JSON 형태로 환경설정 정보가 애플리케이션 별로 등록된다.
1
{
2
 "VCAP_SERVICES": {
3
  "sample_api_node_service": [
4
   {
5
    "credentials": {
6
     "documentUrl": "http://sample-api-node-service.bosh-lite.com/doc",
7
     "serviceKey": "UxJWlzVP0VJquACPD+FohQ==",
8
     "url": "http://sample-api-node-service.bosh-lite.com/"
9
    },
10
    "label": "sample_api_node_service",
11
    "name": "sampleNodeApi",
12
    "plan": "basic",
13
    "provider": null,
14
    "syslog_drain_url": "PASTA_SERVICE_METERING",
15
    "tags": [
16
     "Sample API Service"
17
    ],
18
    "volume_mounts": []
19
   }
20
  ]
21
 }
22
}
23
​
24
{
25
 "VCAP_APPLICATION": {
26
  "application_id": "58872d8a-edfc-44df-97f0-df67cf9033a7",
27
  "application_name": "sample-api-node-caller",
28
  "application_uris": [
29
   "sample-api-node-caller.bosh-lite.com"
30
  ],
31
  "application_version": "55678102-584c-4fca-8304-82f727506b1d",
32
  "limits": {
33
   "disk": 512,
34
   "fds": 16384,
35
   "mem": 512
36
  },
37
  "name": "sample-api-node-caller",
38
  "space_id": "2ce08996-f463-406c-a971-adbbaf4e4ca5",
39
  "space_name": "ops",
40
  "uris": [
41
   "sample-api-node-caller.bosh-lite.com"
42
  ],
43
  "users": null,
44
  "version": "55678102-584c-4fca-8304-82f727506b1d"
45
 }
46
}
Copied!
2.  Node.js에서 파스-타 플랫폼의 애플리케이션 환경정보에 접근하는 방법
시스템 환경변수의 VCAP_SERVICES값을 읽어서 접근 할 수 있다.
1
 process.env.VCAP_SERVICES
Copied!
2.6 미터링/등급/과금 정책
서비스, 그리고 서비스 제공자 마다 미터링/등급/과금 정책 다르기 때문에 본 가이드에서는 정책의 개발 예제를 다루지는 않는다. 다만 CF-ABACUS에 적용할 수 있는 형식에 대해 설명한다.
2.6.1 미터링 정책
미터링 정책이란 수집한 미터링 정보에서 미터링 대상의 지정 및 집계 방식을 정의한 JSON 형식의 오브젝트이다. 서비스 제공자는 미터링 정책 스키마에 맞춰 서비스에 대한 정책을 개발한다.
1.  미터링 정책 스키마
항목명
유형
필수
설명
plan_id
String
O
API 미터링 Plan ID
measures
Array
최소 하나
API 미터링 정보 수집 대상 정의
name
String
O
미터링 정보 수집 대상 명
unit
String
O
미터링 정보 수집 대상 단위
metrics
Array
최소 하나
API 미터링 집계 방식 정의
name
String
O
미터링 정보 수집 대상 명
unit
String
O
미터링 정보 수집 대상 단위
meter
String
X
미터링 정보에 대해서 수집 단계에 적용하는 계산식 또는 변환식
accumulate
String
X
미터링 정보에 대해서 누적 단계에 적용하는 계산식 또는 변환식
aggregate
String
X
미터링 정보에 대해서 집계 단계에 적용하는 계산식 또는 변환식
summarize
String
X
미터링 정보를 보고할 때 적용하는 계산식 또는 변환식
title
String
X
API 미터링 제목
2.  미터링 정책 예제
1
{
2
  "plan_id": "basic-object-storage",
3
  "measures": [
4
    {
5
      "name": "storage",
6
      "unit": "BYTE"
7
    },
8
    {
9
      "name": "api_calls",
10
      "units": "CALL"
11
    }
12
  ],
13
  "metrics": [
14
    {
15
      "name": "storage",
16
      "unit": "GIGABYTE",
17
      "meter": "(m) => m.storage / 1073741824",
18
      "accumulate": "(a, qty) => Math.max(a, qty)"
19
    },
20
    {
21
      "name": "thousand_api_calls",
22
      "unit": "THOUSAND_CALLS",
23
      "meter": "(m) => m.light_api_calls / 1000",
24
      "accumulate": "(a, qty) => a ? a + qty : qty",
25
      "aggregate": "(a, qty) => a ? a + qty : qty",
26
      "summarize": "(t, qty) => qty"
27
    }
28
  ]
29
}
Copied!
2.6.2 등급 정책
등급 정책이란 각 서비스의 사용 가중치를 정의한 JSON 형식의 오브젝트이다. 서비스 제공자는 등급 정책 스키마에 맞춰 서비스에 대한 정책을 개발한다.
1.  등급 정책 스키마
항목명
유형
필수
설명
plan_id
String
O
API 등급 Plan ID
metrics
Array
최소 하나
등급 정책 목록
name
String
O
등급 정의 대상 명
rate
String
X
가중치 계산식 또는 변환식
charge
String
X
사용량에 대한 과금 계산식 또는 변환식
title
String
X
등급 정책 명
2.  등급 정책 예제
1
{
2
  "plan_id": "object-rating-plan",
3
  "metrics": [
4
    {
5
      "name": "storage"
6
    },
7
    {
8
      "name": "thousand_api_calls",
9
      "rate": "(p, qty) => p ? p * qty : 0",
10
      "charge": "(t, cost) => cost"
11
    }
12
  ]
13
}
Copied!
2.6.3 과금 정책
과금 정책이란 각 서비스에 대한 사용 단가를 정의한 JSON 형식의 오브젝트이다. 서비스 제공자는 과금 정책 스키마에 맞춰 서비스에 대한 정책을 개발한다.
1.  과금 정책 스키마
항목명
유형
필수
설명
plan_id
String
O
API 과금 Plan ID
metrics
Array
최소 하나
과금 정책 목록
name
String
O
과금 대상 명
price
Array
최소 하나
과금 정책 상세
country
String
O
서비스 사용 단가에 적용할 통화
price
Number
O
서비스 사용 단가
title
String
X
과금 정책 제목
2.  과금 정책 예제
1
{
2
  "plan_id": "object-pricing-basic",
3
  "metrics": [
4
    {
5
      "name": "storage",
6
      "prices": [
7
        {
8
          "country": "USA",
9
          "price": 1
10
        },
11
        {
12
          "country": "EUR",
13
          "price": 0.7523
14
        },
15
        {
16
          "country": "CAN",
17
          "price": 1.06
18
        }
19
      ]
20
    },
21
    {
22
      "name": "thousand_api_calls",
23
      "prices": [
24
        {
25
          "country": "USA",
26
          "price": 0.03
27
        },
28
        {
29
          "country": "EUR",
30
          "price": 0.0226
31
        },
32
        {
33
          "country": "CAN",
34
          "price": 0.0317
35
        }
36
      ]
37
    }
38
  ]
39
}
Copied!