(Click to open topic with navigation)

5.256 Accounting Usage Records

The resource and services described in this topic are deprecated and may be removed in a future release. Use the comparable resource and services in MAM Web Services instead.

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:

5.256.1 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

5.256.1.A 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 syntax. Besides allowing queries specifying a simple field value (e.g. query={field:value}), you may extract a partial value from a complex field using the form: query={field:{part:value}} or you may use comparison operators of the form: query={field:{op:value}} where op may be one of the following:

  • $eq - equal to
  • $gt - greater than
  • $gte - greater than or equal to
  • $lt - less than
  • $lte - less than or equal to
  • $ne - not equal to

query={"account":"chemistry"}

query={"variables":{"foo":"bar"}}

query={"endTime":{$gt:"2016-03-01 00:00:00 UTC"}}

query={"licenses":{"matlab":{$gte:1}}}

fields No String -- Comma-separated list of field names to display. Partial values may be requested for complex (multi-valued) attributes in the form: attribute_name{part_name}. fields=id,instance,charge,user,account,licenses{matlab}
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"
    }
}

5.256.1.B 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. Partial values may be requested for complex (multi-valued) attributes in the form: attribute_name{part_name}. fields=id,instance,charge,user,account,licenses{matlab}
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": ""
}

5.256.1.C 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": "centos6.6-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":"centos6.6-stateless",
              "template":"genericVM",
           }
        }
     }
  }

Sample response

Restrictions

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

Related Topics 

© 2016 Adaptive Computing