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.
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'
});
Create a client with credentials passed by value as a JavaScript object
const storage = new Storage({
projectId: 'your-project-id',
credentials: {
type: 'service_account',
project_id: 'xxxxxxx',
private_key_id: 'xxxx',
private_key:'-----BEGIN PRIVATE KEY-----xxxxxxx\n-----END PRIVATE KEY-----\n',
client_email: 'xxxx',
client_id: 'xxx',
auth_uri: 'https://accounts.google.com/o/oauth2/auth',
token_uri: 'https://oauth2.googleapis.com/token',
auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
client_x509_cert_url: 'xxx',
}
});
Create a client with credentials passed by loading a JSON file directly from disk
const storage = new Storage({
projectId: 'your-project-id',
credentials: require('/path/to-keyfile.json')
});
Create a client with an AuthClient
(e.g. DownscopedClient
)
const {DownscopedClient} = require('google-auth-library');
const authClient = new DownscopedClient({...});
const storage = new Storage({authClient});
Additional samples: - https://github.com/googleapis/google-auth-library-nodejs#sample-usage-1 - https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js
Properties
acl
Reference to .
Storage#acl
acl
static acl: {
OWNER_ROLE: string;
READER_ROLE: string;
WRITER_ROLE: string;
};
Bucket
static Bucket: typeof Bucket;
Channel
static Channel: typeof Channel;
crc32cGenerator
crc32cGenerator: CRC32CValidatorGenerator;
File
static File: typeof File;
HmacKey
static HmacKey: typeof HmacKey;
retryOptions
retryOptions: RetryOptions;
Methods
bucket(name, options)
bucket(name: string, options?: BucketOptions): Bucket;
Get a reference to a Cloud Storage bucket.
Parameters |
---|
Name | Description |
name |
string
Name of the bucket.
|
options |
BucketOptions
Configuration object.
|
Returns |
---|
Type | Description |
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 |
---|
Name | Description |
id |
string
The ID of the channel.
|
resourceId |
string
The resource ID of the channel.
|
Returns |
---|
Type | Description |
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>;
createBucket(name, callback)
createBucket(name: string, callback: BucketCallback): void;
Returns |
---|
Type | Description |
void | |
createBucket(name, metadata, callback)
createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Returns |
---|
Type | Description |
void | |
createBucket(name, metadata, callback)
createBucket(name: string, metadata: CreateBucketRequest, callback: BucketCallback): void;
Returns |
---|
Type | Description |
void | |
createHmacKey(serviceAccountEmail, options)
createHmacKey(serviceAccountEmail: string, options?: CreateHmacKeyOptions): Promise<CreateHmacKeyResponse>;
createHmacKey(serviceAccountEmail, callback)
createHmacKey(serviceAccountEmail: string, callback: CreateHmacKeyCallback): void;
Returns |
---|
Type | Description |
void | |
createHmacKey(serviceAccountEmail, options, callback)
createHmacKey(serviceAccountEmail: string, options: CreateHmacKeyOptions, callback: CreateHmacKeyCallback): void;
Returns |
---|
Type | Description |
void | |
getBuckets(options)
getBuckets(options?: GetBucketsRequest): Promise<GetBucketsResponse>;
getBuckets(options, callback)
getBuckets(options: GetBucketsRequest, callback: GetBucketsCallback): void;
Returns |
---|
Type | Description |
void | |
getBuckets(callback)
getBuckets(callback: GetBucketsCallback): void;
Returns |
---|
Type | Description |
void | |
getBucketsStream()
getBucketsStream(): Readable;
Returns |
---|
Type | Description |
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.
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;
Returns |
---|
Type | Description |
void | |
getHmacKeys(options, callback)
getHmacKeys(options: GetHmacKeysOptions, callback: GetHmacKeysCallback): void;
Returns |
---|
Type | Description |
void | |
getHmacKeysStream()
getHmacKeysStream(): Readable;
Returns |
---|
Type | Description |
Readable | |
getServiceAccount(options)
getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
getServiceAccount(options)
getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>;
getServiceAccount(options, callback)
getServiceAccount(options: GetServiceAccountOptions, callback: GetServiceAccountCallback): void;
Returns |
---|
Type | Description |
void | |
getServiceAccount(callback)
getServiceAccount(callback: GetServiceAccountCallback): void;
Returns |
---|
Type | Description |
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 |
---|
Name | Description |
accessId |
string
The HMAC key's access ID.
|
options |
HmacKeyOptions
HmacKey constructor options.
|
Returns |
---|
Type | Description |
HmacKey | {HmacKey}
|
Example
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const hmacKey = storage.hmacKey('ACCESS_ID');