docs: add Admin API samples for property stream management methods (#68)

* docs: add Admin API samples for property stream management methods

* fix the copyright string, avoid importing functions from other samples

samples/properties_android_app_data_streams_delete.py

@@ -0,0 +1,59 @@
+#!/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 Admin API sample application which deletes the Android app
+data stream.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.androidAppDataStreams/delete
+for more information.
+"""
+# [START analyticsadmin_properties_android_app_data_streams_delete]
+from google.analytics.admin import AnalyticsAdminServiceClient
+
+
+def run_sample():
+    """Runs the sample."""
+
+    # !!! ATTENTION !!!
+    #  Running this sample may change/delete your Google Analytics account
+    #  configuration. Make sure to not use the Google Analytics property ID from
+    #  your production environment below.
+
+    # TODO(developer): Replace this variable with your Google Analytics 4
+    #  property ID (e.g. "123456") before running the sample.
+    property_id = "YOUR-GA4-PROPERTY-ID"
+
+    # TODO(developer): Replace this variable with your Android app data stream ID
+    #  (e.g. "123456") before running the sample.
+    stream_id = "YOUR-ANDROID-APP-DATA-STREAM-ID"
+
+    delete_android_app_data_stream(property_id, stream_id)
+
+
+def delete_android_app_data_stream(property_id, stream_id):
+    """Deletes the Android app data stream."""
+    client = AnalyticsAdminServiceClient()
+    client.delete_android_app_data_stream(
+        name=f"properties/{property_id}/androidAppDataStreams/{stream_id}"
+    )
+    print("Android app data stream deleted")
+
+
+# [END analyticsadmin_properties_android_app_data_streams_delete]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_android_app_data_streams_delete_test.py

@@ -0,0 +1,30 @@
+# Copyright 2021 Google LLC 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 pytest
+
+import properties_android_app_data_streams_delete
+
+
+FAKE_PROPERTY_ID = "1"
+FAKE_STREAM_ID = "1"
+
+
+def test_properties_android_app_data_streams_delete():
+    # This test ensures that the call is valid and reaches the server, even
+    # though the operation does not succeed due to permission error.
+    with pytest.raises(Exception, match="403 The caller does not have permission"):
+        properties_android_app_data_streams_delete.delete_android_app_data_stream(
+            FAKE_PROPERTY_ID, FAKE_STREAM_ID
+        )

samples/properties_android_app_data_streams_get.py

@@ -0,0 +1,65 @@
+#!/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 Admin API sample application which prints the details for
+an Android app data stream.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.androidAppDataStreams/get
+for more information.
+"""
+# [START analyticsadmin_properties_android_app_data_streams_get]
+from google.analytics.admin import AnalyticsAdminServiceClient
+
+
+def run_sample():
+    """Runs the sample."""
+    # TODO(developer): Replace this variable with your Google Analytics 4
+    #  property ID (e.g. "123456") before running the sample.
+    property_id = "YOUR-GA4-PROPERTY-ID"
+
+    # TODO(developer): Replace this variable with your Android app data stream ID
+    #  (e.g. "123456") before running the sample.
+    stream_id = "YOUR-ANDROID-APP-DATA-STREAM-ID"
+
+    get_android_app_data_stream(property_id, stream_id)
+
+
+def get_android_app_data_stream(property_id, stream_id):
+    """Retrieves the details for an Android app data stream."""
+    client = AnalyticsAdminServiceClient()
+    android_app_data_stream = client.get_android_app_data_stream(
+        name=f"properties/{property_id}/androidAppDataStreams/{stream_id}"
+    )
+
+    print("Result:")
+    print_android_app_data_stream(android_app_data_stream)
+
+
+def print_android_app_data_stream(android_app_data_stream):
+    """Prints the Android app data stream details."""
+    print(f"Resource name: {android_app_data_stream.name}")
+    print(f"Display name: {android_app_data_stream.display_name}")
+    print(f"Firebase app ID: {android_app_data_stream.firebase_app_id}")
+    print(f"Package name: {android_app_data_stream.package_name}")
+    print(f"Create time: {android_app_data_stream.create_time}")
+    print(f"Update time: {android_app_data_stream.update_time}")
+
+
+# [END analyticsadmin_properties_android_app_data_streams_get]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_android_app_data_streams_get_test.py

@@ -0,0 +1,29 @@
+# Copyright 2021 Google LLC 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 properties_android_app_data_streams_get
+
+
+TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+TEST_ANDROID_APP_DATA_STREAM_ID = os.getenv("GA_TEST_ANDROID_APP_DATA_STREAM_ID")
+
+
+def test_properties_android_app_data_streams_get(capsys):
+    properties_android_app_data_streams_get.get_android_app_data_stream(
+        TEST_PROPERTY_ID, TEST_ANDROID_APP_DATA_STREAM_ID
+    )
+    out, _ = capsys.readouterr()
+    assert "Result" in out

samples/properties_android_app_data_streams_list.py

@@ -0,0 +1,51 @@
+#!/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 Admin API sample application which prints Android app data
+streams for a Google Analytics 4 property.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.androidAppDataStreams/list
+for more information.
+"""
+# [START analyticsadmin_properties_android_app_data_streams_list]
+from google.analytics.admin import AnalyticsAdminServiceClient
+
+
+def run_sample():
+    """Runs the sample."""
+    # TODO(developer): Replace this variable with your Google Analytics 4
+    #  property ID (e.g. "123456") before running the sample.
+    property_id = "YOUR-GA4-PROPERTY-ID"
+
+    list_android_app_data_streams(property_id)
+
+
+def list_android_app_data_streams(property_id):
+    """Lists Android app data streams for a Google Analytics 4 property."""
+    client = AnalyticsAdminServiceClient()
+    results = client.list_android_app_data_streams(parent=f"properties/{property_id}")
+
+    print("Result:")
+    for android_app_data_stream in results:
+        print(android_app_data_stream)
+        print()
+
+
+# [END analyticsadmin_properties_android_app_data_streams_list]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_android_app_data_streams_list_test.py

@@ -0,0 +1,27 @@
+# Copyright 2021 Google LLC 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 properties_android_app_data_streams_list
+
+TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+
+
+def test_properties_android_app_data_streams_list(capsys):
+    properties_android_app_data_streams_list.list_android_app_data_streams(
+        TEST_PROPERTY_ID
+    )
+    out, _ = capsys.readouterr()
+    assert "Result" in out

samples/properties_android_app_data_streams_update.py

@@ -0,0 +1,71 @@
+#!/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 Admin API sample application which updates the Android app
+data stream.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.androidAppDataStreams/update
+for more information.
+"""
+# [START analyticsadmin_properties_android_app_data_streams_update]
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.analytics.admin_v1alpha.types import AndroidAppDataStream
+from google.protobuf.field_mask_pb2 import FieldMask
+
+
+def run_sample():
+    """Runs the sample."""
+
+    # !!! ATTENTION !!!
+    #  Running this sample may change/delete your Google Analytics account
+    #  configuration. Make sure to not use the Google Analytics property ID from
+    #  your production environment below.
+
+    # TODO(developer): Replace this variable with your Google Analytics 4
+    #  property ID (e.g. "123456") before running the sample.
+    property_id = "YOUR-GA4-PROPERTY-ID"
+
+    # TODO(developer): Replace this variable with your Android app data stream ID
+    #  (e.g. "123456") before running the sample.
+    stream_id = "YOUR-ANDROID-APP-DATA-STREAM-ID"
+
+    update_android_app_data_stream(property_id, stream_id)
+
+
+def update_android_app_data_stream(property_id, stream_id):
+    """Updates the Android app data stream."""
+    client = AnalyticsAdminServiceClient()
+    # This call updates the display name of the Android app data stream, as
+    # indicated by the value of the `update_mask` field. The Android app data
+    # stream to update is specified in the `name` field of the
+    # `AndroidAppDataStream` instance.
+    android_app_data_stream = client.update_android_app_data_stream(
+        android_app_data_stream=AndroidAppDataStream(
+            name=f"properties/{property_id}/androidAppDataStreams/{stream_id}",
+            display_name="This is an updated test Android app data stream",
+        ),
+        update_mask=FieldMask(paths=["display_name"]),
+    )
+
+    print("Result:")
+    print(android_app_data_stream)
+
+
+# [END analyticsadmin_properties_android_app_data_streams_update]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_android_app_data_streams_update_test.py

@@ -0,0 +1,30 @@
+# Copyright 2021 Google LLC 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 pytest
+
+import properties_android_app_data_streams_update
+
+
+FAKE_PROPERTY_ID = "1"
+FAKE_STREAM_ID = "1"
+
+
+def test_properties_android_app_data_streams_update():
+    # This test ensures that the call is valid and reaches the server, even
+    # though the operation does not succeed due to permission error.
+    with pytest.raises(Exception, match="403 The caller does not have permission"):
+        properties_android_app_data_streams_update.update_android_app_data_stream(
+            FAKE_PROPERTY_ID, FAKE_STREAM_ID
+        )