docs: add a sample for using minute ranges in realtime reports (#314)

packages/google-analytics-data/samples/snippets/run_realtime_report_with_minute_ranges.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+
+# Copyright 2022 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 application demonstrating the creation of
+a realtime report using minute ranges.
+
+See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport#body.request_body.FIELDS.minute_ranges
+for more information.
+"""
+# [START analyticsdata_run_realtime_report_with_minute_ranges]
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import Metric
+from google.analytics.data_v1beta.types import MinuteRange
+from google.analytics.data_v1beta.types import RunRealtimeReportRequest
+
+from run_report import print_run_report_response
+
+
+def run_sample():
+    """Runs the sample."""
+    # TODO(developer): Replace this variable with your Google Analytics 4
+    #  property ID before running the sample.
+    property_id = "YOUR-GA4-PROPERTY-ID"
+    run_realtime_report_with_minute_ranges(property_id)
+
+
+def run_realtime_report_with_minute_ranges(property_id="YOUR-GA4-PROPERTY-ID"):
+    """Runs a realtime report on a Google Analytics 4 property. Dimensions
+    field is omitted in the query, which results in total values of active users
+    returned for each minute range in the report.
+
+    Note the `dateRange` dimension added to the report response automatically
+    as a result of querying multiple minute ranges.
+    """
+    client = BetaAnalyticsDataClient()
+
+    request = RunRealtimeReportRequest(
+        property=f"properties/{property_id}",
+        metrics=[Metric(name="activeUsers")],
+        minute_ranges=[
+            MinuteRange(name="0-4 minutes ago", start_minutes_ago=4),
+            MinuteRange(
+                name="25-29 minutes ago", start_minutes_ago=29, end_minutes_ago=25
+            ),
+        ],
+    )
+    response = client.run_realtime_report(request)
+    print_run_report_response(response)
+
+
+# [END analyticsdata_run_realtime_report_with_minute_ranges]
+
+
+if __name__ == "__main__":
+    run_sample()

packages/google-analytics-data/samples/snippets/run_realtime_report_with_minute_ranges_test.py

@@ -0,0 +1,27 @@
+# Copyright 2022 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 run_realtime_report_with_minute_ranges
+
+TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+
+
+def test_run_report_with_multiple_metrics(capsys):
+    run_realtime_report_with_minute_ranges.run_realtime_report_with_minute_ranges(
+        TEST_PROPERTY_ID
+    )
+    out, _ = capsys.readouterr()
+    assert "Report result" in out

packages/google-analytics-data/samples/snippets/run_report.py

@@ -64,12 +64,15 @@ def print_run_report_response(response):
 
     # [START analyticsdata_print_run_report_response_rows]
     print("Report result:")
-    for row in response.rows:
-        for dimension_value in row.dimension_values:
-            print(dimension_value.value)
-
-        for metric_value in row.metric_values:
-            print(metric_value.value)
+    for rowIdx, row in enumerate(response.rows):
+        print(f"\nRow {rowIdx}")
+        for i, dimension_value in enumerate(row.dimension_values):
+            dimension_name = response.dimension_headers[i].name
+            print(f"{dimension_name}: {dimension_value.value}")
+
+        for i, metric_value in enumerate(row.metric_values):
+            metric_name = response.metric_headers[i].name
+            print(f"{metric_name}: {metric_value.value}")
     # [END analyticsdata_print_run_report_response_rows]