On this page:
13.1 Region
region
13.2 Vaults
create-vault
delete-vault
list-vaults
describe-vault
13.3 Vault notifications
set-vault-notifications
get-vault-notifications
delete-vault-notifications
13.4 Archives
create-archive
create-archive-from-file
delete-archive
13.5 Retrieval jobs
retrieve-inventory
retrieve-archive
list-jobs
get-job-output
get-output-job-to-file
13.6 Example: Backup using Glacier and SDB

13 Glacier (Archives)

 (require (planet gh/aws:1:=4/glacier))

Glacier provides storage for archiving. You can store objects less expensively than using S3. The trade-off is that it is very slow to retreive them.

13.1 Region

parameter

(region)  string?

(region v)  void?
  v : string?
Set the region. Defaults to "us-east-1".

13.2 Vaults

procedure

(create-vault name)  (or/c #t exn:fail:aws?)

  name : string?
Create a vault and return #t or raise exn:aws:fail?. Idempotent.

procedure

(delete-vault name)  (or/c #t exn:fail:aws?)

  name : string?
Delete a vault and return #t or raise exn:aws:fail?. Idempotent.

procedure

(list-vaults)  jsexpr?

> (list-vaults)
'(#hasheq((VaultName . "testvault")
          (CreationDate . "2012-08-30T12:29:37.200Z")
          (LastInventoryDate . null)
          (NumberOfArchives . 0)
          (SizeInBytes . 0)
          (VaultARN . "arn:aws:glacier:us-east-1:203585791165:vaults/testvault")))

procedure

(describe-vault name)  jsexpr?

  name : string?

13.3 Vault notifications

procedure

(set-vault-notifications name    
  sns-topic    
  inventory?    
  archive?)  (or/c #t exn:fail:aws?)
  name : string?
  sns-topic : string?
  inventory? : boolean?
  archive? : boolean?

procedure

(get-vault-notifications name)  jsexpr?

  name : string?

procedure

(delete-vault-notifications name)  void?

  name : string?

13.4 Archives

procedure

(create-archive vault-name    
  archive-description    
  data)  string?
  vault-name : string?
  archive-description : string?
  data : bytes?
Create an archive containing the data and return its archive ID.

procedure

(create-archive-from-file vault-name path)  string?

  vault-name : string?
  path : path?
Create an archive with data from a file and return its archive ID.

procedure

(delete-archive vault-name archive-id)  (or/c #t exn:fail:aws?)

  vault-name : string?
  archive-id : string?
Delete an archive.

13.5 Retrieval jobs

procedure

(retrieve-inventory vault-name    
  job-description    
  [sns-topic])  string?
  vault-name : string?
  job-description : string?
  sns-topic : (or/c string? #f) = #f
Initiate a job to retrieve an archive’s inventory, and return the job ID.

procedure

(retrieve-archive vault-name    
  job-description    
  [sns-topic])  string?
  vault-name : string?
  job-description : string?
  sns-topic : (or/c string? #f) = #f
Initiate a job to retrieve an archive’s data, and return the job ID.

procedure

(list-jobs vault-name)  jsexpr?

  vault-name : string?

procedure

(get-job-output vault-name job-id)  (or/c jsexpr? bytes?)

  vault-name : string?
  job-id : string?
Get the output of a job. If the Content-Type of the response is application/json, return the result as a jsexpr?, otherwise return it as bytes?.

procedure

(get-output-job-to-file vault-name    
  job-id    
  path    
  exists)  boolean?
  vault-name : string?
  job-id : string?
  path : path?
  exists : (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace)
Get the output of an archive retrieval job and put it in a file. Return a boolean? whether the output matches its x-amz-sha256-tree-hash.

13.6 Example: Backup using Glacier and SDB

This example can be found in examples/backup.rkt.

#lang racket
 
;; Use Glacier for archival backups, and SDB to store the metadata.
 
(require (planet gh/aws/sdb)
         (planet gh/aws/sns)
         (planet gh/aws/glacier)
         (planet gh/http/request))      ;just for seconds->gmt-8601-string
 
(define path->archive-domain "examplesBackupPathToArchive")
(define archive->meta-domain "examplesBackupArchiveToMeta")
(define vault "examples.backup")
 
(define (ensure-assets)
  ;; Creating a vault on Glacier is idempotent; harmless to do again.
  (create-vault vault)
  ;; Creating a domain on SDB is idempotent; harmless to do again.
  (create-domain path->archive-domain)
  (create-domain archive->meta-domain))
 
(define/contract (archive-file path)
  (path? . -> . void?)
  (define path/string (path->string path))
  ;; Upload to Glacier.
  (printf "~a\nUploading to Amazon Glacier ...\n" path/string)
  (define archive-id (create-archive-from-file vault path))
  ;; Store some metadata on SDB.
  ;;
  ;; Using the path for SDB's ItemName, store an attribute named
  ;; ArchiveId with the Glacier archive ID as the value. Remember that
  ;; SDB allows multiple values per attribute, so setting this more
  ;; than once will add more values rather than replace.
  (printf "Updating Amazon Simple Database with metadata ...\n")
  (put-attributes path->archive-domain
                  path/string
                  `([ArchiveId ,archive-id]))
  ;; Also store some info about this specific archive.
  (put-attributes archive->meta-domain
                  archive-id
                  `([Size ,(number->string (file-size path))]
                    [Date ,(seconds->gmt-8601-string)]
                    [Path ,path/string]))
  (void))
 
(define/contract (archive-directory path [sns-topic #f])
  ((path-string?) (string?) . ->* . void?)
  (printf "Ensuring Amazon SDB and Glacier resources are created ...\n")
  (ensure-assets)
  (printf "Starting archive of all files under ~a ...\n" path)
  (for ([x (in-directory path)])
      ;; Unless a directory or a dot file
      (unless (or (directory-exists? x)
                  (equal? #\. (string-ref (path->string x) 0)))
        (archive-file x)))
  (when sns-topic
    (publish sns-topic (format "Archive completed ~a." (seconds->gmt-string))))
  (void))
 
;; For example let's archive the file in our tests dir.
(define root-dir
  (path->string (simplify-path (path->complete-path (build-path 'up "tests")))))
;; Let's notify to our first SNS topic (if any)
(define sns-topic (match (list-topics) [(list x rest ...) x][else #f]))
(archive-directory root-dir sns-topic)
 
;; Let's look at the information from SDB
(select-hash (format "SELECT * FROM ~a" path->archive-domain))
(select-hash (format "SELECT * FROM ~a" archive->meta-domain))