Deprecation Notice: The Files API feature is going to be removed at some time in the future, replaced by the Google Cloud Storage Client Library . The documentation for the deprecated API is retained for the convenience of developers still using the Files API.
This document discusses the functions that the
google.appengine.api.files
package provides for the Google Cloud
Storage Python API.
Contents
Functions
- files.gs.create()
- files.listdir()
- files.delete()
- files.open()
- files.File.write()
- files.File.read()
- files.File.tell()
- files.File.seek()
- files.File.close()
- files.finalize()
Classes
Functions
- files.gs.create ( filename , mime_type = 'application/octet' , acl = None , cache_control = None , content_encoding = None content_disposition = None , content_encoding = None , user_metadata = None )
-
Create a Google Cloud Storage object in the specified bucket.
Arguments
- filename (Required)
-
The Google Cloud Storage file name for the object, in the format
/gs/bucket/object_name
. Theobject_name
can contain any sequence of Unicode characters, but cannot exceed 1024 bytes when UTF-8 encoded. Avoid using control characters that are considered illegal in XML 1.0 when creating an object name, as Google Cloud Storage omits these characters when listing objects. If an object with the same name already exists, the object created by this function will overwrite the existing object. - mime_type = 'application/octet-stream' (Optional)
- The MIME type of the object. If you do not specify a MIME type, the default application/octet-stream MIME type will be set for you.
- acl = none (Optional)
-
Set a predefined ACL on your object.
If you do not set this parameter, the API sets this parameter as null and uses the default object ACL for that bucket (by default, this is
project-private
). - cache_control = None (Optional)
-
Set a Cache-Control header on your object. If you do not set this header, the Google Cloud Storage API sets:
-
Cache-Control: public, max-age=3600
for publicly readable objects (objects with the ACLpublic-read
) -
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
for private objects (objects with the ACLprivate
).
-
- content_encoding = None (Optional)
-
If your object is compressed, specify the compression method using the Content-Encoding header.
- content_disposition = None (Optional)
-
Set the Content-Disposition header for your object.
- user_metadata = None (Optional)
-
Set custom headers and values using a Dictionary data set. These headers are served on
GET
requests to the user in the format x-goog-meta- custom_header : custom_value . For example, you can set custom headers as follows:params = {'author':'john', 'task':'1'} gs.create(... user_metadata=params)
The headers are served on
GET
requests:HTTP/1.1 200 OK Cache-Control: my cache control ETag: "7d677bb83bf43de498557f4a47570b21" Content-Type: application/octet-stream Last-Modified: Tue, 13 Sep 2011 17:57:04 GMT x-goog-meta-author: john x-goog-meta-task: 1 Content-Length: 45
Result Value
Returns a handle to the newly created object.
Returns a sorted list of the objects in the specified bucket path.
Arguments
- path (Required)
-
The Google Cloud Storage bucket path, in the format
/gs/bucketname
. Supply only the bucket name in the path; do not supply subdirectories inpath
. You can use theprefix
parameter to supply subdirectories. - prefix = None (Optional)
- Specifies a pattern, resulting in the return only those file names that match the pattern. (This does not support regular expressions.) You can supply a file prefix, such as a subdirectory path.
- marker = None (Optional)
-
The file name at which you want to start listing, with the returned
list excluding the file name used as marker. One way to use this
parameter is to use it with
max_keys
to "page through" the bucket's file names. - max_keys = None (Optional)
-
The maximum number of file names to be returned.
files.listdir('/gs/mybucket', prefix='/mysubdir/backups', max_keys=20)
Result Value
Returns a sorted list of file names.
Permanently deletes the specified file or files from Google Cloud Storage or Blobstore.
This works only on read-only file names.
Arguments
- filenames (Required)
-
The file to delete, in the format of
/gs/bucket/object
(for Google Cloud Storage files) or/blobstore/ blobkey
(for Blobstore files). To delete multiple files, supply a comma-separated list of file names. (Wildcards are not supported.) For Google Cloud Storage files, you can optionally supply the output offiles.listdir()
directly to this function: