docs: add Admin API samples for account management methods (#65)

* docs: add Admin API samples for account management methods

* update copyright and remove redundant run_sample method

* update noxfile template and set enforce_type_hints=False

* add type annotations

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

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

samples/accounts_user_links_audit.py

@@ -0,0 +1,59 @@
+#!/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 all user links on
+an account.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/accounts.userLinks/audit
+for more information.
+"""
+# [START analyticsadmin_accounts_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
+    #  account ID (e.g. "123456") before running the sample.
+    account_id = "YOUR-GA-ACCOUNT-ID"
+    audit_account_user_links(account_id)
+
+
+def audit_account_user_links(account_id):
+    """Lists all user links on an account, including implicit ones that come
+    from effective permissions granted by groups or organization admin roles."""
+    client = AnalyticsAdminServiceClient()
+
+    print("Result:")
+    for user_link in client.audit_user_links(
+        AuditUserLinksRequest(parent=f"accounts/{account_id}")
+    ):
+        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_accounts_user_links_audit]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/accounts_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 accounts_user_links_audit
+
+
+TEST_ACCOUNT_ID = os.getenv("GA_TEST_ACCOUNT_ID")
+
+
+def test_accounts_user_links_audit(capsys):
+    accounts_user_links_audit.audit_account_user_links(TEST_ACCOUNT_ID)
+    out, _ = capsys.readouterr()
+    assert "Result" in out

samples/accounts_user_links_batch_create.py

@@ -0,0 +1,77 @@
+#!/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 account using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/accounts.userLinks/batchCreate
+for more information.
+"""
+# [START analyticsadmin_accounts_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
+    #  account ID (e.g. "123456") before running the sample.
+    account_id = "YOUR-GA-ACCOUNT-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_account_user_link(account_id, email_address)
+
+
+def batch_create_account_user_link(account_id, email_address):
+    """Creates a user link for the account using a batch call."""
+    client = AnalyticsAdminServiceClient()
+    response = client.batch_create_user_links(
+        BatchCreateUserLinksRequest(
+            parent=f"accounts/{account_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_accounts_user_links_batch_create]
+
+if __name__ == "__main__":
+    run_sample()

samples/accounts_user_links_batch_create_test.py

@@ -0,0 +1,32 @@
+# 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 pytest
+
+import accounts_user_links_batch_create
+
+
+FAKE_ACCOUNT_ID = "1"
+TEST_EMAIL_ADDRESS = os.getenv("GA_TEST_EMAIL_ADDRESS")
+
+
+def test_accounts_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"):
+        accounts_user_links_batch_create.batch_create_account_user_link(
+            FAKE_ACCOUNT_ID, TEST_EMAIL_ADDRESS
+        )

samples/accounts_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 deletes the user link
+using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/accounts.userLinks/batchDelete
+for more information.
+"""
+# [START analyticsadmin_accounts_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
+    #  account ID (e.g. "123456") before running the sample.
+    account_id = "YOUR-GA-ACCOUNT-ID"
+
+    # TODO(developer): Replace this variable with your Google Analytics
+    #  account user link ID (e.g. "123456") before running the sample.
+    account_user_link_id = "YOUR-ACCOUNT-USER-LINK-ID"
+
+    batch_delete_account_user_link(account_id, account_user_link_id)
+
+
+def batch_delete_account_user_link(account_id, account_user_link_id):
+    """Deletes the user link using a batch call."""
+    client = AnalyticsAdminServiceClient()
+    client.batch_delete_user_links(
+        BatchDeleteUserLinksRequest(
+            parent=f"accounts/{account_id}",
+            requests=[
+                DeleteUserLinkRequest(
+                    name=f"accounts/{account_id}/userLinks/{account_user_link_id}"
+                )
+            ],
+        )
+    )
+    print("User link deleted")
+
+
+# [END analyticsadmin_accounts_user_links_batch_delete]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/accounts_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 accounts_user_links_batch_delete
+
+
+FAKE_ACCOUNT_ID = "1"
+FAKE_ACCOUNT_USER_LINK_ID = "1"
+
+
+def test_accounts_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"):
+        accounts_user_links_batch_delete.batch_delete_account_user_link(
+            FAKE_ACCOUNT_ID, FAKE_ACCOUNT_USER_LINK_ID
+        )

samples/accounts_user_links_batch_get.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 the details for
+the account user link using a batch call.
+
+See https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/accounts.userLinks/batchGet
+for more information.
+"""
+# [START analyticsadmin_accounts_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
+    #  account ID (e.g. "123456") before running the sample.
+    account_id = "YOUR-GA-ACCOUNT-ID"
+
+    # TODO(developer): Replace this variable with your Google Analytics
+    #  account user link ID (e.g. "123456") before running the sample.
+    account_user_link_id = "YOUR-ACCOUNT-USER-LINK-ID"
+
+    batch_get_account_user_link(account_id, account_user_link_id)
+
+
+def batch_get_account_user_link(account_id, account_user_link_id):
+    """Retrieves details for the account user link using a batch call."""
+    client = AnalyticsAdminServiceClient()
+    response = client.batch_get_user_links(
+        BatchGetUserLinksRequest(
+            parent=f"accounts/{account_id}",
+            names=[f"accounts/{account_id}/userLinks/{account_user_link_id}"],
+        )
+    )
+
+    print("Result:")
+    for user_link in response.user_links:
+        print(user_link)
+        print()
+
+
+# [END analyticsadmin_accounts_user_links_batch_get]
+
+
+if __name__ == "__main__":
+    run_sample()

samples/accounts_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 accounts_user_links_batch_get
+
+TEST_ACCOUNT_ID = os.getenv("GA_TEST_ACCOUNT_ID")
+TEST_USER_LINK_ID = os.getenv("GA_TEST_USER_LINK_ID")
+
+
+def test_accounts_user_links_batch_get(capsys):
+    accounts_user_links_batch_get.batch_get_account_user_link(
+        TEST_ACCOUNT_ID, TEST_USER_LINK_ID
+    )
+    out, _ = capsys.readouterr()
+    assert "Result" in out