feat(bigquery): Add cloud-client samples for access policies

bigquery/cloud-client/grantAccessToDataset.js

@@ -0,0 +1,113 @@
+// Copyright 2025 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.
+
+'use strict';
+
+/**
+ * Grants access to a BigQuery dataset for a specified entity
+ *
+ * @param {string} datasetId ID of the dataset to grant access to
+ * @param {string} entityId ID of the entity to grant access to
+ * @param {string} role Role to grant
+ * @returns {Promise<Array>} Array of access entries
+ */
+async function grantAccessToDataset(datasetId, entityId, role) {
+  // [START bigquery_grant_access_to_dataset]
+  const {BigQuery} = require('@google-cloud/bigquery');
+
+  // TODO(developer): Update and un-comment below lines
+
+  // ID of the dataset to revoke access to.
+  // datasetId = "my_project_id.my_dataset";
+
+  // ID of the user or group from whom you are adding access.
+  // Alternatively, the JSON REST API representation of the entity,
+  // such as a view's table reference.
+  // entityId = "[email protected]";
+
+  // One of the "Basic roles for datasets" described here:
+  // https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
+  // role = "READER";
+
+  // Type of entity you are granting access to.
+  // Find allowed allowed entity type names here:
+  // https://cloud.google.com/python/docs/reference/bigquery/latest/enums#class-googlecloudbigqueryenumsentitytypesvalue
+  // In this case, we're using the equivalent of GROUP_BY_EMAIL
+  const entityType = 'groupByEmail';
+
+  // Instantiate a client.
+  const client = new BigQuery();
+
+  try {
+    // Get a reference to the dataset.
+    const [dataset] = await client.dataset(datasetId).get();
+
+    // The 'access entries' list is immutable. Create a copy for modifications.
+    const entries = Array.isArray(dataset.metadata.access)
+      ? [...dataset.metadata.access]
+      : [];
+
+    // Append an AccessEntry to grant the role to a dataset.
+    // Find more details about the AccessEntry object in the BigQuery documentation
+    entries.push({
+      role: role,
+      [entityType]: entityId,
+    });
+
+    // Assign the list of AccessEntries back to the dataset.
+    const metadata = {
+      access: entries,
+    };
+
+    // Update will only succeed if the dataset
+    // has not been modified externally since retrieval.
+    //
+    // See the BigQuery client library documentation for more details on metadata updates
+
+    // Update just the 'access entries' property of the dataset.
+    const [updatedDataset] = await client
+      .dataset(datasetId)
+      .setMetadata(metadata);
+
+    // Show a success message.
+    const fullDatasetId =
+      updatedDataset &&
+      updatedDataset.metadata &&
+      updatedDataset.metadata.datasetReference
+        ? `${updatedDataset.metadata.datasetReference.projectId}.${updatedDataset.metadata.datasetReference.datasetId}`
+        : datasetId;
+
+    console.log(
+      `Role '${role}' granted for entity '${entityId}'` +
+        ` in dataset '${fullDatasetId}'.`
+    );
+
+    return updatedDataset.access;
+  } catch (error) {
+    if (error.code === 412) {
+      // A read-modify-write error (PreconditionFailed equivalent)
+      console.error(
+        `Dataset '${datasetId}' was modified remotely before this update. ` +
+          'Fetch the latest version and retry.'
+      );
+    } else {
+      throw error;
+    }
+  }
+  // [END bigquery_grant_access_to_dataset]
+}
+
+module.exports = {
+  grantAccessToDataset,
+};

bigquery/cloud-client/grantAccessToTableOrView.js

@@ -0,0 +1,81 @@
+// Copyright 2025 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.
+
+'use strict';
+
+const {BigQuery} = require('@google-cloud/bigquery');
+
+/**
+ * Grants access to a BigQuery table or view for a specified principal.
+ *
+ * @param {string} projectId - Google Cloud Platform project ID
+ * @param {string} datasetId - Dataset where the table or view is
+ * @param {string} resourceName - Table or view name to get the access policy
+ * @param {string} principalId - The principal requesting access to the table or view
+ * @param {string} role - Role to assign to the member
+ * @returns {Promise<object[]>} The updated policy bindings
+ */
+async function grantAccessToTableOrView({
+  projectId,
+  datasetId,
+  resourceName,
+  principalId,
+  role,
+}) {
+  // [START bigquery_grant_access_to_table_or_view]
+  // Uncomment and update these variables:
+  // const projectId = 'my_project_id';
+  // const datasetId = 'my_dataset';
+  // const resourceName = 'my_table';
+  // const principalId = 'user:[email protected]';
+  // const role = 'roles/bigquery.dataViewer';
+
+  // Create a BigQuery client
+  const bigquery = new BigQuery();
+
+  // Get the dataset and table references
+  const dataset = bigquery.dataset(datasetId);
+  const table = dataset.table(resourceName);
+
+  try {
+    // Get the IAM access policy for the table or view
+    const [policy] = await table.iam.getPolicy();
+
+    // Create a new binding for the principal and role
+    const binding = {
+      role: role,
+      members: [principalId],
+    };
+
+    // Add the new binding to the policy
+    policy.bindings.push(binding);
+
+    // Set the updated IAM access policy
+    const [updatedPolicy] = await table.iam.setPolicy(policy);
+
+    console.log(
+      `Role '${role}' granted for principal '${principalId}' on resource '${projectId}.${datasetId}.${resourceName}'.`
+    );
+
+    return updatedPolicy.bindings;
+  } catch (error) {
+    console.error('Error granting access:', error);
+    throw error;
+  }
+  // [END bigquery_grant_access_to_table_or_view]
+}
+
+module.exports = {
+  grantAccessToTableOrView,
+};

bigquery/cloud-client/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "bigquery-cloud-client",
+    "description": "Big Query Cloud Client Node.js for Google App",
+    "version": "0.0.1",
+    "private": true,
+    "license": "Apache Version 2.0",
+    "author": "Google Inc.",
+    "engines": {
+        "node": "20.x"
+    },
+    "scripts": {
+        "deploy": "gcloud app deploy",
+        "start": "node app.js",
+        "unit-test": "c8 mocha -p -j 2 test/ --timeout=10000 --exit",
+        "test": "npm run unit-test"
+    },
+    "dependencies": {
+        "@google-cloud/bigquery": "7.9.2"
+    },
+    "devDependencies": {
+        "c8": "^10.0.0",
+        "chai": "^4.5.0",
+        "mocha": "^10.0.0",
+        "sinon": "^18.0.0"
+    }
+}

bigquery/cloud-client/revokeDatasetAccess.js

@@ -0,0 +1,110 @@
+// Copyright 2025 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
+//
+//     https://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.
+
+'use strict';
+
+const {BigQuery} = require('@google-cloud/bigquery');
+
+// [START bigquery_revoke_dataset_access]
+/**
+ * Revokes access to a dataset for a specified entity.
+ *
+ * @param {string} datasetId - ID of the dataset to revoke access to.
+ * @param {string} entityId - ID of the user or group from whom you are revoking access.
+ *                            Alternatively, the JSON REST API representation of the entity,
+ *                            such as a view's table reference.
+ * @returns {Promise<Array>} A promise that resolves to the updated access entries
+ */
+async function revokeDatasetAccess(datasetId, entityId) {
+  // Import the Google Cloud client library.
+  const bigquery = new BigQuery();
+
+  // TODO (developer): Update and un-comment below lines
+
+  // ID of the dataset to revoke access to.
+  // datasetId = "your-project.your_dataset"
+
+  // ID of the user or group from whom you are revoking access.
+  // Alternatively, the JSON REST API representation of the entity,
+  // such as a view's table reference.
+  // entityId = "[email protected]"
+
+  // Get a reference to the dataset.
+  const [dataset] = await bigquery.dataset(datasetId).get();
+
+  // To revoke access to a dataset, remove elements from the access list.
+  //
+  // See the BigQuery client library documentation for more details on access entries
+
+  // Filter access entries to exclude entries matching the specified entity_id
+  // and assign a new list back to the access list.
+  dataset.metadata.access = dataset.metadata.access.filter(entry => {
+    // Check for entity_id (specific match)
+    if (entry.entity_id === entityId) {
+      console.log(
+        `Found matching entity_id: ${entry.entity_id}, removing entry`
+      );
+      return false;
+    }
+
+    // Check for userByEmail field
+    if (entry.userByEmail === entityId) {
+      console.log(
+        `Found matching userByEmail: ${entry.userByEmail}, removing entry`
+      );
+      return false;
+    }
+
+    // Check for groupByEmail field
+    if (entry.groupByEmail === entityId) {
+      console.log(
+        `Found matching groupByEmail: ${entry.groupByEmail}, removing entry`
+      );
+      return false;
+    }
+
+    // Keep all other entries
+    return true;
+  });
+
+  // Update will only succeed if the dataset
+  // has not been modified externally since retrieval.
+
+  try {
+    // Update just the access entries property of the dataset.
+    const [updatedDataset] = await dataset.setMetadata(dataset.metadata);
+
+    const fullDatasetId = `${dataset.parent.projectId}.${dataset.id}`;
+    console.log(
+      `Revoked dataset access for '${entityId}' to dataset '${fullDatasetId}'.`
+    );
+
+    return updatedDataset.access;
+  } catch (error) {
+    // Check if it's a precondition failed error (a read-modify-write error)
+    if (error.code === 412) {
+      console.log(
+        `Dataset '${dataset.id}' was modified remotely before this update. ` +
+          'Fetch the latest version and retry.'
+      );
+    } else {
+      throw error;
+    }
+  }
+}
+// [END bigquery_revoke_dataset_access]
+
+module.exports = {
+  revokeDatasetAccess,
+};