docs: add sample for revoking dataset access

samples/snippets/README.rst

@@ -1,4 +1,3 @@
-
 .. This file is automatically generated. Do not edit this file directly.
 
 Google BigQuery Python Samples
@@ -16,11 +15,14 @@ This directory contains samples for Google BigQuery. `Google BigQuery`_ is Googl
 .. _Google BigQuery: https://cloud.google.com/bigquery/docs
 
 
+To run the sample, you need to have the `BigQuery Admin` role.
+
+
+
 Setup
 -------------------------------------------------------------------------------
 
 
-
 Authentication
 ++++++++++++++
 
@@ -31,9 +33,6 @@ credentials for applications.
 .. _Authentication Getting Started Guide:
     https://cloud.google.com/docs/authentication/getting-started
 
-
-
-
 Install Dependencies
 ++++++++++++++++++++
 
@@ -64,15 +63,9 @@ Install Dependencies
 .. _pip: https://pip.pypa.io/
 .. _virtualenv: https://virtualenv.pypa.io/
 
-
-
-
-
-
 Samples
 -------------------------------------------------------------------------------
 
-
 Quickstart
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -89,8 +82,6 @@ To run this sample:
     $ python quickstart.py
 
 
-
-
 Simple Application
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -107,8 +98,6 @@ To run this sample:
     $ python simple_app.py
 
 
-
-
 User Credentials
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -124,7 +113,6 @@ To run this sample:
 
     $ python user_credentials.py
 
-
     usage: user_credentials.py [-h] [--launch-browser] project
 
     Command-line application to run a query using user credentials.
@@ -143,10 +131,6 @@ To run this sample:
 
 
 
-
-
-
-
 The client library
 -------------------------------------------------------------------------------
 
@@ -162,5 +146,4 @@ to `browse the source`_ and  `report issues`_.
     https://github.com/GoogleCloudPlatform/google-cloud-python/issues
 
 
-
-.. _Google Cloud SDK: https://cloud.google.com/sdk/
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

samples/snippets/conftest.py

@@ -50,6 +50,11 @@ def dataset_id(bigquery_client: bigquery.Client, project_id: str):
     bigquery_client.delete_dataset(dataset, delete_contents=True, not_found_ok=True)
 
 
+@pytest.fixture(scope="session")
+def entity_id(bigquery_client: bigquery.Client, dataset_id: str):
+    return "cloud-developer-relations@google.com"
+
+
 @pytest.fixture(scope="session")
 def dataset_id_us_east1(bigquery_client: bigquery.Client, project_id: str):
     dataset_id = prefixer.create_prefix()

samples/snippets/dataset_access_test.py

@@ -0,0 +1,48 @@
+# Copyright 2021 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.
+
+import revoke_dataset_access
+import update_dataset_access
+
+
+def test_dataset_access_permissions(capsys, dataset_id, entity_id, bigquery_client):
+    original_dataset = bigquery_client.get_dataset(dataset_id)
+    update_dataset_access.update_dataset_access(dataset_id, entity_id)
+    full_dataset_id = "{}.{}".format(
+        original_dataset.project, original_dataset.dataset_id
+    )
+
+    out, err = capsys.readouterr()
+    assert (
+        "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
+        in out
+    )
+
+    updated_dataset = bigquery_client.get_dataset(dataset_id)
+    updated_dataset_entries = list(updated_dataset.access_entries)
+    updated_dataset_entity_ids = {entry.entity_id for entry in updated_dataset_entries}
+    assert entity_id in updated_dataset_entity_ids
+    revoke_dataset_access.revoke_dataset_access(dataset_id, entity_id)
+    revoked_dataset = bigquery_client.get_dataset(dataset_id)
+    revoked_dataset_entries = list(revoked_dataset.access_entries)
+
+    full_dataset_id = f"{updated_dataset.project}.{updated_dataset.dataset_id}"
+    out, err = capsys.readouterr()
+    assert (
+        f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'"
+        in out
+    )
+    assert len(revoked_dataset_entries) == len(updated_dataset_entries) - 1
+    revoked_dataset_entity_ids = {entry.entity_id for entry in revoked_dataset_entries}
+    assert entity_id not in revoked_dataset_entity_ids

samples/snippets/revoke_dataset_access.py

@@ -0,0 +1,52 @@
+# Copyright 2021 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.
+
+
+def revoke_dataset_access(dataset_id: str, entity_id: str):
+    original_dataset_id = dataset_id
+    original_entity_id = entity_id
+
+    # [START bigquery_revoke_dataset_access]
+
+    # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
+    dataset_id = "your-project.your_dataset"
+
+    # TODO(developer): Set entity_id to the ID of the email or group from whom you are revoking access.
+    entity_id = "user-or-group-to-remove@example.com"
+    # [END bigquery_revoke_dataset_access]
+    dataset_id = original_dataset_id
+    entity_id = original_entity_id
+    # [START bigquery_revoke_dataset_access]
+
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
+
+    entries = list(dataset.access_entries)
+    dataset.access_entries = [
+        entry for entry in entries if entry.entity_id != entity_id
+    ]
+
+    dataset = client.update_dataset(
+        dataset,
+        # Update just the `access_entries` property of the dataset.
+        ["access_entries"],
+    )  # Make an API request.
+
+    full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
+    print(f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'")
+    # [END bigquery_revoke_dataset_access]

samples/snippets/update_dataset_access.py

@@ -0,0 +1,70 @@
+# 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
+#
+#     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.
+
+
+def update_dataset_access(dataset_id: str, entity_id: str):
+    original_dataset_id = dataset_id
+    original_entity_id = entity_id
+
+    # [START bigquery_update_dataset_access]
+
+    # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
+    dataset_id = "your-project.your_dataset"
+
+    # TODO(developer): Set entity_id to the ID of the email or group from whom
+    # you are adding access. Alternatively, to the JSON REST API representation
+    # of the entity, such as a view's table reference.
+    entity_id = "user-or-group-to-add@example.com"
+
+    # TODO(developer): Set entity_type to the type of entity you are granting access to.
+    # Common types include:
+    #
+    # * "userByEmail" -- A single user or service account. For example "fred@example.com"
+    # * "groupByEmail" -- A group of users. For example "example@googlegroups.com"
+    # * "view" -- An authorized view. For example
+    #       {"projectId": "p", "datasetId": "d", "tableId": "v"}
+    #
+    # For a complete reference, see the REST API reference documentation:
+    # https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#Dataset.FIELDS.access
+    entity_type = "groupByEmail"
+
+    # TODO(developer): Set role to a one of the "Basic roles for datasets"
+    # described here:
+    # https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
+    role = "READER"
+    # [END bigquery_update_dataset_access]
+    dataset_id = original_dataset_id
+    entity_id = original_entity_id
+    # [START bigquery_update_dataset_access]
+
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
+
+    entries = list(dataset.access_entries)
+    entries.append(
+        bigquery.AccessEntry(role=role, entity_type=entity_type, entity_id=entity_id,)
+    )
+    dataset.access_entries = entries
+
+    dataset = client.update_dataset(dataset, ["access_entries"])  # Make an API request.
+
+    full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
+    print(
+        "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
+    )
+    # [END bigquery_update_dataset_access]