aws - Backendjs Documentation

module:aws

Description:

AWS API interface, uses API directly for each service, JSON is returned as is but XML repsonses are converted using fast-xml-parser into objects.

Methods

(static) aws.cwGetMetricData()

Description:

Return collected metric statistics

Options:
- start_time - starting timestamp
- end_time - ending timestamp
- period - aggregation period in seconds, default is 60, if < 0 then dunamically set it for the time range
- age - number of ms to go back in case start_time is not specified, fraction can be used, default is 30 secs if no timestamp are given
- namespace - namespace for all metrics, default is AWS/EC2
- desc - return data in descending order
- metrics - a list with metrics to retrieve: { name: "..", stat: "..", dimensions: { key: val, ...}, [namespace: ".."], [label: "..""], [hidden: 1], [expression: ".."] }
Returns an object: { data: [{ id, label, timestamps: [], data: [] }], errors: [] }

Example:
```
aws.cwGetMetricData({ age: 300000, metrics: [{ name: "NetworkOut", label: "Traffic", stat: "Average", dimensions: { InstanceId: "i-1234567" } } ] }, lib.log)
```

(static) aws.cwListMetrics()

Description:

Return metrics for the given query, the options can be specified:
- name - a metric name
- namespace - limit by namespace: AWS/AutoScaling, AWS Billing, AWS/CloudFront, AWS/DynamoDB, AWS/ElastiCache, AWS/EBS, AWS/EC2, AWS/ELB, AWS/ElasticMapReduce, AWS/Kinesis, AWS/OpsWorks, AWS/Redshift, AWS/RDS, AWS/Route53, AWS/SNS, AWS/SQS, AWS/SWF, AWS/StorageGateway

(static) aws.cwPutLogEvents()

Description:

Store events in the Cloudwatch Logs. Options:
- name - log group name, required
- stream - log stream name, required
- events - a list of strings, or objects { timestamp, message }, required
- tm_pos - position in the message where the timestamp starts, default is 0
- tm_sep - separator after the timestamp, default is space

(static) aws.cwPutMetricAlarm()

Description:

Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. The options specify the following:
- name - alarm name, if not specified metric name and dimensions will be used to generate alarm name
- metric - metric name, default is CPUUtilization
- namespace - AWS namespace, default is AWS/EC2
- op - comparison operator, one of => | <= | > | < | GreaterThanOrEqualToThreshold | GreaterThanThreshold | LessThanThreshold | LessThanOrEqualToThreshold. Default is >=.
- statistic - one of SampleCount | Average | Sum | Minimum | Maximum, default is Average
- period - collection period in seconds, default is 60
- evaluationPeriods - the number of periods over which data is compared to the specified threshold, default is 15
- threshold - the value against which the specified statistic is compared, default is 90
- ok - ARN(s) to be notified on OK state
- alarm - ARN(s) to be notified on ALARM state
- insufficient_data - ARN(s) to be notified on INSUFFICIENT_DATA state
- dimensions - the dimensions for the alarm's associated metric.

(static) aws.cwPutMetricData()

Description:

Publishes metric data points to Amazon CloudWatch. The argumernts specify the following:
- namespace - custome namespace, cannot start with AWS
- data - an object with metric data: { metricName: value }, ... { metricName: { value: Number, dimension1: name1, .. }, }, ... { metricName: { value: [min, max, sum, sample], dimension1: ... }, }, ...
The options can specify the following:
- storageResolution - 1 to use 1 second resolution
- timestamp - ms to be used as the timestamp instead of the current time

(static) aws.cwlFilterLogEvents()

Description:

Lists log events from the specified log group. You can list all the log events or filter the results using a filter pattern, a time range, and the name of the log stream. Options:
- name - a group name, required
- count - how many events to retrieve in one batch, 10000
- limit - total number of events to return
- filter - filter pattern
- stime - start time in ms
- etime - end time in ms
- prefix - log stream prefix pattern
- names - list of log streams to filter
- token - a previous token to start with
- timeout - how long to keep reading or waiting, ms

(static) aws.ddbBatchGetItem()

Description:

Retrieve all items for given list of keys
- items is an object with table name as property name and list of options for GetItem request
- options may contain any valid native property if it starts with capital letter.

Example

{ users: { keys: [{ id: 1, name: "john" },{ id: .., name: .. }], select: ['name','id'], consistent: true }, ... }

(static) aws.ddbBatchWriteItem()

Description:

Update items from the list at the same time
- items is a list of objects with table name as property and list of operations, an operation can be PutRequest or DeleteRequest
- options may contain any valid native property if it starts with capital letter.

Example

{ table: [ { put: { id: 1, name: "tt" } }, { del: { id: 2 } }] }

(static) aws.ddbCreateTable()

Description:

Create a table
- attrs can be an array in native DDB JSON format or an object with name:type properties, type is one of S, N, NN, NS, BS
- options may contain any valid native property if it starts with capital letter and the following:
  - waitTimeout - number of milliseconds to wait for ACTIVE status
  - waitDelay - how often to pool for table status, default is 250ms
  - keys is an array of column ids used for the primary key or a string with the hash key. if omitted, the first attribute will be used for the primary key
  - local - an object with each property for a local secondary index name defining key format the same way as for primary keys, all Uppercase properties are added to the top index object
  - global - an object for global secondary indexes, same format as for local indexes
  - projections - an object with index name and list of projected properties to be included in the index or "ALL" for all properties, if omitted then default KEYS_ONLY is assumed
  - readCapacity - read capacity units for provisioned throughput
  - writeCapacity - write capacity units
  - onDemand - billing mode, auto provision capacity and pay per request, if no read/write capacity is configured on-demand is the default
  - stream - enable stream support

Example

ddbCreateTable('users', { id: 'S', mtime: 'N', name: 'S'},
                                 { keys: ["id", "name"],
                                   local: { mtime: { mtime: "HASH" } },
                                   global: { name: { name: 'HASH', ProvisionedThroughput: { ReadCapacityUnits: 50 } } },
                                   projections: { mtime: ['gender','age'],
                                                  name: ['name','gender'] },
                                   stream: "NEW_IMAGE",
                                   readCapacity: 10,
                                   writeCapacity: 10 });

(static) aws.ddbDeleteItem()

Description:

Delete an item from a table
- keys is an object with name: value for hash/range attributes
- options may contain any valid native property if it starts with capital letter and the following special options:
  - expr - condition expression
  - values - an object with values map to be used for in the update and/or condition expressions, to be used for ExpressionAttributeValues parameters
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter
  - returning - values to be returned on success, any value means ALL_OLD

Example

ddbDeleteItem("users", { id: 1, name: "john" }, {})

(static) aws.ddbDeleteTable()

Description:

Remove a table from the database. By default the callback will ba callled only after the table is deleted, specifying options.nowait will return immediately

(static) aws.ddbDescribeTable()

Description:

Return table definition and parameters in the result structure with property of the given table name

Example

{ name: { AttributeDefinitions: [], KeySchema: [] ...} }

(static) aws.ddbGetItem()

Description:

Retrieve one item by primary key
- keys - an object with primary key attributes name and value.
- select - list of columns to return, otherwise all columns will be returned
- options may contain any native property allowed in the request or special properties:
  - consistent - set consistency level for the request
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter

Example

ddbGetItem("users", { id: 1, name: "john" }, { select: 'id,name' })

(static) aws.ddbPutItem()

Description:

Put or add an item
- item is an object, type will be inferred from the native js type.
- options may contain any valid native property if it starts with capital letter or special properties:
  - query - an object with column names to be used in ConditionExpression clause and value as null to set condition to { Exists: false } or any other exact value to be checked against which corresponds to { Exists: true, Value: value }
  - expr - condition expression
  - values - an object with values map to be used for in the update and/or condition expressions, to be used for ExpressionAttributeValues parameters
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter
  - returning - values to be returned on success, any value means ALL_OLD

Example

ddbPutItem("users", { id: 1, name: "john", mtime: 11233434 }, { query: { name: null } })

(static) aws.ddbQueryTable()

Description:

Query on a table, return all matching items
- condition is an object with name: value pairs, by default EQ opeartor is used for comparison
- options may contain any valid native property if it starts with capital letter or special property:
  - start - defines starting primary key when paginating, can be a string/number for hash or an object with hash/range properties
  - consistent - set consistency level for the request
  - select - list of attributes to get only
  - total - return number of matching records
  - count - limit number of record in result
  - desc - descending order
  - sort - index name to use, indexes are named the same as the corresponding column, with index primary keys for Keycondition will be used
  - ops - an object with operators to be used for properties if other than EQ.
  - keys - list of primary key columns, if there are other properties in the condition then they will be put into QueryFilter instead of KeyConditions. If keys are absent, all properties in the condition are treated as primary keys.
  - projection - projection expression
  - values - an object with values map to be used for in the update and/or condition expressions, to be used for ExpressionAttributeValues parameters
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter
  - expr - filtering expression

Example

aws.ddbQueryTable("users", { id: 1, name: "john" }, { select: 'id,name', ops: { name: 'gt' } })
         aws.ddbQueryTable("users", { id: 1, name: "john", status: "ok" }, { keys: ["id"], select: 'id,name', ops: { name: 'gt' } })
         aws.ddbQueryTable("users", { id: 1 }, { expr: "status=:s", values: { s: "status" } })

(static) aws.ddbScanTable()

Description:

Scan a table for all matching items
- condition is an object with name: value pairs or a string with FilterExpression
- options may contain any valid native property if it starts with capital letter or special property:
  - start - defines starting primary key
  - ops - an object with operators to be used for properties if other than EQ.
  - projection - projection expression
  - values - an object with values map to be used for in the update and/or condition expressions, to be used for ExpressionAttributeValues parameters
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter

Example

aws.ddbScanTable("users", { id: 1, name: 'a' }, { ops: { name: 'gt' }})
         aws.ddbScanTable("users", "id=:id AND name=:name", { values: { id: 1, name: 'a' } });

(static) aws.ddbTransactWriteItems()

Description:

Update items from the list at the same time in one transaction, on any failure everything is rolled back
- items is a list of operations to be performed in the same format as for aws.ddbPutItem, aws.ddbUpdateItem, aws.ddbDeleteItem and aws.ddbQueryItem
- options may contain any valid native property if it starts with capital letter.

Example

{ op: "put": table: "table-name", obj: { id: 1, name: "tt" } },
         { op: "del": table: "table-name", obj: { id: 2 } },
         { op: "update": table: "table-name", obj: { id: 1, name: "test" }, options: { query: { status: "ok" } } },
         { op: "check": table: "table-name", obj: { id: 1 }, options: { query: { status: "ok" } } }

(static) aws.ddbUpdateItem()

Description:

Update an item
- keys is an object with primary key attributes name and value.
- item is an object with properties where value can be:
  - number/string/array - action PUT, replace or add new value
  - null/empty string - action DELETE
- item can be a string with Update expression
- options may contain any valid native property if it starts with capital letter or special properties:
  - expr - condition expression
  - values - an object with values map to be used for in the update and/or condition expressions, to be used for ExpressionAttributeValues parameters
  - names - an object with a map to be used for attribute names in condition and update expressions, to be used for ExpressionAttributeNames parameter
  - updateOps - an object with operators to be used for properties, one of the: set, remove, unset, delete, incr, add, append, prepend, not_exists
  - query - an object with columns to be used in ConditionExpression, value null means the attribute does not exists, any other value to be checked against using regular compare rules. The conditional comparison operator is taken from options.ops the same way as for queries.
  - returning - values to be returned on success, * or new means ALL_NEW, old means ALL_OLD, updated means UPDATED_NEW, old_updated means UPDATED_OLD

Example

ddbUpdateItem("users", { id: 1, name: "john" }, { gender: 'male', icons: '1.png' }, { action: { icons: 'add' }, query: { id: 1 }, returning: "*" })
         ddbUpdateItem("users", { id: 1, name: "john" }, { gender: 'male', icons: '1.png' }, { action: { icons: 'incr' }, query: { id: null } })
         ddbUpdateItem("users", { id: 1, name: "john" }, { gender: 'male', icons: '1.png', num: 1 }, { action: { num: 'add', icons: 'add' }, query: { id: null, num: 0 }, ops: { num: "gt" } })

(static) aws.ddbUpdateTable()

Description:

Update tables provisioned throughput settings, options is used instead of table name so this call can be used directly in the cron jobs to adjust provisionined throughput on demand. Options must provide the following properties:
- name - table name
- readCapacity and writeCapacity - new povisioned throughtput settings, both must be specified
- stream - null to disable or one of the NEW_IMAGE | OLD_IMAGE | NEW_AND_OLD_IMAGES | KEYS_ONLY
- add - an object with indexes to create
- del - delete a global secondary index by name, a string or a list with multiple indexes
- update - an object with indexes to update
- waitTimeout - how long to wait in ms until the table is active again
- onDemand - true to switch to pat per request mode, false to switch to provisioning mode
Example
```
         aws.ddbUpdateTable({ name: "users", add: { name_id: { name: "S", id: 'N', readCapacity: 20, writeCapacity: 20, projections: ["mtime","email"] } })
         aws.ddbUpdateTable({ name: "users", add: { name: { name: "S", readCapacity: 20, writeCapacity: 20, projections: ["mtime","email"] } })
         aws.ddbUpdateTable({ name: "users", del: "name" })
         aws.ddbUpdateTable({ name: "users", update: { name: { readCapacity: 10, writeCapacity: 10 } })
```

Example

of crontab job in etc/crontab:

             [
             { "type": "server", "cron": "0 0 1 * * *", "job": { "aws.ddbUpdateTable": { "name": "bk_user", "readCapacity": 1000, "writeCapacity": 1000 } } },
             { "type": "server", "cron": "0 0 6 * * *", "job": { "aws.ddbUpdateTable": { "name": "bk_user", "readCapacity": 2000, "writeCapacity": 2000 } } }
             ]

(static) aws.ddbUpdateTimeToLive()

Description:

Update TTL attribute. The options properties:
- name - table name
- attribute - the attribute name
- enabled - true or false

(static) aws.ddbWaitForTable()

Description:

Call the callback after specified period of time or when table status become different from the given waiting status. if options.waitTimeout is not specified calls the callback immediately. options.waitStatus is checked if given and keeps waiting while the status is equal to it. options.waitDelay can be specified how often to request new status, default is 250ms.

(static) aws.queryCW()

Description:

AWS CloudWatch API request

(static) aws.queryCWL()

Description:

AWS CloudWatch Log API request

(static) aws.querySQS()

Description:

AWS SQS API request

(static) aws.sqsReceiveMessage()

Description:

Receive message(s) from the SQS queue, the callback will receive a list with messages if no error. The following options can be specified:
- count - how many messages to receive
- timeout - how long to wait, in milliseconds, this is for Long Poll
- visibilityTimeout - the duration (in milliseconds) that the received messages are hidden from subsequent retrieve requests
- attempt - request attempt id for FIFO queues after being retrieved by a ReceiveMessage request.

(static) aws.sqsSendMessage()

Description:

Send a message to the SQS queue. The options can specify the following:
- delay - how long to delay this message in milliseconds
- group - a group id for FIFO queues
- unique - deduplication id for FIFO queues
- attrs - an object with additional message attributes to send, use only string, numbers or binary values, all other types will be converted into strings