source download amazon.lsp
Module: amazon
Functions for the Amazon-AWS EC2, S3 REST API
Version: 0.01 - initial development release
Version: 0.02 - added EC2 API
Version: 0.03 - clean-up documentation and amazon:url-encode
Author: Lutz Mueller 2007, Martin Quiroga 2007
Requirements
As a minimum newLISP version 9.2.8 is required for this module.
The module depends on crypto.lsp, which implements HMAC RFC-2104 authentication and itself depends on the C library libcrypto.
For a descripion of the Amazon Web Services (AWS) REST APIs implemented see: http://developer.amazonwebservices.com/
Usage
Call the amazon:set-AWS-credentials function once after loading this module, then use any of the other functions.
Almost all functions allow for an optional timeout parameter in milliseconds. When no timeout is given all functions assume 30 seconds timeout.
The functions return either a header or a SXML list on success, or nil on failure. On failure the variable amazon:error contains the text of the last error occured.
§
amazon:set-AWS-credentials
syntax: (amazon:set-AWS-credentials acount access-key secret-key)
parameter: account - The acount number to set.
parameter: access-key - The AWS access-key-id to set.
parameter: secret-key - The AWS secret access-key-id to set.
return: Returns true
The EC2 account number AWS-access-key and AWS secret-key credentials should be called first, before calling any other function in the Amazon interface.
Example:(amazon:set-AWS-credentials "123456789012" ; EC2 account number (not used by S3) "01234ABCDE56789GHIK" ; access key "01ab23cd45EF56789+WXYZ987+abcdeLKJH789zz" ; secret access key )§
amazon:create-bucket
syntax: (amazon:create-bucket str-bucket-name [int-timeout])
parameter: str-bucket-name - The name of the bucket i.e.: my-bucket
parameter: int-timeout - The number of milliseconds to wait.
return: Returns header information or nil on failure.
Creates an Amazon S3 bucket.
Example:The first statement reates my-bucket with a default timeout of 30 seconds. On the second statement carries 20 second timeout limit.(amazon:create-bucket "my-bucket") (amazon:create-bucket "my-bucket" 20000)§
amazon:delete-bucket
syntax: (amazon:delete-bucket str-bucket-name [int-timeout])
parameter: str-bucket-name - The name of the bucket i.e.: my-bucket
parameter: int-timeout - The number of milliseconds to wait.
return: Returns amzon header string or nil on failure.
Deletes an Amazon S3 bucket. Deleting a non-existing bucket will fail with nil.
Example:Deletes my-bucket.(amazon:delete-bucket "my-bucket")§
amazon:list-all-buckets
syntax: (amazon:list-all-buckets [int-timeout])
parameter: int-timeout - The number of milliseconds to wait.
return: Returns Amazon REST S3 SXML results or nil on failure.
Lists all the S3 buckets for the account, for which credentials were given.
Example:Lists all buckets.(amazon:list-all-buckets)§
amazon:list-bucket
syntax: (amazon:list-bucket str-bucket-name [str-query [int-timeout]])
parameter: str-bucket-name - The name of the bucket, i.e. my-bucket
parameter: str-query - The optional query string which by default is assumed to be the empty string.
parameter: int-timeout - The number of milliseconds to wait.
return: Returns Amazon REST S3 SXML results or nil on failure.
Lists the contents of a bucket. Optionally a query string can be given to list only a subset of buckets. The query string must be URL encoded and has the usual form of key-value pairs separated by a '&' sign, i.e. prefix=photos&marker=puppies etc.
Example:In the first statement All objects in my-bucket are listed (the query string is empty). The second statement lists all objects in photos and allows a timeout of 10 seconds.(amazon:list-bucket "my-bucket") (amazon:list-bucket "my-bucket" "prefix=photos" 10000)§
amazon:put-bucket-object
syntax: (amazon:put-bucket-object str-bucket-name str-object-name str-content-type buff-pay-load [int-timeout])
parameter: str-bucket-name - The name of the bucket, i.e. my-bucket.
parameter: str-object-name - The name of the object, i.e. foo.
parameter: str-content-type - The content-type of the data, i.e. text/html.
parameter: buff-pay-load - The data of the object in a string buffer.
parameter: int-timeout - The number of milliseconds to wait.
Puts an object into a bucket. An exisiting object will get overwritten. Example:Note that str-object-name can contains sub directory like prefixes separated by a forward slash: Example:(amazon:put-bucket-object "my-bucket" "puppy.jpg" "image/jpeg" (read-file "puppy.jpg") )The statement reads a file puppy.jpg and uploads it to my-bucket. In the second example a sub directory category will automatically be created.(amazon:put-bucket-object "my-bucket" "category/TheThing" "text/html" "The content" )§
amazon:get-bucket-object
syntax: (amazon:get-bucket-object str-bucket-name str-object-name [int-timeout])
parameter: str-bucket-name - The name of the bucket, i.e. my-bucket.
parameter: str-object-name - The name of the object, i.e. foo.
parameter: int-timeout - The number of milliseconds to wait.
Gets an object from a bucket.
Example:Downloads puppy.jpg. Note that str-object-name can contain sub directory like prefixes, separated by a forward slash: Example:(amazon:get-bucket-object "my-bucket" "puppy.jpg")(amazon:get-bucket-object "my-bucket" "category/TheThing") => "The content"§
amazon:delete-bucket-object
syntax: (amazon:delete-bucket-object str-bucket-name str-object-name [int-timeout])
parameter: str-bucket-name - The name of the bucket, i.e. my-bucket.
parameter: str-object-name - The name of the object to be deleted, i.e. foo.
parameter: int-timeout - The number of milliseconds to wait.
Deletes an object from a bucket. Note that deleting with a non-exisiting str-object-name will not result in error, but a wrong str-bucket-name will result in error.
Example:Deletes the file "puppy.jpg". Note that str-object-name can contain sub directory like prefixes separated by a forward slash: Example:(amazon:delete-bucket-object "my-bucket" "puppy.jpg")(amazon:delete-bucket-object "my-bucket" "category/TheThing")§
amazon:ec2-query
syntax: (amazon:ec2-query list-query-parameters)
parameter: list-query-parameters - Is an assoc-list of string key and value pairs corresponding to EC2 Actions and their respective parameters.
return: Returns an SXML list corresponding to the return XML of the query, or nil on failure.
The full Amazon EC2 API documentation can be found here: EC2_Developer_Guide
This API implementation is based on the EC2 Query API described in the documentation. For any EC2 Operation the only required element of the query parameter list is the "Action" element and can take the form of:
For Image Actions:
"RegisterImage" "DescribeImages" "DeregisterImage"
For Instance Actions:
"RunInstances" "DescribeInstances" "TerminateInstances" "ConfirmProductInstance"
For Key Pair Actions:
"CreateKeyPair" "DescribeKeyPairs" "DeleteKeyPair"
For Image Attribute Actions:
"ModifyImageAttribute" "DescribeImageAttribute" "ResetImageAttribute"
For Security Group Actions:
"CreateSecurityGroup" "DescribeSecurityGroups" "DeleteSecurityGroup"
"AuthorizeSecurityGroupIngress" "RevokeSecurityGroupIngress"
The full list of Actions and their corresponding parameters can be found here: Operations_by_Function
Example:If a given Action handles multiple paramters of the same type, these can be provided as a list of values(amazon:ec2-query (list (list "Action" "DescribeInstances") (list "InstanceId" (list "i-564fa43f" "i-e320c98a"))))§
amazon:authorization
syntax: (amazon:authorization str-sign [int-option])
parameter: str-sign - The string to sign.
parameter: int-option - Integer value to toggle between the S3 and EC2 styles of signatures.
The int-option parameter, when set to 0 is for the S3 style of signature and 1 is for the EC2 style.If no value is provided, the default is S3 style.
In the case of the S3 style, amazon:authorization returns an authorization string of the form: AWS access-key:signature where access-key is a 20 byte long key given by Amazon when signing up for Amazon Web Services (AWS) and signature is a 28 byte long BASE64 encoded string resulting from an crypto:hmac signing of the str-sign with the secret-access-key.
In the case of the EC2 style, amazon:authorization simply returns a 28 byte long BASE64 encoded string resulting from an crypto:hmac signing of the str-sign with the secret-access-key.
This function is used by other functions in this API.§
amazon:date
syntax: (amazon:date [offset])
parameter: offset - The offset in minutes from the local time.
Returns the current time string in Internet format, i.e: Fri, 23 Nov 2007 12:06:39 +0000 for signing HTTP requests in the Amazon AWS interface and usage in HTTP headers. The offset parameter is optional, when no offset is given the date string returned is based on GMT and finishes with the letters GMT, else the string is based on the local time and finishes with the +nnnn or -nnnn' offset number given in offset.
Example:This functions is also used by other functions in this API.(amazon:date) => "Mon, 26 Nov 2007 20:08:13 GMT" (amazon:date 300) => "Mon, 26 Nov 2007 15:08:17 +0300"§
amazon:ec2-date
syntax: (amazon:ec2-date [int-unix-time])
parameter: int-unix-time - The time in seconds elapsed since midnight UTC of January 1, 1970.
Returns a time string of the format 2007-12-04T14:04:24-0800 as specified in the ISO 8601 standard for signing EC2 Query API requests. The int-unix-time parameter is optional, when this is not provided the current time is used as a default value.
Example:This functions is also used by other functions in this API.(amazon:ec2-date) => "2007-12-04T16:15:00-0800" (amazon:ec2-date (+ (date-value) 300)) => "2007-12-04T16:20:00-0800"§
amazon:url-encode
syntax: (amazon:url-encode str)
parameter: str - The string to URL encode.
return: Returns a url-encoded (e.g. percent-encoded) string of the input string.
Example:(amazon:url-encode "2007-12-04T14:06:31-0800") => "2007-12-04T14%3a06%3a31-0800"§
amazon:url-decode
syntax: (amazon:url-decode str)
parameter: str - The URL-encoded string to decode.
Returns a decoded string of the url-encoded (e.g. percent-encoded) input string.
Example:(amazon:url-decode "2007-12-04T14%3a06%3a31-0800") => "2007-12-04T14:06:31-0800"- ∂ -
generated with newLISP and newLISPdoc