(Click to open topic with navigation)

Moab Web Services > Resources > Accounting > Accounting Usage Records

Accounting Usage Records

This section describes the services available through Moab Web Services for interacting with the Usage Record object in Moab Accounting Manager. It contains the URLs, request bodies, and responses delivered to and from MWS as an intermediary for MAM.

The Fields: Usage Records reference section contains the type and description of all fields in the Usage Record object.

Supported methods

Resource GET PUT POST DELETE
/rest/accounting/usage-records Get All Usage Records -- -- --
/rest/accounting/usage-records/<id> Get Single Usage Record -- -- --
/rest/accounting/usage-records/quote -- -- Obtain a Quote For Resource Usage --

This topic contains these sections:

Getting Usage Records

The HTTP GET method is used to retrieve Usage Record information.

Quick reference

GET http://localhost:8080/mws/rest/accounting/usage-records?api-version=3
GET http://localhost:8080/mws/rest/accounting/usage-records/<id>?api-version=3
POST http://localhost:8080/mws/rest/accounting/usage-records/quote?api-version=3

Get All Usage Records

URLs and parameters

GET http://localhost:8080/mws/rest/accounting/usage-records?api-version=3&proxy-user=<user>[&query=<query_conditions>][&fields=<fields_to_display>[&sort=<fields_to_sort>]|&show-all=(true|false)]
Parameter Required Type Valid values Description Example
proxy-user Yes String -- Perform action as defined MAM user. proxy-user=amy
query No JSON --

Results are restricted to those having the specified field values.

The query parameter does not support the full Mongo query syntax. Only querying for a simple, non-nested JSON object is allowed.

 query={"account":"query"}
fields No String -- Comma-separated list of field names to display. fields=id,instance,charge,user,account
sort No JSON -- Sort the results. Use 1 for ascending and -1 for descending. Should be used in conjunction with the fields parameter. sort={"user":1}
show-all No Boolean true or false true shows all fields including metadata and hidden fields. Default is false. show-all=true

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/accounting/usage-records?api-version=3&proxy-user=amy&fields=id,instance,charge,user,account&pretty=true
------------------------------------

{
  "totalCount": 2,
  "resultCount": 2,
  "results":   [
        {
      "id": 1,
      "instance": "job.1",
      "charge": 31,
      "user": "amy",
      "account": "chemistry"
    },
        {
      "id": 2,
      "instance": "job.2",
      "charge": 30,
      "user": "amy",
      "account": "biology"
    }
}

Get Single Usage Record

URLs and parameters

GET http://localhost:8080/mws/rest/accounting/usage-records/<id>?api-version=3&proxy-user=<user>[&fields=<fields_to_display>|&show-all=(true|false)]
Parameter Required Type Valid values Description Example
id Yes String -- The unique identifier of the object. code
proxy-user Yes String -- Perform action as defined MAM user. proxy-user=amy
fields No String -- Comma-separated list of field names to display. fields=id,instance,charge,user,account
show-all No Boolean true or false true shows all fields including metadata and hidden fields. Default is false. show-all=true

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/accounting/usage-records/1?api-version=3&proxy-user=amy&pretty=true
------------------------------------

{
  "id": 1,
  "type": "Job",
  "instance": "job.1",
  "charge": 31,
  "stage": "Charge",
  "user": "amy",
  "group": "faculty",
  "account": "chemistry",
  "organization": "sciences",
  "qualityOfService": "",
  "machine": "colony",
  "nodes": "",
  "processors": 16,
  "memory": "",
  "disk": "",
  "network": "",
  "duration": 720,
  "startTime": "",
  "endTime": "",
  "description": ""
}

Obtain a Quote For Resource Usage

URLs and parameters

POST http://localhost:8080/mws/rest/accounting/usage-records/quote?api-version=3&object-type=<object>&proxy-user=<user>&charge-duration=<seconds>
Parameter Required Type Valid values Description Example
proxy-user Yes String -- Perform action as defined MAM user. proxy-user=amy
charge-duration Yes Integer -- The quote duration of the job in seconds. charge-duration=6400
object-type Yes String -- The object to quote. It can be job or service. object-type=job
itemize No Boolean true or false Returns the composite charge information in the response data. itemize=true
rate No JSONArray -- Uses the specified charge rates in the quote. The specified rates override the standard and quote rates. If the guarantee field is set to true, these charge rates will be saved and used when this quote is referenced in a charge action. rate=[{"type":"VBR","name":"Memory","rate":1},{"type":"VBR","name":"Processors","rate":1}]
guarantee No Boolean true or false Guarantees the quote and returns a quote id to secure the current charge rates. This results in the creation of a quote record and a permanent usage record. This parameter is mutually exclusive with the cost-only parameter. guarantee=true
grace-duration No Integer -- The guaranteed quote grace period in seconds. If the quote duration is specified but not the quote end time, the quote endtime will be calculated as the quote start time plus the quote duration plus the grace duration. grace-duration=6400
cost-only No Integer -- Returns the cost, ignoring all balance and validity checks. This parameter is mutually exclusive with the guarantee parameter. cost-only=true
description No String -- The guaranteed quote description. description="ABC Coupon Rate"
start-time No Date -- The guaranteed quote start time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now. start-time="2012-04-09 13:49:40 UTC"
end-time No Date -- The guaranteed quote end time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now. end-time="2012-04-09 14:49:40 UTC"

See Global URL Parameters for available URL parameters.

Request body

The request body below shows all of the fields in a job that could affect the quote.

POST http://localhost:8080/mws/rest/accounting/usage-records/quote?api-version=3&object-type=job&charge-duration=300
------------------------------------

{
  "id": "Moab.1",
  "user": "amy",
  "group": "group",
  "rmName": "machine1",
  "templateList": [
  "genericVm"
  ],
  "account": "biology",
  "qosRequested": "QOS1",
  "variables": {
    "imageName": "centos5.5-stateless",
    "topLevelServiceId": "myService.1",
    "serviceId": "vmService.1",
    "vmid": "VmService.1",
    "pmid": "VmService.1"
  },
  "requirements": [
  {
      "requiredProcessorsPerTask": 2,
      "genericResources": {
         "gold": 100,
         "os": 500
      },
      "requiredNodeCountMinimum": 1,
      "requiredMemoryPerTask": 1024,
      "requiredClass": "batch"
  }
  ]
}

The request body below shows all of the fields in a service that affect the quote in a default MAM installation.

POST http://localhost:8080/mws/rest/accounting/usage-records/quote?api-version=3&object-type=service&charge-duration=300
------------------------------------

{
     "name":"service.1",
     "user": "amy",
     "account": "chemistry"
     "attributes":{
        "moab":{
           "job":{
              "resources":{
                 "procs":1,
                 "mem":2048,
                 "OS":500,
                 "gold":100
              },
              "variables":{
                 "Var1": 1524
              },
              "image":"centos5.5-stateless",
              "template":"genericVM",
           }
        }
     }
  }

Sample response

Restrictions

The details field is only available with MAM version 7.1.0 or later.

Related Topics 

© 2015 Adaptive Computing