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 > StoragePackage
@google-cloud/storageConstructors
(constructor)(options)
constructor
(
options
?:
StorageOptions
);
Constructs the Storage client.
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
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
crc32cGenerator
crc32cGenerator
:
CRC32CValidatorGenerator
;
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
Name
Description
name
string
Name of the bucket.
options
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.
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
;
Parameters
Name
Description
serviceAccountEmail
string
options
callback
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.
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.
const
{
Storage
}
=
require
(
' @google-cloud/storage
'
);
const
storage
=
new
Storage
();
const
hmacKey
=
storage
.
hmacKey
(
'ACCESS_ID'
);
