docs: update quickstart samples to support the Data API v1 beta (#50)

* docs: added a sample

* docs: usage instructions updated to use Python3

* docs: updated sample to include main() method

* docs: update the sample to support the Google Analytics Data API v1 beta

* docs: update quickstart samples to support the Data API v1 beta

* docs: update quickstart samples to support the Data API v1 beta

* separate the sample into separate methods to facilitate testing

* separate the sample into separate methods to facilitate testing

* fix: update formatting

* fix: update formatting

* add noxfile_config with a test property id value

* add noxfile_config with a test property id value

* fix: use the credentials json file provided during the test

* fix: use the credentials json file provided during the test

samples/snippets/noxfile_config.py

@@ -0,0 +1,16 @@
+TEST_CONFIG_OVERRIDE = {
+    # You can opt out from the test for specific Python versions.
+    "ignored_versions": ["2.7"],
+    # Old samples are opted out of enforcing Python type hints
+    # All new samples should feature them
+    "enforce_type_hints": True,
+    # An envvar key for determining the project id to use. Change it
+    # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
+    # build specific Cloud project. You can also use your own string
+    # to use your own Cloud project.
+    "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
+    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # A dictionary you want to inject into your test. Don't put any
+    # secrets here. These values will override predefined values.
+    "envs": {"GA_TEST_PROPERTY_ID": "222596558"},
+}

samples/snippets/quickstart.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright 2020 Google Inc. All Rights Reserved.
+# Copyright 2021 Google Inc. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,87 +15,56 @@
 # limitations under the License.
 
 """Google Analytics Data API sample quickstart application.
-Example usage:
-    python quickstart.py --property_id <PROPERTY_ID>
-
-    where <PROPERTY_ID> is the Google Analytics property id to use for a query.
-
-Note: you need to have the Google Analytics Data API enabled in your project
-prior to running this sample. Please visit the following URL and make sure the
-API is enabled:
-
-https://console.developers.google.com/apis/library/analyticsdata.googleapis.com
 
 This application demonstrates the usage of the Analytics Data API using
-service account credentials. For more information on service accounts, see
-
-https://cloud.google.com/iam/docs/understanding-service-accounts
-
-The following document provides instructions on setting service account
-credentials for your application:
-
-  https://cloud.google.com/docs/authentication/production
-
-In a nutshell, you need to:
-1. Create a service account and download the key JSON file.
-
-https://cloud.google.com/docs/authentication/production#creating_a_service_account
+service account credentials.
 
-2. Provide service account credentials using one of the following options:
-- set the GOOGLE_APPLICATION_CREDENTIALS environment variable, the API
-client will use the value of this variable to find the service account key
-JSON file.
+Before you start the application, please review the comments starting with
+"TODO(developer)" and update the code to use correct values.
 
-https://cloud.google.com/docs/authentication/production#setting_the_environment_variable
-
-OR
-- manually pass the path to the service account key JSON file to the API client
-by specifying the keyFilename parameter in the constructor:
-https://cloud.google.com/docs/authentication/production#passing_the_path_to_the_service_account_key_in_code
-
-To install the latest published package dependency, execute the following:
-  pip install google-analytics-data
+Usage:
+  pip3 install --upgrade google-analytics-data
+  python3 quickstart.py
 """
-import argparse
+# [START google_analytics_data_quickstart]
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import DateRange
+from google.analytics.data_v1beta.types import Dimension
+from google.analytics.data_v1beta.types import Metric
+from google.analytics.data_v1beta.types import RunReportRequest
 
-# [START ga_data_run_report]
-from google.analytics.data_v1alpha import AlphaAnalyticsDataClient
-from google.analytics.data_v1alpha.types import DateRange
-from google.analytics.data_v1alpha.types import Dimension
-from google.analytics.data_v1alpha.types import Entity
-from google.analytics.data_v1alpha.types import Metric
-from google.analytics.data_v1alpha.types import RunReportRequest
 
+def sample_run_report(property_id="YOUR-GA4-PROPERTY-ID"):
+    """Runs a simple report on a Google Analytics 4 property."""
+    # TODO(developer): Uncomment this variable and replace with your
+    #  Google Analytics 4 property ID before running the sample.
+    # property_id = "YOUR-GA4-PROPERTY-ID"
 
-def sample_run_report(property_id):
-    """Runs a simple report on a Google Analytics App+Web property."""
-
+    # [START google_analytics_data_initialize]
     # Using a default constructor instructs the client to use the credentials
     # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
-    client = AlphaAnalyticsDataClient()
-    request = RunReportRequest(entity=Entity(property_id=property_id),
-                               dimensions=[Dimension(name='city')],
-                               metrics=[Metric(name='activeUsers')],
-                               date_ranges=[DateRange(start_date='2020-03-31',
-                                                      end_date='today')])
+    client = BetaAnalyticsDataClient()
+    # [END google_analytics_data_initialize]
+
+    # [START google_analytics_data_run_report]
+    request = RunReportRequest(
+        property="properties/" + str(property_id),
+        dimensions=[Dimension(name="city")],
+        metrics=[Metric(name="activeUsers")],
+        date_ranges=[DateRange(start_date="2020-03-31", end_date="today")],
+    )
     response = client.run_report(request)
+    # [END google_analytics_data_run_report]
 
+    # [START google_analytics_data_run_report_response]
     print("Report result:")
     for row in response.rows:
         print(row.dimension_values[0].value, row.metric_values[0].value)
+    # [END google_analytics_data_run_report_response]
 
 
-# [END ga_data_run_report]
+# [END google_analytics_data_quickstart]
+
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument(
-        "--property_id",
-        type=str,
-        required=True,
-        help="Google Analytics property ID to use for a query.",
-    )
-    args = parser.parse_args()
-    sample_run_report(args.property_id)
+    sample_run_report()

samples/snippets/quickstart_json_credentials.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# 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.
+
+"""Google Analytics Data API sample quickstart application.
+
+This application demonstrates the usage of the Analytics Data API using
+service account credentials from a JSON file downloaded from
+the Google Cloud Console.
+
+Before you start the application, please review the comments starting with
+"TODO(developer)" and update the code to use correct values.
+
+Usage:
+  pip3 install --upgrade google-analytics-data
+  python3 quickstart_json_credentials.py
+"""
+# [START google_analytics_data_quickstart]
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import DateRange
+from google.analytics.data_v1beta.types import Dimension
+from google.analytics.data_v1beta.types import Metric
+from google.analytics.data_v1beta.types import RunReportRequest
+
+
+def sample_run_report(property_id="YOUR-GA4-PROPERTY-ID", credentials_json_path=""):
+    """Runs a simple report on a Google Analytics 4 property."""
+    # TODO(developer): Uncomment this variable and replace with your
+    #  Google Analytics 4 property ID before running the sample.
+    # property_id = "YOUR-GA4-PROPERTY-ID"
+
+    # [START google_analytics_data_initialize]
+    # TODO(developer): Uncomment this variable and replace with a valid path to
+    #  the credentials.json file for your service account downloaded from the
+    #  Cloud Console.
+    # credentials_json_path = "/path/to/credentials.json"
+
+    # Explicitly use service account credentials by specifying
+    # the private key file.
+    client = BetaAnalyticsDataClient().from_service_account_json(credentials_json_path)
+    # [END google_analytics_data_initialize]
+
+    # [START google_analytics_data_run_report]
+    request = RunReportRequest(
+        property="properties/" + str(property_id),
+        dimensions=[Dimension(name="city")],
+        metrics=[Metric(name="activeUsers")],
+        date_ranges=[DateRange(start_date="2020-03-31", end_date="today")],
+    )
+    response = client.run_report(request)
+    # [END google_analytics_data_run_report]
+
+    print("Report result:")
+    for row in response.rows:
+        print(row.dimension_values[0].value, row.metric_values[0].value)
+# [END google_analytics_data_quickstart]
+
+
+if __name__ == "__main__":
+    sample_run_report()

samples/snippets/quickstart_json_credentials_test.py

@@ -0,0 +1,29 @@
+# Copyright 2020 Google Inc. All Rights Reserved.
+#
+# 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.
+
+import os
+
+import quickstart_json_credentials
+
+
+def test_quickstart(capsys):
+    # Create a temporary service account credentials JSON file to be used by
+    # the test.
+    TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+    CREDENTIALS_JSON_PATH = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+    quickstart_json_credentials.sample_run_report(
+        TEST_PROPERTY_ID, CREDENTIALS_JSON_PATH
+    )
+    out, _ = capsys.readouterr()
+    assert "Report result" in out

samples/snippets/quickstart_oauth2.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# 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.
+
+"""Google Analytics Data API sample quickstart application.
+
+This application demonstrates the usage of the Analytics Data API using
+OAuth2 credentials.
+
+Before you start the application, please review the comments starting with
+"TODO(developer)" and update the code to use correct values.
+
+Usage:
+  pip3 install --upgrade google-auth-oauthlib
+  pip3 install --upgrade google-analytics-data
+  python3 quickstart_oauth2.py
+"""
+# [START google_analytics_data_quickstart]
+from google.analytics.data import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import DateRange
+from google.analytics.data_v1beta.types import Dimension
+from google.analytics.data_v1beta.types import Metric
+from google.analytics.data_v1beta.types import RunReportRequest
+from google_auth_oauthlib import flow
+
+
+def sample_run_report(credentials=None, property_id="YOUR-GA4-PROPERTY-ID"):
+    """Runs a simple report on a Google Analytics 4 property."""
+    # TODO(developer): Uncomment this variable and replace with your
+    #  Google Analytics 4 property ID before running the sample.
+    # property_id = "YOUR-GA4-PROPERTY-ID"
+
+    client = BetaAnalyticsDataClient(credentials=credentials)
+    request = RunReportRequest(
+        property="properties/" + str(property_id),
+        dimensions=[Dimension(name="city")],
+        metrics=[Metric(name="activeUsers")],
+        date_ranges=[DateRange(start_date="2020-03-31", end_date="today")],
+    )
+
+    response = client.run_report(request)
+
+    print("Report result:")
+    for row in response.rows:
+        print(row.dimension_values[0].value, row.metric_values[0].value)
+
+
+def get_credentials():
+    """Creates an OAuth2 credentials instance."""
+    # [START google_analytics_data_initialize]
+    appflow = flow.InstalledAppFlow.from_client_secrets_file(
+        "client_secrets.json",
+        scopes=["https://www.googleapis.com/auth/analytics.readonly"],
+    )
+    # TODO(developer): Update the line below to set the `launch_browser` variable.
+    # The `launch_browser` boolean variable indicates if a local server is used
+    # as the callback URL in the auth flow. A value of `True` is recommended,
+    # but a local server does not work if accessing the application remotely,
+    # such as over SSH or from a remote Jupyter notebook.
+    launch_browser = True
+    if launch_browser:
+        appflow.run_local_server()
+    else:
+        appflow.run_console()
+    return appflow.credentials
+    # [END google_analytics_data_initialize]
+
+
+def main():
+    credentials = get_credentials()
+    sample_run_report(credentials)
+
+
+# [END google_analytics_data_quickstart]
+
+if __name__ == "__main__":
+    main()

samples/snippets/quickstart_oauth2_test.py

@@ -0,0 +1,24 @@
+# Copyright 2020 Google Inc. All Rights Reserved.
+#
+# 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.
+
+import os
+
+import quickstart_oauth2
+
+
+def test_quickstart(capsys):
+    TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+    quickstart_oauth2.sample_run_report(None, TEST_PROPERTY_ID)
+    out, _ = capsys.readouterr()
+    assert "Report result" in out

samples/snippets/quickstart_test.py

@@ -12,11 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
+
 import quickstart
 
 
 def test_quickstart(capsys):
-    TEST_PROPERTY_ID = '222596558'
+    TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
     quickstart.sample_run_report(TEST_PROPERTY_ID)
     out, _ = capsys.readouterr()
     assert "Report result" in out

samples/snippets/requirements.txt

@@ -1 +1,2 @@
 google-analytics-data==0.4.0
+google-auth-oauthlib==0.4.3