On this page:
2.1 Names
2.2 AWS Keys
public-key
private-key
read-keys
ensure-have-keys
use-iam-ec2-credentials!
2.3 Request authorization
add-v4-auth-heads
2.4 Exception handling
exn:  fail:  aws
header&response->exn:  fail:  aws
check-response
2.5 Connection pooling

2 All Services

2.1 Names

The names of procedures and structs generally do not have special prefixes to “group” them. Instead, use the prefix-in option for require if you prefer a prefix (or need one to avoid a name collision).

For example if you want the aws/sns procedures to have an sns- prefix, so that create-topic is renamed to sns-create-topic:

(require (prefix-in sns- aws/sns))
(sns-create-topic "foobar")

2.2 AWS Keys

 (require aws/keys) package: aws

parameter

(public-key)  string?

(public-key key)  void?
  key : string?
Your AWS public key, a.k.a. “Access ID.”

parameter

(private-key)  string?

(private-key key)  void?
  key : string?
Your AWS private key, a.k.a. “Secret Key.”

procedure

(read-keys [file])  void?

  file : path?
   = (build-path(find-system-path 'home-dir) ".aws-keys")
Set the parameters public-key and private-key by reading their values from a plain text file. The file should consist of two lines:

AWSAccessKeyId=<key>

AWSSecretKey=<key>

By default this file is ~/.aws-keys. You probably want to chmod the permissions of this file carefully.

If your code will run on an EC2 instance, instead consider using use-iam-ec2-credentials!.

procedure

(ensure-have-keys)  void?

If either public-key or private-key is "", calls read-keys. If either is still blank, calls error with a hopefully helpful reminder about how to set the parameters.

procedure

(use-iam-ec2-credentials! iam-role-name)  void?

  iam-role-name : string?

Added in version 1.10 of package aws.

When your code is running on an EC2 instance, instead of you supplying credentials in a configuration file (like ~/.aws-keys) or in environment variables, it is possible to obtain credentials from EC2 instance meta-data. This simplifies configuration and is more secure.

For more information how to configure this, see IAM Roles for Amazon EC2. Step five of those instructions — “Have the application retrieve a set of temporary credentials and use them” — is done by simply calling this function once when your program starts.

Credentials are initially obtained — and subsequently refreshed before they expire — from the EC2 instance meta-data. The public-key and private-key parameters are automatically set to these values. Those keys are used to sign requests made by this library. The X-Amz-Security-Token header is supplied when making requests.

2.3 Request authorization

 (require aws/sigv4) package: aws

procedure

(add-v4-auth-heads #:heads heads    
  #:method method    
  #:uri uri    
  #:sha256 sha256    
  #:region region    
  #:service service)  dict?
  heads : dict?
  method : string
  uri : string?
  sha256 : string?
  region : string?
  service : string?

Added in version 1.12 of package aws.

Given a dict? of HTTP request headers, add one or more headers required by AWS for authorization:

Various functions in this library that make requests, use this function. As a result, you will probably not need to use it directly — unless you want to sign requests for AWS functionality that is not wrapped by this library.

2.4 Exception handling

Most of the functions do not return a failure value. Instead they raise exn:fail:aws, which you need to “catch” using with-handlers.

 (require aws/exn) package: aws

struct

(struct exn:fail:aws (http-code http-message aws-code aws-message)
    #:extra-constructor-name make-exn:fail:aws)
  http-code : exact-positive-integer?
  http-message : string?
  aws-code : string?
  aws-message : string?

procedure

(header&response->exn:fail:aws headers    
  body    
  ccm)  exn:fail:aws?
  headers : string?
  body : (or/c bytes? xexpr?)
  ccm : continuation-mark-set?
Given an HTTP response’s headers and body, return a exn:fail:aws constructed with information from the response.

procedure

(check-response in headers)

  (or/c string? (raise/c exn:fail:aws?))
  in : input-port?
  headers : string?
Check headers. If the status code is one of 200, 201, 202, 204, 206, 301, 302, or 307, simply return headers (without reading any response body from in).

Otherwise, read the XML response body from in and use the information to construct and raise exn:fail:aws.

Note: This does not close the input port in before raising an exception. It assumes you are using call/requests, call/input-request, or call/output-request from the http/request library (or using dynamic-wind or other exception handling, or a custodian—or whatever) to make sure the port is closed!

2.5 Connection pooling

This library uses the http package to make HTTP connections to AWS. You may cause connections to be reused ("pooled") by setting the current-pool-timeout parameter to some non-zero number of seconds.

This can be faster, especially for many small requests in a row.

In the following example, the first list-buckets request will leave the connection open for 30 seconds. As a result, the second list-buckets request will reuse the same connection. After another 30 seconds, the connection will be closed automatically.

(require http/request
         aws/s3)
(parameterize ([current-pool-timeout 30])
  (list-buckets)
  (list-buckets))