Repository files navigation

A library for connecting toGoogle Cloud Storage through Lua.

You can learn more about authenticating with Google Cloud Storage here:https://cloud.google.com/storage/docs/authentication.

Here's a quick guide to get you started:

The easiest way use this library is to create a service account for yourproject. You'll need to generate a private key and store it alongside yourconfiguration.

Go to the cloud console:https://console.cloud.google.com. Enable CloudStorage if you haven't done so already. You may also need to enter billinginformation.

Navigate toIAM & admin »Service accounts, located on the sidebar.ClickCreate service account.

SelectFurnish a new private key and selectJSON as the type. Aftercreating the service account your browser will download a.json file. Storethat securely, since it grants access to your project.

The.json is used to create a new API client with this library:

localgoogle=require"cloud_storage.google"localstorage=google.CloudStorage:from_json_key_file("path/to/my-key.json")-- you can now use any of the methods on the storage objectlocalfiles=assert(storage:get_bucket("my_bucket"))

openssl pkcs12 -in key.p12 -out key.pem -nodes -clcerts

localoauth=require"cloud_storage.oauth"localgoogle=require"cloud_storage.google"-- replace with your service account IDlocalo=oauth.OAuth("cloud-storage@my-project.iam.gserviceaccount.com","path/to/key.pem")-- use your id as the second argument, everything before the @ in your service account IDlocalstorage=google.CloudStorage(o,"cloud-storage")localfiles=assert(storage:get_bucket("my_bucket"))

By default, this library usessocket.http for making HTTP requests. You can provide a custom HTTP client that supports the LuaSocket interface:

localhttp=require("cloud_storage.http")-- Replace with your custom HTTP client-- Must implement a request() function compatible with LuaSockethttp.set(require("lapis.http"))-- Now all future requests will use the `request` function in your http client...

This allows for custom timeout handling, proxy configuration, or mock clients for testing.

This module contains the OAuth implementation used by the storage API.

localoauth=require"cloud_storage.oauth"

Create a new OAuth object. Handles OAuth authenticated requests.

It's not necessary to use this module directly if loading private key from a.json file.

Communicates with the Google cloud storage API.

localgoogle=require"cloud_storage.google"

Any methods that fail to execute will returnnil, an error message, and anobject that represents the error. Successful responses will return a Lua tablecontaining the details of the operation.

Create a new instance of a storage object from an OAuth instance. Note that thefrom_json_key_file interface is a simpler way of constructing the storageinterface.

localoauth=require"cloud_storage.oauth"localgoogle=require"cloud_storage.google"localo=oauth.OAuth("me@my-project.iam.gserviceaccount.com","key.pem")localstorage=google.CloudStorage(o,"111111111111")

Create a new instance of a storage object from a.json private key filegenerated by the Google Cloud Console.

localgoogle=require"cloud_storage.google"localstorage=google.CloudStorage:from_json_key_file("my-storage-auth.json")

https://cloud.google.com/storage/docs/xml-api/get-service

https://cloud.google.com/storage/docs/xml-api/get-bucket

https://cloud.google.com/storage/docs/xml-api/get-object

https://cloud.google.com/storage/docs/xml-api/delete-object

https://cloud.google.com/storage/docs/xml-api/head-object

https://cloud.google.com/storage/docs/xml-api/put-object-copy

Options:

• acl: value to use forx-goog-acl, defaults topublic-read
• headers: table of additional headers to include in request

https://cloud.google.com/storage/docs/xml-api/put-object-compose

Composes a new file from multiple source files in the same bucket byconcatenating them.

source_keys is an array of keys as strings or an array of key declarations astables.

The table format for a source key is structured like this:

{name="file.png",-- optional fields:generation="1361471441094000",if_generation_match="1361471441094000",}

Options:

• acl: value to use forx-goog-acl, defaults topublic-read
• mimetype: setsContent-type header for the composed file
• headers: table of additional headers to include in request

Note: this API previously hadkey as an option but it was moved tosecond argument

Uploads the stringdata to the bucket at the specified key.

Options include:

• mimetype: setsContent-type header for the file, defaults to not being set
• acl: sets thex-goog-acl header for file, defaults topublic-read
• headers: an optional array table of any additional headers to send

storage:put_file_string("my_bucket","message.txt","hello world!", {mimetype="text/plain",acl="private"})

Readsfname from disk and uploads it. The key of the file will be the name ofthe file unlessopts.key is provided. The mimetype of the file is guessedbased on the extension unlessopts.mimetype is provided.

storage:put_file("my_bucket","source.lua", {mimetype="text/lua"})

All the same options fromput_file_string are available for this method.

Note: This method is currently inefficient . The whole file is loadedinto memory and sent at once in the request. An alternative implementationwill be added in the future. Open a ticket if you need it.

https://cloud.google.com/storage/docs/xml-api/resumable-upload

Options:

• acl: value to use forx-goog-acl, defaults topublic-read
• mimetype: setsContent-type header for the composed file
• headers: table of additional headers to include in request

Returns full URL for a bucket

Options:

• subdomain: use the{bucket}.domain format instead of defaultdomain/{bucket} format
• scheme: protocol of returned URL, defaulthttps

Returns full URL for a key on a bucket. Supports the same options asstorage:bucket_url method.

storage:file_url("my-bucket","pics/leafo.png")--> "https://commondatastorage.googleapis.com/my-bucket/pics/leafo.png"storage:file_url("my-bucket","pics/leafo.png", {scheme="http",subdomain=true,})--> "http://my-bucket.commondatastorage.googleapis.com/pics/leafo.png"

Options:

• subdomain: use the{bucket}.domain format instead of defaultdomain/{bucket} format
• scheme: protocol of returned URL, defaulthttps

Creates a temporarily URL for downloading an object regardless of it's ACL.expiration is a Unix timestamp in the future, like one generated fromos.time().

print(storage:signed_url("my_bucket","message.txt",os.time()+100))

Options:

• headers: table of additionalx-goog headers to embed into the signature
• verb: HTTP verb to embed into the signature, deafultGET
• scheme: protocol of returned URL, defaulthttps

Generate a signed URL for browser-based upload.

Options:

• content_disposition
• filename If provided, will append to content disposition asfilename= (and set content disposition toattachment if none is provided)
• acl defaultproject-private
• success_action_redirect
• expires unix timestamp. Deafult: 1 hour from now
• size_limit
• scheme protocol of returned URL, defaulthttps

https://cloud.google.com/storage/docs/xml-api/put-object-acls

All future changelogs will be post on github release notes:https://github.com/leafo/cloud_storage/releases

• Changedput_file_string now takeskey as second argument, instead of within options table
• Replaceluacrypto withluaossl
• Add support forjson private keys
• Better error handling for all API calls. (Failures returnnil, error message, and error object)
• Addcopy_file andcompose methods
• Addupload_url method to create upload URLs
• Addstart_resumable_upload method for creating resumable uploads
• Headers are canonicalized and sorted to make them consistent between calls
• Fix bug where special characters in key were not being URL encoded
• Fix bug where some special characters were not being encoded for signed URLs
• Rewrite documentation tutorial

• Initial release