docs: add Admin API samples for property user link management methods (…

…#67)

* docs: add Admin API samples for property user link management methods

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

samples/properties_user_links_audit.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+
+# 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.
+
+"""Google Analytics Admin API sample application which prints user links audit
+data on the Google Analytics 4 property.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.userLinks/audit
+for more information.
+"""
+# [START analyticsadmin_properties_user_links_audit]
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.analytics.admin_v1alpha.types import AuditUserLinksRequest
+
+
+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"
+    audit_property_user_links(property_id)
+
+
+def audit_property_user_links(property_id):
+    """Lists all user links on the Google Analytics 4 property, including
+    implicit ones that come from effective permissions granted by groups or
+    organization admin roles."""
+    client = AnalyticsAdminServiceClient()
+    results = client.audit_user_links(
+        AuditUserLinksRequest(parent=f"properties/{property_id}")
+    )
+
+    print("Result:")
+    for user_link in results:
+        print(f"Resource name: {user_link.name}")
+        print(f"Email address: {user_link.email_address}")
+        for direct_role in user_link.direct_roles:
+            print(f"Direct role: {direct_role}")
+
+        for effective_role in user_link.effective_roles:
+            print(f"Effective role: {effective_role}")
+        print()
+
+
+# [END analyticsadmin_properties_user_links_audit]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_user_links_audit_test.py

@@ -0,0 +1,26 @@
+# 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_user_links_audit
+
+
+TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+
+
+def test_properties_user_links_audit(capsys):
+    properties_user_links_audit.audit_property_user_links(TEST_PROPERTY_ID)
+    out, _ = capsys.readouterr()
+    assert "Result" in out

samples/properties_user_links_batch_create.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+
+# 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.
+
+"""Google Analytics Admin API sample application which creates a user link for
+the Google Analytics 4 property using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.userLinks/batchCreate
+for more information.
+"""
+# [START analyticsadmin_properties_user_links_batch_create]
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.analytics.admin_v1alpha.types import BatchCreateUserLinksRequest
+from google.analytics.admin_v1alpha.types import CreateUserLinkRequest
+from google.analytics.admin_v1alpha.types import UserLink
+
+
+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 account 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 an email address of the user to
+    #  link. This user will be given access to your account after running the
+    #  sample.
+    email_address = "TEST-EMAIL-ADDRESS"
+
+    batch_create_property_user_link(property_id, email_address)
+
+
+def batch_create_property_user_link(property_id, email_address):
+    """Creates a user link for the Google Analytics 4 property using a batch
+    call."""
+    client = AnalyticsAdminServiceClient()
+    response = client.batch_create_user_links(
+        BatchCreateUserLinksRequest(
+            parent=f"properties/{property_id}",
+            requests=[
+                CreateUserLinkRequest(
+                    user_link=UserLink(
+                        email_address=email_address,
+                        direct_roles=["predefinedRoles/read"],
+                    )
+                )
+            ],
+            notify_new_users=True,
+        )
+    )
+
+    print("Result:")
+    for user_link in response.user_links:
+        print(user_link)
+        print()
+
+
+# [END analyticsadmin_properties_user_links_batch_create]
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_user_links_batch_create_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_user_links_batch_create
+
+
+FAKE_PROPERTY_ID = "1"
+FAKE_EMAIL_ADDRESS = "test@google.com"
+
+
+def test_properties_user_links_batch_create():
+    # 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_user_links_batch_create.batch_create_property_user_link(
+            FAKE_PROPERTY_ID, FAKE_EMAIL_ADDRESS
+        )

samples/properties_user_links_batch_delete.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+
+# 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.
+
+"""Google Analytics Admin API sample application which delete the user link for
+the Google Analytics 4 property using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.userLinks/batchDelete
+for more information.
+"""
+# [START analyticsadmin_properties_user_links_batch_delete]
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.analytics.admin_v1alpha.types import BatchDeleteUserLinksRequest
+from google.analytics.admin_v1alpha.types import DeleteUserLinkRequest
+
+
+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 Google Analytics
+    #  account user link ID (e.g. "123456") before running the sample.
+    property_user_link_id = "YOUR-ACCOUNT-USER-LINK-ID"
+
+    batch_delete_property_user_link(property_id, property_user_link_id)
+
+
+def batch_delete_property_user_link(property_id, property_user_link_id):
+    """Deletes the GA4 property user link using a batch call."""
+    client = AnalyticsAdminServiceClient()
+    client.batch_delete_user_links(
+        BatchDeleteUserLinksRequest(
+            parent=f"properties/{property_id}",
+            requests=[
+                DeleteUserLinkRequest(
+                    name=f"properties/{property_id}/userLinks/{property_user_link_id}"
+                )
+            ],
+        )
+    )
+    print("User link deleted")
+
+
+# [END analyticsadmin_properties_user_links_batch_delete]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_user_links_batch_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_user_links_batch_delete
+
+
+FAKE_PROPERTY_ID = "1"
+FAKE_USER_LINK_ID = "1"
+
+
+def test_properties_user_links_batch_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_user_links_batch_delete.batch_delete_property_user_link(
+            FAKE_PROPERTY_ID, FAKE_USER_LINK_ID
+        )

samples/properties_user_links_batch_get.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+
+# 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.
+
+"""Google Analytics Admin API sample application which prints details for the
+Google Analytics 4 property user link using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.userLinks/batchGet
+for more information.
+"""
+# [START analyticsadmin_properties_user_links_batch_get]
+from google.analytics.admin import AnalyticsAdminServiceClient
+from google.analytics.admin_v1alpha.types import BatchGetUserLinksRequest
+
+
+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 Google Analytics
+    #  account user link ID (e.g. "123456") before running the sample.
+    property_user_link_id = "YOUR-ACCOUNT-USER-LINK-ID"
+
+    batch_get_property_user_link(property_id, property_user_link_id)
+
+
+def batch_get_property_user_link(property_id, property_user_link_id):
+    """Retrieves details for the Google Analytics 4 property user link using a
+    batch call."""
+    client = AnalyticsAdminServiceClient()
+    response = client.batch_get_user_links(
+        BatchGetUserLinksRequest(
+            parent=f"properties/{property_id}",
+            names=[f"properties/{property_id}/userLinks/{property_user_link_id}"],
+        )
+    )
+
+    print("Result:")
+    for user_link in response.user_links:
+        print(user_link)
+        print()
+
+
+# [END analyticsadmin_properties_user_links_batch_get]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/properties_user_links_batch_get_test.py

@@ -0,0 +1,28 @@
+# 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_user_links_batch_get
+
+TEST_PROPERTY_ID = os.getenv("GA_TEST_PROPERTY_ID")
+TEST_USER_LINK_ID = os.getenv("GA_USER_LINK_ID")
+
+
+def test_properties_user_links_batch_get(capsys):
+    properties_user_links_batch_get.batch_get_property_user_link(
+        TEST_PROPERTY_ID, TEST_USER_LINK_ID
+    )
+    out, _ = capsys.readouterr()
+    assert "Result" in out