Class Storage

ACLs

Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share files with other users and allow other users to access your buckets and files.

To learn more about ACLs, read this overview on Access Control.

See Cloud Storage overview See Access Control

Inheritance

Service > Storage

Package

@google-cloud/storage

Constructors

(constructor)(options)

constructor(options?: StorageOptions);

Constructs the Storage client.

Parameter
NameDescription
options StorageOptions

Configuration options.

Examples

Create a client that uses Application Default Credentials (ADC)


const {Storage} = require('@google-cloud/storage');
const storage = new Storage();

Create a client with explicit credentials


const storage = new Storage({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Properties

acl

acl: typeof Storage.acl;

Reference to .

Storage#acl

acl

static acl: {
        OWNER_ROLE: string;
        READER_ROLE: string;
        WRITER_ROLE: string;
    };

Bucket

static Bucket: typeof Bucket;

Bucket class.

Storage.Bucket

Channel

static Channel: typeof Channel;

Channel class.

Storage.Channel

File

static File: typeof File;

File class.

Storage.File

HmacKey

static HmacKey: typeof HmacKey;

HmacKey class.

Storage.HmacKey

retryOptions

retryOptions: RetryOptions;

Methods

bucket(name, options)

bucket(name: string, options?: BucketOptions): Bucket;

Get a reference to a Cloud Storage bucket.

Parameters
NameDescription
name string

Name of the bucket.

options BucketOptions

Configuration object.

Returns
TypeDescription
Bucket

{Bucket}

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const albums = storage.bucket('albums');
const photos = storage.bucket('photos');

channel(id, resourceId)

channel(id: string, resourceId: string): Channel;

Reference a channel to receive notifications about changes to your bucket.

Parameters
NameDescription
id string

The ID of the channel.

resourceId string

The resource ID of the channel.

Returns
TypeDescription
Channel

{Channel}

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const channel = storage.channel('id', 'resource-id');

createBucket(name, metadata)

createBucket(name: string, metadata?: CreateBucketRequest): Promise<CreateBucketResponse>;
Parameters
NameDescription
name string
metadata CreateBucketRequest
Returns
TypeDescription
Promise<CreateBucketResponse>

createBucket(name, callback)

createBucket(name: string, callback: BucketCallback): void;
Parameters
NameDescription
name string
callback BucketCallback
Returns
TypeDescription
void

createBucket(name, metadata, callback)

createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Parameters
NameDescription
name string
metadata CreateBucketRequest
callback BucketCallback
Returns
TypeDescription
void

createBucket(name, metadata, callback)

createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Parameters
NameDescription
name string
metadata CreateBucketRequest
callback BucketCallback
Returns
TypeDescription
void

createHmacKey(serviceAccountEmail, options)

createHmacKey(serviceAccountEmail: string, options?: CreateHmacKeyOptions): Promise<CreateHmacKeyResponse>;
Parameters
NameDescription
serviceAccountEmail string
options CreateHmacKeyOptions
Returns
TypeDescription
Promise<CreateHmacKeyResponse>

createHmacKey(serviceAccountEmail, callback)

createHmacKey(serviceAccountEmail: string, callback: CreateHmacKeyCallback): void;
Parameters
NameDescription
serviceAccountEmail string
callback CreateHmacKeyCallback
Returns
TypeDescription
void

createHmacKey(serviceAccountEmail, options, callback)

createHmacKey(serviceAccountEmail: string, options: CreateHmacKeyOptions, callback: CreateHmacKeyCallback): void;
Parameters
NameDescription
serviceAccountEmail string
options CreateHmacKeyOptions
callback CreateHmacKeyCallback
Returns
TypeDescription
void

getBuckets(options)

getBuckets(options?: GetBucketsRequest): Promise<GetBucketsResponse>;
Parameter
NameDescription
options GetBucketsRequest
Returns
TypeDescription
Promise<GetBucketsResponse>

getBuckets(options, callback)

getBuckets(options: GetBucketsRequest, callback: GetBucketsCallback): void;
Parameters
NameDescription
options GetBucketsRequest
callback GetBucketsCallback
Returns
TypeDescription
void

getBuckets(callback)

getBuckets(callback: GetBucketsCallback): void;
Parameter
NameDescription
callback GetBucketsCallback
Returns
TypeDescription
void

getBucketsStream()

getBucketsStream(): Readable;
Returns
TypeDescription
Readable

getHmacKeys(options)

getHmacKeys(options?: GetHmacKeysOptions): Promise<GetHmacKeysResponse>;

Retrieves a list of HMAC keys matching the criteria.

The authenticated user must have storage.hmacKeys.list permission for the project in which the key exists.

Parameter
NameDescription
options GetHmacKeysOptions

Configuration options.

Returns
TypeDescription
Promise<GetHmacKeysResponse>
Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
storage.getHmacKeys(function(err, hmacKeys) {
  if (!err) {
    // hmacKeys is an array of HmacKey objects.
  }
});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
const callback = function(err, hmacKeys, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    storage.getHmacKeys(nextQuery, callback);
  }

  // The `metadata` property is populated for you with the metadata at the
  // time of fetching.
  hmacKeys[0].metadata;
};

storage.getHmacKeys({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
storage.getHmacKeys().then(function(data) {
  const hmacKeys = data[0];
});

getHmacKeys(callback)

getHmacKeys(callback: GetHmacKeysCallback): void;
Parameter
NameDescription
callback GetHmacKeysCallback
Returns
TypeDescription
void

getHmacKeys(options, callback)

getHmacKeys(options: GetHmacKeysOptions, callback: GetHmacKeysCallback): void;
Parameters
NameDescription
options GetHmacKeysOptions
callback GetHmacKeysCallback
Returns
TypeDescription
void

getHmacKeysStream()

getHmacKeysStream(): Readable;
Returns
TypeDescription
Readable

getServiceAccount(options)

getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
Parameter
NameDescription
options GetServiceAccountOptions
Returns
TypeDescription
Promise<GetServiceAccountResponse>

getServiceAccount(options)

getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
Parameter
NameDescription
options GetServiceAccountOptions
Returns
TypeDescription
Promise<GetServiceAccountResponse>

getServiceAccount(options, callback)

getServiceAccount(options: GetServiceAccountOptions, callback: GetServiceAccountCallback): void;
Parameters
NameDescription
options GetServiceAccountOptions
callback GetServiceAccountCallback
Returns
TypeDescription
void

getServiceAccount(callback)

getServiceAccount(callback: GetServiceAccountCallback): void;
Parameter
NameDescription
callback GetServiceAccountCallback
Returns
TypeDescription
void

hmacKey(accessId, options)

hmacKey(accessId: string, options?: HmacKeyOptions): HmacKey;

Get a reference to an HmacKey object. Note: this does not fetch the HMAC key's metadata. Use HmacKey#get() to retrieve and populate the metadata.

To get a reference to an HMAC key that's not created for a service account in the same project used to instantiate the Storage client, supply the project's ID as projectId in the options argument.

Parameters
NameDescription
accessId string

The HMAC key's access ID.

options HmacKeyOptions

HmacKey constructor owptions.

Returns
TypeDescription
HmacKey

{HmacKey}

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const hmacKey = storage.hmacKey('ACCESS_ID');