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

bigquery/cloud-client/grantAccessToDataset.js

@@ -14,61 +14,99 @@
 
 'use strict';
 
-const {BigQuery} = require('@google-cloud/bigquery');
-
 /**
  * Grants access to a BigQuery dataset for a specified entity
  *
- * @param {object} options The configuration object
- * @param {string} options.datasetId ID of the dataset to grant access to (e.g. "my_project_id.my_dataset")
- * @param {string} options.entityId ID of the user or group to grant access to (e.g. "user-or-group-to-add@example.com")
- * @param {string} options.role One of the basic roles for datasets (e.g. "READER")
+ * @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
  */
-// [START bigquery_grant_access_to_dataset]
-async function grantAccessToDataset(options) {
-  // Create a BigQuery client
-  const bigquery = new BigQuery();
+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 = "user-or-group-to-add@example.com";
+
+  // One of the "Basic roles for datasets" described here:
+  // https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
+  // role = "READER";
 
-  const {datasetId, entityId, role} = options;
+  // 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 = bigquery.dataset(datasetId);
-    const [metadata] = await dataset.getMetadata();
+    // 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 = [...(metadata.access || [])];
+    // The 'access entries' list is immutable. Create a copy for modifications.
+    const entries = Array.isArray(dataset.metadata.access)
+      ? [...dataset.metadata.access]
+      : [];
 
-    // Add the new access entry
+    // 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,
-      groupByEmail: entityId, // For group access. Use userByEmail for user access
+      [entityType]: entityId,
     });
 
-    // Update the dataset's access entries
-    const [updatedMetadata] = await dataset.setMetadata({
-      ...metadata,
+    // 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 '${datasetId}'.`
+      `Role '${role}' granted for entity '${entityId}'` +
+        ` in dataset '${fullDatasetId}'.`
     );
 
-    return updatedMetadata.access;
+    return updatedDataset.access;
   } catch (error) {
     if (error.code === 412) {
-      // 412 Precondition Failed - Dataset was modified between get and update
+      // 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;
     }
-    throw error;
   }
+  // [END bigquery_grant_access_to_dataset]
 }
-// [END bigquery_grant_access_to_dataset]
 
 module.exports = {
   grantAccessToDataset,

bigquery/cloud-client/revokeDatasetAccess.js

@@ -18,43 +18,89 @@ const {BigQuery} = require('@google-cloud/bigquery');
 
 // [START bigquery_revoke_dataset_access]
 /**
- * Revokes access to a BigQuery dataset for a specified entity.
+ * Revokes access to a dataset for a specified entity.
  *
- * @param {Object} params The parameters for revoking dataset access
- * @param {string} params.datasetId The ID of the dataset to revoke access from
- * @param {string} params.entityId The ID of the user or group to revoke access from
+ * @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}) {
-  // Instantiate a client
+async function revokeDatasetAccess(datasetId, entityId) {
+  // Import the Google Cloud client library.
   const bigquery = new BigQuery();
 
-  try {
-    // Get a reference to the dataset
-    const [dataset] = await bigquery.dataset(datasetId).get();
+  // TODO (developer): Update and un-comment below lines
 
-    // Filter out the access entry for the specified entity
-    dataset.metadata.access = dataset.metadata.access.filter(
-      entry => entry.userByEmail !== entityId && entry.groupByEmail !== entityId
-    );
+  // 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 = "user-or-group-to-remove@example.com"
+
+  // 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
 
-    // Update the dataset with the new 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 '${dataset.id}'.`
+      `Revoked dataset access for '${entityId}' to dataset '${fullDatasetId}'.`
     );
 
-    return updatedDataset.metadata.access;
+    return updatedDataset.access;
   } catch (error) {
+    // Check if it's a precondition failed error (a read-modify-write error)
     if (error.code === 412) {
-      // Handle precondition failed error (dataset modified externally)
-      console.error(
-        `Dataset '${datasetId}' was modified remotely before this update. ` +
+      console.log(
+        `Dataset '${dataset.id}' was modified remotely before this update. ` +
           'Fetch the latest version and retry.'
       );
+    } else {
+      throw error;
     }
-    throw error;
   }
 }
 // [END bigquery_revoke_dataset_access]