You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
719 lines
26 KiB
719 lines
26 KiB
2 years ago
|
"use strict";
|
||
|
|
// Copyright 2019 Google LLC
|
||
|
|
//
|
||
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
// you may not use this file except in compliance with the License.
|
||
|
|
// You may obtain a copy of the License at
|
||
|
|
//
|
||
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
//
|
||
|
|
// Unless required by applicable law or agreed to in writing, software
|
||
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
// See the License for the specific language governing permissions and
|
||
|
|
// limitations under the License.
|
||
|
|
Object.defineProperty(exports, "__esModule", { value: true });
|
||
|
|
exports.AclRoleAccessorMethods = exports.Acl = void 0;
|
||
|
|
const promisify_1 = require("@google-cloud/promisify");
|
||
|
|
/**
|
||
|
|
* Attach functionality to a {@link Storage.acl} instance. This will add an
|
||
|
|
* object for each role group (owners, readers, and writers), with each object
|
||
|
|
* containing methods to add or delete a type of entity.
|
||
|
|
*
|
||
|
|
* As an example, here are a few methods that are created.
|
||
|
|
*
|
||
|
|
* myBucket.acl.readers.deleteGroup('groupId', function(err) {});
|
||
|
|
*
|
||
|
|
* myBucket.acl.owners.addUser('email@example.com', function(err, acl) {});
|
||
|
|
*
|
||
|
|
* myBucket.acl.writers.addDomain('example.com', function(err, acl) {});
|
||
|
|
*
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
class AclRoleAccessorMethods {
|
||
|
|
constructor() {
|
||
|
|
this.owners = {};
|
||
|
|
this.readers = {};
|
||
|
|
this.writers = {};
|
||
|
|
/**
|
||
|
|
* An object of convenience methods to add or delete owner ACL permissions
|
||
|
|
* for a given entity.
|
||
|
|
*
|
||
|
|
* The supported methods include:
|
||
|
|
*
|
||
|
|
* - `myFile.acl.owners.addAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.owners.deleteAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.owners.addAllUsers`
|
||
|
|
* - `myFile.acl.owners.deleteAllUsers`
|
||
|
|
* - `myFile.acl.owners.addDomain`
|
||
|
|
* - `myFile.acl.owners.deleteDomain`
|
||
|
|
* - `myFile.acl.owners.addGroup`
|
||
|
|
* - `myFile.acl.owners.deleteGroup`
|
||
|
|
* - `myFile.acl.owners.addProject`
|
||
|
|
* - `myFile.acl.owners.deleteProject`
|
||
|
|
* - `myFile.acl.owners.addUser`
|
||
|
|
* - `myFile.acl.owners.deleteUser`
|
||
|
|
*
|
||
|
|
* @name Acl#owners
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // Add a user as an owner of a file.
|
||
|
|
* //-
|
||
|
|
* const myBucket = gcs.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
* myFile.acl.owners.addUser('email@example.com', function(err, aclObject)
|
||
|
|
* {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For reference, the above command is the same as running the following.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.add({
|
||
|
|
* entity: 'user-email@example.com',
|
||
|
|
* role: gcs.acl.OWNER_ROLE
|
||
|
|
* }, function(err, aclObject) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.owners.addUser('email@example.com').then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
* ```
|
||
|
|
*/
|
||
|
|
this.owners = {};
|
||
|
|
/**
|
||
|
|
* An object of convenience methods to add or delete reader ACL permissions
|
||
|
|
* for a given entity.
|
||
|
|
*
|
||
|
|
* The supported methods include:
|
||
|
|
*
|
||
|
|
* - `myFile.acl.readers.addAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.readers.deleteAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.readers.addAllUsers`
|
||
|
|
* - `myFile.acl.readers.deleteAllUsers`
|
||
|
|
* - `myFile.acl.readers.addDomain`
|
||
|
|
* - `myFile.acl.readers.deleteDomain`
|
||
|
|
* - `myFile.acl.readers.addGroup`
|
||
|
|
* - `myFile.acl.readers.deleteGroup`
|
||
|
|
* - `myFile.acl.readers.addProject`
|
||
|
|
* - `myFile.acl.readers.deleteProject`
|
||
|
|
* - `myFile.acl.readers.addUser`
|
||
|
|
* - `myFile.acl.readers.deleteUser`
|
||
|
|
*
|
||
|
|
* @name Acl#readers
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // Add a user as a reader of a file.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.readers.addUser('email@example.com', function(err, aclObject)
|
||
|
|
* {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For reference, the above command is the same as running the following.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.add({
|
||
|
|
* entity: 'user-email@example.com',
|
||
|
|
* role: gcs.acl.READER_ROLE
|
||
|
|
* }, function(err, aclObject) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.readers.addUser('email@example.com').then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
* ```
|
||
|
|
*/
|
||
|
|
this.readers = {};
|
||
|
|
/**
|
||
|
|
* An object of convenience methods to add or delete writer ACL permissions
|
||
|
|
* for a given entity.
|
||
|
|
*
|
||
|
|
* The supported methods include:
|
||
|
|
*
|
||
|
|
* - `myFile.acl.writers.addAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.writers.deleteAllAuthenticatedUsers`
|
||
|
|
* - `myFile.acl.writers.addAllUsers`
|
||
|
|
* - `myFile.acl.writers.deleteAllUsers`
|
||
|
|
* - `myFile.acl.writers.addDomain`
|
||
|
|
* - `myFile.acl.writers.deleteDomain`
|
||
|
|
* - `myFile.acl.writers.addGroup`
|
||
|
|
* - `myFile.acl.writers.deleteGroup`
|
||
|
|
* - `myFile.acl.writers.addProject`
|
||
|
|
* - `myFile.acl.writers.deleteProject`
|
||
|
|
* - `myFile.acl.writers.addUser`
|
||
|
|
* - `myFile.acl.writers.deleteUser`
|
||
|
|
*
|
||
|
|
* @name Acl#writers
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // Add a user as a writer of a file.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.writers.addUser('email@example.com', function(err, aclObject)
|
||
|
|
* {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For reference, the above command is the same as running the following.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.add({
|
||
|
|
* entity: 'user-email@example.com',
|
||
|
|
* role: gcs.acl.WRITER_ROLE
|
||
|
|
* }, function(err, aclObject) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.writers.addUser('email@example.com').then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
* ```
|
||
|
|
*/
|
||
|
|
this.writers = {};
|
||
|
|
AclRoleAccessorMethods.roles.forEach(this._assignAccessMethods.bind(this));
|
||
|
|
}
|
||
|
|
_assignAccessMethods(role) {
|
||
|
|
const accessMethods = AclRoleAccessorMethods.accessMethods;
|
||
|
|
const entities = AclRoleAccessorMethods.entities;
|
||
|
|
const roleGroup = role.toLowerCase() + 's';
|
||
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||
|
|
this[roleGroup] = entities.reduce((acc, entity) => {
|
||
|
|
const isPrefix = entity.charAt(entity.length - 1) === '-';
|
||
|
|
accessMethods.forEach(accessMethod => {
|
||
|
|
let method = accessMethod + entity[0].toUpperCase() + entity.substring(1);
|
||
|
|
if (isPrefix) {
|
||
|
|
method = method.replace('-', '');
|
||
|
|
}
|
||
|
|
// Wrap the parent accessor method (e.g. `add` or `delete`) to avoid the
|
||
|
|
// more complex API of specifying an `entity` and `role`.
|
||
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||
|
|
acc[method] = (entityId, options, callback) => {
|
||
|
|
let apiEntity;
|
||
|
|
if (typeof options === 'function') {
|
||
|
|
callback = options;
|
||
|
|
options = {};
|
||
|
|
}
|
||
|
|
if (isPrefix) {
|
||
|
|
apiEntity = entity + entityId;
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
// If the entity is not a prefix, it is a special entity group
|
||
|
|
// that does not require further details. The accessor methods
|
||
|
|
// only accept a callback.
|
||
|
|
apiEntity = entity;
|
||
|
|
callback = entityId;
|
||
|
|
}
|
||
|
|
options = Object.assign({
|
||
|
|
entity: apiEntity,
|
||
|
|
role,
|
||
|
|
}, options);
|
||
|
|
const args = [options];
|
||
|
|
if (typeof callback === 'function') {
|
||
|
|
args.push(callback);
|
||
|
|
}
|
||
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||
|
|
return this[accessMethod].apply(this, args);
|
||
|
|
};
|
||
|
|
});
|
||
|
|
return acc;
|
||
|
|
}, {});
|
||
|
|
}
|
||
|
|
}
|
||
|
|
exports.AclRoleAccessorMethods = AclRoleAccessorMethods;
|
||
|
|
AclRoleAccessorMethods.accessMethods = ['add', 'delete'];
|
||
|
|
AclRoleAccessorMethods.entities = [
|
||
|
|
// Special entity groups that do not require further specification.
|
||
|
|
'allAuthenticatedUsers',
|
||
|
|
'allUsers',
|
||
|
|
// Entity groups that require specification, e.g. `user-email@example.com`.
|
||
|
|
'domain-',
|
||
|
|
'group-',
|
||
|
|
'project-',
|
||
|
|
'user-',
|
||
|
|
];
|
||
|
|
AclRoleAccessorMethods.roles = ['OWNER', 'READER', 'WRITER'];
|
||
|
|
/**
|
||
|
|
* Cloud Storage uses access control lists (ACLs) to manage object and
|
||
|
|
* bucket access. ACLs are the mechanism you use to share objects with other
|
||
|
|
* users and allow other users to access your buckets and objects.
|
||
|
|
*
|
||
|
|
* An ACL consists of one or more entries, where each entry grants permissions
|
||
|
|
* to an entity. Permissions define the actions that can be performed against an
|
||
|
|
* object or bucket (for example, `READ` or `WRITE`); the entity defines who the
|
||
|
|
* permission applies to (for example, a specific user or group of users).
|
||
|
|
*
|
||
|
|
* Where an `entity` value is accepted, we follow the format the Cloud Storage
|
||
|
|
* API expects.
|
||
|
|
*
|
||
|
|
* Refer to
|
||
|
|
* https://cloud.google.com/storage/docs/json_api/v1/defaultObjectAccessControls
|
||
|
|
* for the most up-to-date values.
|
||
|
|
*
|
||
|
|
* - `user-userId`
|
||
|
|
* - `user-email`
|
||
|
|
* - `group-groupId`
|
||
|
|
* - `group-email`
|
||
|
|
* - `domain-domain`
|
||
|
|
* - `project-team-projectId`
|
||
|
|
* - `allUsers`
|
||
|
|
* - `allAuthenticatedUsers`
|
||
|
|
*
|
||
|
|
* Examples:
|
||
|
|
*
|
||
|
|
* - The user "liz@example.com" would be `user-liz@example.com`.
|
||
|
|
* - The group "example@googlegroups.com" would be
|
||
|
|
* `group-example@googlegroups.com`.
|
||
|
|
* - To refer to all members of the Google Apps for Business domain
|
||
|
|
* "example.com", the entity would be `domain-example.com`.
|
||
|
|
*
|
||
|
|
* For more detailed information, see
|
||
|
|
* {@link http://goo.gl/6qBBPO| About Access Control Lists}.
|
||
|
|
*
|
||
|
|
* @constructor Acl
|
||
|
|
* @mixin
|
||
|
|
* @param {object} options Configuration options.
|
||
|
|
*/
|
||
|
|
class Acl extends AclRoleAccessorMethods {
|
||
|
|
constructor(options) {
|
||
|
|
super();
|
||
|
|
this.pathPrefix = options.pathPrefix;
|
||
|
|
this.request_ = options.request;
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @typedef {array} AddAclResponse
|
||
|
|
* @property {object} 0 The Acl Objects.
|
||
|
|
* @property {object} 1 The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* @callback AddAclCallback
|
||
|
|
* @param {?Error} err Request error, if any.
|
||
|
|
* @param {object} acl The Acl Objects.
|
||
|
|
* @param {object} apiResponse The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* Add access controls on a {@link Bucket} or {@link File}.
|
||
|
|
*
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/insert| BucketAccessControls: insert API Documentation}
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls/insert| ObjectAccessControls: insert API Documentation}
|
||
|
|
*
|
||
|
|
* @param {object} options Configuration options.
|
||
|
|
* @param {string} options.entity Whose permissions will be added.
|
||
|
|
* @param {string} options.role Permissions allowed for the defined entity.
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/access-control Access
|
||
|
|
* Control}.
|
||
|
|
* @param {number} [options.generation] **File Objects Only** Select a specific
|
||
|
|
* revision of this file (as opposed to the latest version, the default).
|
||
|
|
* @param {string} [options.userProject] The ID of the project which will be
|
||
|
|
* billed for the request.
|
||
|
|
* @param {AddAclCallback} [callback] Callback function.
|
||
|
|
* @returns {Promise<AddAclResponse>}
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* const options = {
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* role: gcs.acl.OWNER_ROLE
|
||
|
|
* };
|
||
|
|
*
|
||
|
|
* myBucket.acl.add(options, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For file ACL operations, you can also specify a `generation` property.
|
||
|
|
* // Here is how you would grant ownership permissions to a user on a
|
||
|
|
* specific
|
||
|
|
* // revision of a file.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.add({
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* role: gcs.acl.OWNER_ROLE,
|
||
|
|
* generation: 1
|
||
|
|
* }, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myBucket.acl.add(options).then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* ```
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_add_file_owner
|
||
|
|
* Example of adding an owner to a file:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_add_bucket_owner
|
||
|
|
* Example of adding an owner to a bucket:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_add_bucket_default_owner
|
||
|
|
* Example of adding a default owner to a bucket:
|
||
|
|
*/
|
||
|
|
add(options, callback) {
|
||
|
|
const query = {};
|
||
|
|
if (options.generation) {
|
||
|
|
query.generation = options.generation;
|
||
|
|
}
|
||
|
|
if (options.userProject) {
|
||
|
|
query.userProject = options.userProject;
|
||
|
|
}
|
||
|
|
this.request({
|
||
|
|
method: 'POST',
|
||
|
|
uri: '',
|
||
|
|
qs: query,
|
||
|
|
maxRetries: 0,
|
||
|
|
json: {
|
||
|
|
entity: options.entity,
|
||
|
|
role: options.role.toUpperCase(),
|
||
|
|
},
|
||
|
|
}, (err, resp) => {
|
||
|
|
if (err) {
|
||
|
|
callback(err, null, resp);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
callback(null, this.makeAclObject_(resp), resp);
|
||
|
|
});
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @typedef {array} RemoveAclResponse
|
||
|
|
* @property {object} 0 The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* @callback RemoveAclCallback
|
||
|
|
* @param {?Error} err Request error, if any.
|
||
|
|
* @param {object} apiResponse The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* Delete access controls on a {@link Bucket} or {@link File}.
|
||
|
|
*
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/delete| BucketAccessControls: delete API Documentation}
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls/delete| ObjectAccessControls: delete API Documentation}
|
||
|
|
*
|
||
|
|
* @param {object} options Configuration object.
|
||
|
|
* @param {string} options.entity Whose permissions will be revoked.
|
||
|
|
* @param {int} [options.generation] **File Objects Only** Select a specific
|
||
|
|
* revision of this file (as opposed to the latest version, the default).
|
||
|
|
* @param {string} [options.userProject] The ID of the project which will be
|
||
|
|
* billed for the request.
|
||
|
|
* @param {RemoveAclCallback} callback The callback function.
|
||
|
|
* @returns {Promise<RemoveAclResponse>}
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* myBucket.acl.delete({
|
||
|
|
* entity: 'user-useremail@example.com'
|
||
|
|
* }, function(err, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For file ACL operations, you can also specify a `generation` property.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.delete({
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* generation: 1
|
||
|
|
* }, function(err, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.delete().then(function(data) {
|
||
|
|
* const apiResponse = data[0];
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* ```
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_remove_bucket_owner
|
||
|
|
* Example of removing an owner from a bucket:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_remove_bucket_default_owner
|
||
|
|
* Example of removing a default owner from a bucket:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_remove_file_owner
|
||
|
|
* Example of removing an owner from a bucket:
|
||
|
|
*/
|
||
|
|
delete(options, callback) {
|
||
|
|
const query = {};
|
||
|
|
if (options.generation) {
|
||
|
|
query.generation = options.generation;
|
||
|
|
}
|
||
|
|
if (options.userProject) {
|
||
|
|
query.userProject = options.userProject;
|
||
|
|
}
|
||
|
|
this.request({
|
||
|
|
method: 'DELETE',
|
||
|
|
uri: '/' + encodeURIComponent(options.entity),
|
||
|
|
qs: query,
|
||
|
|
}, (err, resp) => {
|
||
|
|
callback(err, resp);
|
||
|
|
});
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @typedef {array} GetAclResponse
|
||
|
|
* @property {object|object[]} 0 Single or array of Acl Objects.
|
||
|
|
* @property {object} 1 The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* @callback GetAclCallback
|
||
|
|
* @param {?Error} err Request error, if any.
|
||
|
|
* @param {object|object[]} acl Single or array of Acl Objects.
|
||
|
|
* @param {object} apiResponse The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* Get access controls on a {@link Bucket} or {@link File}. If
|
||
|
|
* an entity is omitted, you will receive an array of all applicable access
|
||
|
|
* controls.
|
||
|
|
*
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/get| BucketAccessControls: get API Documentation}
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls/get| ObjectAccessControls: get API Documentation}
|
||
|
|
*
|
||
|
|
* @param {object|function} [options] Configuration options. If you want to
|
||
|
|
* receive a list of all access controls, pass the callback function as
|
||
|
|
* the only argument.
|
||
|
|
* @param {string} options.entity Whose permissions will be fetched.
|
||
|
|
* @param {number} [options.generation] **File Objects Only** Select a specific
|
||
|
|
* revision of this file (as opposed to the latest version, the default).
|
||
|
|
* @param {string} [options.userProject] The ID of the project which will be
|
||
|
|
* billed for the request.
|
||
|
|
* @param {GetAclCallback} [callback] Callback function.
|
||
|
|
* @returns {Promise<GetAclResponse>}
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* myBucket.acl.get({
|
||
|
|
* entity: 'user-useremail@example.com'
|
||
|
|
* }, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // Get all access controls.
|
||
|
|
* //-
|
||
|
|
* myBucket.acl.get(function(err, aclObjects, apiResponse) {
|
||
|
|
* // aclObjects = [
|
||
|
|
* // {
|
||
|
|
* // entity: 'user-useremail@example.com',
|
||
|
|
* // role: 'owner'
|
||
|
|
* // }
|
||
|
|
* // ]
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For file ACL operations, you can also specify a `generation` property.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.get({
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* generation: 1
|
||
|
|
* }, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myBucket.acl.get().then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* ```
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_print_file_acl
|
||
|
|
* Example of printing a file's ACL:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_print_file_acl_for_user
|
||
|
|
* Example of printing a file's ACL for a specific user:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_print_bucket_acl
|
||
|
|
* Example of printing a bucket's ACL:
|
||
|
|
*
|
||
|
|
* @example <caption>include:samples/acl.js</caption>
|
||
|
|
* region_tag:storage_print_bucket_acl_for_user
|
||
|
|
* Example of printing a bucket's ACL for a specific user:
|
||
|
|
*/
|
||
|
|
get(optionsOrCallback, cb) {
|
||
|
|
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : null;
|
||
|
|
const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : cb;
|
||
|
|
let path = '';
|
||
|
|
const query = {};
|
||
|
|
if (options) {
|
||
|
|
path = '/' + encodeURIComponent(options.entity);
|
||
|
|
if (options.generation) {
|
||
|
|
query.generation = options.generation;
|
||
|
|
}
|
||
|
|
if (options.userProject) {
|
||
|
|
query.userProject = options.userProject;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
this.request({
|
||
|
|
uri: path,
|
||
|
|
qs: query,
|
||
|
|
}, (err, resp) => {
|
||
|
|
if (err) {
|
||
|
|
callback(err, null, resp);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
let results;
|
||
|
|
if (resp.items) {
|
||
|
|
results = resp.items.map(this.makeAclObject_);
|
||
|
|
}
|
||
|
|
else {
|
||
|
|
results = this.makeAclObject_(resp);
|
||
|
|
}
|
||
|
|
callback(null, results, resp);
|
||
|
|
});
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* @typedef {array} UpdateAclResponse
|
||
|
|
* @property {object} 0 The updated Acl Objects.
|
||
|
|
* @property {object} 1 The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* @callback UpdateAclCallback
|
||
|
|
* @param {?Error} err Request error, if any.
|
||
|
|
* @param {object} acl The updated Acl Objects.
|
||
|
|
* @param {object} apiResponse The full API response.
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* Update access controls on a {@link Bucket} or {@link File}.
|
||
|
|
*
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/update| BucketAccessControls: update API Documentation}
|
||
|
|
* See {@link https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls/update| ObjectAccessControls: update API Documentation}
|
||
|
|
*
|
||
|
|
* @param {object} options Configuration options.
|
||
|
|
* @param {string} options.entity Whose permissions will be updated.
|
||
|
|
* @param {string} options.role Permissions allowed for the defined entity.
|
||
|
|
* See {@link Storage.acl}.
|
||
|
|
* @param {number} [options.generation] **File Objects Only** Select a specific
|
||
|
|
* revision of this file (as opposed to the latest version, the default).
|
||
|
|
* @param {string} [options.userProject] The ID of the project which will be
|
||
|
|
* billed for the request.
|
||
|
|
* @param {UpdateAclCallback} [callback] Callback function.
|
||
|
|
* @returns {Promise<UpdateAclResponse>}
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* ```
|
||
|
|
* const storage = require('@google-cloud/storage')();
|
||
|
|
* const myBucket = storage.bucket('my-bucket');
|
||
|
|
* const myFile = myBucket.file('my-file');
|
||
|
|
*
|
||
|
|
* const options = {
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* role: gcs.acl.WRITER_ROLE
|
||
|
|
* };
|
||
|
|
*
|
||
|
|
* myBucket.acl.update(options, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // For file ACL operations, you can also specify a `generation` property.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.update({
|
||
|
|
* entity: 'user-useremail@example.com',
|
||
|
|
* role: gcs.acl.WRITER_ROLE,
|
||
|
|
* generation: 1
|
||
|
|
* }, function(err, aclObject, apiResponse) {});
|
||
|
|
*
|
||
|
|
* //-
|
||
|
|
* // If the callback is omitted, we'll return a Promise.
|
||
|
|
* //-
|
||
|
|
* myFile.acl.update(options).then(function(data) {
|
||
|
|
* const aclObject = data[0];
|
||
|
|
* const apiResponse = data[1];
|
||
|
|
* });
|
||
|
|
* ```
|
||
|
|
*/
|
||
|
|
update(options, callback) {
|
||
|
|
const query = {};
|
||
|
|
if (options.generation) {
|
||
|
|
query.generation = options.generation;
|
||
|
|
}
|
||
|
|
if (options.userProject) {
|
||
|
|
query.userProject = options.userProject;
|
||
|
|
}
|
||
|
|
this.request({
|
||
|
|
method: 'PUT',
|
||
|
|
uri: '/' + encodeURIComponent(options.entity),
|
||
|
|
qs: query,
|
||
|
|
json: {
|
||
|
|
role: options.role.toUpperCase(),
|
||
|
|
},
|
||
|
|
}, (err, resp) => {
|
||
|
|
if (err) {
|
||
|
|
callback(err, null, resp);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
callback(null, this.makeAclObject_(resp), resp);
|
||
|
|
});
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* Transform API responses to a consistent object format.
|
||
|
|
*
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
makeAclObject_(accessControlObject) {
|
||
|
|
const obj = {
|
||
|
|
entity: accessControlObject.entity,
|
||
|
|
role: accessControlObject.role,
|
||
|
|
};
|
||
|
|
if (accessControlObject.projectTeam) {
|
||
|
|
obj.projectTeam = accessControlObject.projectTeam;
|
||
|
|
}
|
||
|
|
return obj;
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* Patch requests up to the bucket's request object.
|
||
|
|
*
|
||
|
|
* @private
|
||
|
|
*
|
||
|
|
* @param {string} method Action.
|
||
|
|
* @param {string} path Request path.
|
||
|
|
* @param {*} query Request query object.
|
||
|
|
* @param {*} body Request body contents.
|
||
|
|
* @param {function} callback Callback function.
|
||
|
|
*/
|
||
|
|
request(reqOpts, callback) {
|
||
|
|
reqOpts.uri = this.pathPrefix + reqOpts.uri;
|
||
|
|
this.request_(reqOpts, callback);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
exports.Acl = Acl;
|
||
|
|
/*! Developer Documentation
|
||
|
|
*
|
||
|
|
* All async methods (except for streams) will return a Promise in the event
|
||
|
|
* that a callback is omitted.
|
||
|
|
*/
|
||
|
|
(0, promisify_1.promisifyAll)(Acl, {
|
||
|
|
exclude: ['request'],
|
||
|
|
});
|
||
|
|
//# sourceMappingURL=acl.js.map
|