BigQuery - REST samples for adding labels. (GoogleCloudPlatform#764)

See docs: https://cloud.google.com/bigquery/docs/labeling-datasets

bigquery/rest/README.rst

@@ -0,0 +1,105 @@
+.. This file is automatically generated. Do not edit this file directly.
+
+Google BigQuery Python Samples
+===============================================================================
+
+This directory contains samples for Google BigQuery. `Google BigQuery`_ is Google's fully managed, petabyte scale, low cost analytics data warehouse. BigQuery is NoOps—there is no infrastructure to manage and you don't need a database administrator—so you can focus on analyzing data to find meaningful insights, use familiar SQL, and take advantage of our pay-as-you-go model.
+
+
+
+
+.. _Google BigQuery: https://cloud.google.com/bigquery/docs 
+
+Setup
+-------------------------------------------------------------------------------
+
+
+Authentication
+++++++++++++++
+
+Authentication is typically done through `Application Default Credentials`_,
+which means you do not have to change the code to authenticate as long as
+your environment has credentials. You have a few options for setting up
+authentication:
+
+#. When running locally, use the `Google Cloud SDK`_
+
+    .. code-block:: bash
+
+        gcloud beta auth application-default login
+
+
+#. When running on App Engine or Compute Engine, credentials are already
+   set-up. However, you may need to configure your Compute Engine instance
+   with `additional scopes`_.
+
+#. You can create a `Service Account key file`_. This file can be used to
+   authenticate to Google Cloud Platform services from any environment. To use
+   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
+   the path to the key file, for example:
+
+    .. code-block:: bash
+
+        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
+
+.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
+.. _additional scopes: https://cloud.google.com/compute/docs/authentication#using
+.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them.
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+
+Samples
+-------------------------------------------------------------------------------
+
+Label a dataset or table
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python labels.py
+
+    usage: labels.py [-h] [--project_id PROJECT_ID] [--table_id TABLE_ID]
+                     dataset_id label_key label_value
+    
+    Application to add or modify a label on a BigQuery dataset or table.
+    
+    positional arguments:
+      dataset_id            BigQuery dataset ID.
+      label_key             Key for new/modified label.
+      label_value           Value for new/modified label.
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      --project_id PROJECT_ID
+                            Google Cloud project ID. If not set, uses a default
+                            value from the environment.
+      --table_id TABLE_ID   BigQuery table ID. If present, a label is added to the
+                            specified table instead of the dataset.
+
+
+
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

bigquery/rest/README.rst.in

@@ -0,0 +1,23 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google BigQuery
+  short_name: BigQuery
+  url: https://cloud.google.com/bigquery/docs
+  description: > 
+    `Google BigQuery`_ is Google's fully managed, petabyte scale, low cost
+    analytics data warehouse. BigQuery is NoOps—there is no infrastructure to
+    manage and you don't need a database administrator—so you can focus on
+    analyzing data to find meaningful insights, use familiar SQL, and take
+    advantage of our pay-as-you-go model.
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Label a dataset or table
+  show_help: true
+  file: labels.py
+
+cloud_client_library: false

bigquery/rest/labels.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+
+# Copyright 2016, Google, Inc.
+# 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.
+
+"""Application to add or modify a label on a BigQuery dataset or table."""
+
+import argparse
+
+import google.auth
+import google.auth.transport.requests
+
+
+def label_dataset(dataset_id, label_key, label_value, project_id=None):
+    """Add or modify a label on a dataset."""
+    # Authenticate requests using Google Application Default credentials.
+    credentials, default_project_id = google.auth.default(
+            scopes=['https://www.googleapis.com/auth/bigquery'])
+    session = google.auth.transport.requests.AuthorizedSession(credentials)
+
+    if project_id is None:
+        project_id = default_project_id
+
+    # Send a PATCH request to add or modify a label.
+    url_format = (
+        'https://www.googleapis.com/bigquery/v2/'
+        'projects/{project_id}/datasets/{dataset_id}')
+    response = session.patch(
+        url_format.format(project_id=project_id, dataset_id=dataset_id),
+        params={'fields': 'labels'},
+        json={
+            'labels': {
+                label_key: label_value,
+            }
+        })
+
+    # Check the response for errors.
+    response.raise_for_status()
+
+    # Print the new label value from the response.
+    labels = response.json()['labels']
+    print(
+        'Updated label "{}" with value "{}"'.format(
+            label_key,
+            labels[label_key]))
+
+
+def label_table(dataset_id, table_id, label_key, label_value, project_id=None):
+    """Add or modify a label on a table."""
+    # Authenticate requests using Google Application Default credentials.
+    credentials, default_project_id = google.auth.default(
+            scopes=['https://www.googleapis.com/auth/bigquery'])
+    session = google.auth.transport.requests.AuthorizedSession(credentials)
+
+    if project_id is None:
+        project_id = default_project_id
+
+    # Send a PATCH request to add or modify a label.
+    url_format = (
+        'https://www.googleapis.com/bigquery/v2/'
+        'projects/{project_id}/datasets/{dataset_id}/tables/{table_id}')
+    response = session.patch(
+        url_format.format(
+            project_id=project_id,
+            dataset_id=dataset_id,
+            table_id=table_id),
+        params={'fields': 'labels'},
+        json={
+            'labels': {
+                label_key: label_value,
+            }
+        })
+
+    # Check the response for errors.
+    response.raise_for_status()
+
+    # Print the new label value from the response.
+    labels = response.json()['labels']
+    print(
+        'Updated label "{}" with value "{}"'.format(
+            label_key,
+            labels[label_key]))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument('dataset_id', help='BigQuery dataset ID.')
+    parser.add_argument('label_key', help='Key for new/modified label.')
+    parser.add_argument('label_value', help='Value for new/modified label.')
+    parser.add_argument(
+        '--project_id',
+        help=(
+            'Google Cloud project ID. '
+            'If not set, uses a default value from the environment.'),
+        default=None)
+    parser.add_argument(
+        '--table_id',
+        help=(
+            'BigQuery table ID. '
+            'If present, a label is added to the specified table instead of '
+            'the dataset.'),
+        default=None)
+
+    args = parser.parse_args()
+
+    if args.table_id is None:
+        label_dataset(
+            args.dataset_id,
+            args.label_key,
+            args.label_value,
+            project_id=args.project_id)
+    else:
+        label_table(
+            args.dataset_id,
+            args.table_id,
+            args.label_key,
+            args.label_value,
+            project_id=args.project_id)

bigquery/rest/labels_test.py

@@ -0,0 +1,41 @@
+# Copyright 2016, Google, Inc.
+# 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.
+
+from labels import label_dataset, label_table
+
+
+def test_label_dataset(cloud_config, capsys):
+    label_dataset(
+        'test_dataset',
+        'environment',
+        'test',
+        project_id=cloud_config.project)
+
+    out, _ = capsys.readouterr()
+    result = out.split('\n')[0]
+
+    assert 'Updated label "environment" with value "test"' in result
+
+
+def test_label_table(cloud_config, capsys):
+    label_table(
+        'test_dataset',
+        'test_table',
+        'data-owner',
+        'my-team',
+        project_id=cloud_config.project)
+
+    out, _ = capsys.readouterr()
+    result = out.split('\n')[0]
+
+    assert 'Updated label "data-owner" with value "my-team"' in result

bigquery/rest/requirements.txt

@@ -0,0 +1,2 @@
+google-auth==0.5.0
+requests==2.12.5