Add support for the Admint Audit Events API

Add the API wrapper, data model, tests, and update the docs.

Author: cmlccie

docs/user/api.rst

@@ -31,6 +31,13 @@ access_tokens
 .. autoclass:: webexteamssdk.api.access_tokens.AccessTokensAPI()
 
 
+.. _admin_audit_events:
+
+admin_audit_events
+------------------
+
+.. autoclass:: webexteamssdk.api.admin_audit_events.AdminAuditEventsAPI()
+
 
 .. _attachment_actions
 
@@ -153,7 +160,10 @@ Access Token
 
 .. _Admin_Audit_Event:
 
+Admin Audit Event
+-----------------
 
+.. autoclass:: AdminAuditEvent()
     :inherited-members:
 
 

docs/user/api_structure_table.rst

@@ -2,6 +2,8 @@
 | :class:`WebexTeamsAPI` | :ref:`access_tokens`      | :meth:`get() <webeteamssdk.api.access_tokens.AccessTokensAPI.get>`              |
 |                        |                           | :meth:`refresh() <webeteamssdk.api.access_tokens.AccessTokensAPI.refresh>`      |
 +------------------------+---------------------------+---------------------------------------------------------------------------------+
+|                        | :ref:`admin_audit_events` | :meth:`list() <webexteamssdk.api.admin_audit_events.list>`                      |
++------------------------+---------------------------+---------------------------------------------------------------------------------+
 |                        | :ref:`attachment_actions` | :meth:`create() <webexteamssdk.api.attachment_actions.create>`                  |
 |                        |                           | :meth:`get() <webexteamssdk.api.attachment_actions.get>`                        |
 +------------------------+---------------------------+---------------------------------------------------------------------------------+

tests/api/test_admin_audit_events.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""WebexTeamsAPI Admin Audit Events API fixtures and tests.
+
+Copyright (c) 2016-2019 Cisco and/or its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import itertools
+
+import pytest
+
+import webexteamssdk
+
+
+from_datetime_string = str(
+    webexteamssdk.WebexTeamsDateTime(2018, 1, 1, 0, 0, 0, 0),
+)
+
+to_datetime_string = str(
+    webexteamssdk.WebexTeamsDateTime.utcnow(),
+)
+
+
+# Helper Functions
+
+def is_valid_admin_audit_event(obj):
+    return isinstance(obj, webexteamssdk.AdminAuditEvent) \
+           and obj.id is not None
+
+
+def are_valid_admin_audit_events(iterable):
+    return all([is_valid_admin_audit_event(obj) for obj in iterable])
+
+
+# Fixtures
+
+@pytest.fixture(scope="session")
+def admin_audit_events(api, me):
+    three_events = list(api.admin_audit_events.list(
+        orgId=me.orgId,
+        _from=from_datetime_string,
+        to=to_datetime_string,
+    )[:3])
+    assert len(three_events) == 3
+    return three_events
+
+
+# Tests
+
+def test_list_admin_audit_events(api, admin_audit_events):
+    assert are_valid_admin_audit_events(admin_audit_events)
+
+
+def test_list_admin_audit_events_by_actor_id(api, admin_audit_events):
+    actor_id = admin_audit_events[0].actorId
+    actor_events = list(api.events.list(actorId=actor_id)[:3])
+    assert are_valid_admin_audit_events(actor_events)
+    assert all([event.actorId == actor_id for event in actor_events])
+
+
+@pytest.mark.xfail  # TODO: Returned link headers are malformed on the endpoint
+def test_list_events_with_paging(api, me, admin_audit_events):
+    page_size = 1
+    pages = 3
+    num_events = pages * page_size
+    assert len(admin_audit_events) >= num_events
+    events_gen = api.admin_audit_events.list(
+        orgId=me.orgId,
+        _from=from_datetime_string,
+        to=to_datetime_string,
+        max=page_size,
+    )
+    events_list = list(itertools.islice(events_gen, num_events))
+    assert len(events_list) == num_events
+    assert are_valid_admin_audit_events(events_list)

webexteamssdk/__init__.py

@@ -42,9 +42,9 @@
 )
 from .models.dictionary import dict_data_factory
 from .models.immutable import (
-    AccessToken, AttachmentAction, Event, immutable_data_factory, License,
-    Membership, Message, Organization, Person, Role, Room, Team,
-    TeamMembership, Webhook, WebhookEvent,
+    AccessToken, AdminAuditEvent, AttachmentAction, Event,
+    immutable_data_factory, License, Membership, Message, Organization, Person,
+    Role, Room, Team, TeamMembership, Webhook, WebhookEvent,
 )
 from .models.simple import simple_data_factory, SimpleDataModel
 from .utils import WebexTeamsDateTime

webexteamssdk/api/__init__.py

@@ -34,6 +34,7 @@
 from webexteamssdk.restsession import RestSession
 from webexteamssdk.utils import check_type
 from .access_tokens import AccessTokensAPI
+from .admin_audit_events import AdminAuditEventsAPI
 from .attachment_actions import AttachmentActionsAPI
 from .events import EventsAPI
 from .guest_issuer import GuestIssuerAPI
@@ -172,23 +173,26 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         )
 
         # API wrappers
-        self.people = PeopleAPI(self._session, object_factory)
-        self.rooms = RoomsAPI(self._session, object_factory)
+        self.admin_audit_events = AdminAuditEventsAPI(
+            self._session, object_factory,
+        )
+        self.attachment_actions = AttachmentActionsAPI(
+            self._session, object_factory,
+        )
+        self.events = EventsAPI(self._session, object_factory)
+        self.guest_issuer = GuestIssuerAPI(self._session, object_factory)
+        self.licenses = LicensesAPI(self._session, object_factory)
         self.memberships = MembershipsAPI(self._session, object_factory)
         self.messages = MessagesAPI(self._session, object_factory)
+        self.organizations = OrganizationsAPI(self._session, object_factory)
+        self.people = PeopleAPI(self._session, object_factory)
+        self.roles = RolesAPI(self._session, object_factory)
+        self.rooms = RoomsAPI(self._session, object_factory)
         self.teams = TeamsAPI(self._session, object_factory)
         self.team_memberships = TeamMembershipsAPI(
-            self._session, object_factory
-        )
-        self.attachment_actions = AttachmentActionsAPI(
-            self._session, object_factory
+            self._session, object_factory,
         )
         self.webhooks = WebhooksAPI(self._session, object_factory)
-        self.organizations = OrganizationsAPI(self._session, object_factory)
-        self.licenses = LicensesAPI(self._session, object_factory)
-        self.roles = RolesAPI(self._session, object_factory)
-        self.events = EventsAPI(self._session, object_factory)
-        self.guest_issuer = GuestIssuerAPI(self._session, object_factory)
 
     @property
     def access_token(self):

webexteamssdk/api/admin_audit_events.py

@@ -0,0 +1,133 @@
+# -*- coding: utf-8 -*-
+"""Webex Admin Audit Events API wrapper.
+
+Copyright (c) 2016-2019 Cisco and/or its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals,
+)
+
+from builtins import *
+
+from past.builtins import basestring
+
+from webexteamssdk.generator_containers import generator_container
+from webexteamssdk.restsession import RestSession
+from webexteamssdk.utils import check_type, dict_from_items_with_values
+
+
+API_ENDPOINT = 'adminAudit/events'
+OBJECT_TYPE = 'admin_audit_event'
+
+
+class AdminAuditEventsAPI(object):
+    """Admin Audit Events API.
+
+    Wraps the Webex Teams Admin Audit Events API and exposes the API as native
+    Python methods that return native Python objects.
+
+    """
+
+    def __init__(self, session, object_factory):
+        """Init a new AdminAuditEventsAPI object with the provided RestSession.
+
+        Args:
+            session(RestSession): The RESTful session object to be used for
+                API calls to the Webex Teams service.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+
+        """
+        check_type(session, RestSession)
+
+        super(AdminAuditEventsAPI, self).__init__()
+
+        self._session = session
+        self._object_factory = object_factory
+
+    @generator_container
+    def list(self, orgId, _from, to, actorId=None, max=100, offset=0,
+             **request_parameters):
+        """List Organizations.
+
+        This method supports Webex Teams's implementation of RFC5988 Web
+        Linking to provide pagination support.  It returns a generator
+        container that incrementally yields all audit events returned by the
+        query.  The generator will automatically request additional 'pages' of
+        responses from Webex as needed until all responses have been returned.
+        The container makes the generator safe for reuse.  A new API call will
+        be made, using the same parameters that were specified when the
+        generator was created, every time a new iterator is requested from the
+        container.
+
+        Args:
+            orgId(basestring): List events in this organization, by ID.
+            _from(basestring): List events which occurred after a specific
+                date and time.
+            to(basestring): List events which occurred before a specific date
+                and time.
+            actorId(basestring): List events performed by this person, by ID.
+            max(int): Limit the maximum number of events in the response. The
+                maximum value is 200.
+            offset(int): Offset from the first result that you want to fetch.
+            **request_parameters: Additional request parameters (provides
+                support for parameters that may be added in the future).
+
+        Returns:
+            GeneratorContainer: A GeneratorContainer which, when iterated,
+            yields the organizations returned by the Webex Teams query.
+
+        Raises:
+            TypeError: If the parameter types are incorrect.
+            ApiError: If the Webex Teams cloud returns an error.
+        """
+        check_type(orgId, basestring)
+        check_type(_from, basestring)
+        check_type(to, basestring)
+        check_type(actorId, basestring, optional=True)
+        check_type(max, int)
+        check_type(offset, int)
+
+        params = dict_from_items_with_values(
+            request_parameters,
+            orgId=orgId,
+            _from=_from,
+            to=to,
+            actorId=actorId,
+            max=max,
+            offset=offset,
+        )
+
+        if _from:
+            params["from"] = params.pop("_from")
+
+        # API request - get items
+        items = self._session.get_items(API_ENDPOINT, params=params)
+
+        # Yield AdminAuditEvent objects created from the returned JSON objects
+        for item in items:
+            yield self._object_factory(OBJECT_TYPE, item)

webexteamssdk/models/immutable.py

@@ -30,20 +30,24 @@
 """
 
 from __future__ import (
-    absolute_import,
-    division,
-    print_function,
-    unicode_literals,
+    absolute_import, absolute_import, division, division,
+    print_function, print_function, unicode_literals, unicode_literals,
 )
 
 from builtins import *
+
 import json
 from collections import defaultdict
 
 from webexteamssdk.utils import json_dict
 from .mixins.access_token import AccessTokenBasicPropertiesMixin
+from .mixins.admin_audit_event import (
+    AdminAuditEventBasicPropertiesMixin,
+    AdminAuditEventDataBasicPropertiesMixin,
+)
 from .mixins.attachment_action import AttachmentActionBasicPropertiesMixin
 from .mixins.event import EventBasicPropertiesMixin
+from .mixins.guest_issuer_token import GuestIssuerTokenBasicPropertiesMixin
 from .mixins.license import LicenseBasicPropertiesMixin
 from .mixins.membership import MembershipBasicPropertiesMixin
 from .mixins.message import MessageBasicPropertiesMixin
@@ -55,7 +59,6 @@
 from .mixins.team_membership import TeamMembershipBasicPropertiesMixin
 from .mixins.webhook import WebhookBasicPropertiesMixin
 from .mixins.webhook_event import WebhookEventBasicPropertiesMixin
-from .mixins.guest_issuer_token import GuestIssuerTokenBasicPropertiesMixin
 
 
 class ImmutableData(object):
@@ -178,6 +181,20 @@ class AccessToken(ImmutableData, AccessTokenBasicPropertiesMixin):
     """Webex Teams Access-Token data model."""
 
 
+class AdminAuditEventData(ImmutableData,
+                          AdminAuditEventDataBasicPropertiesMixin):
+    """Webex Teams Admin Audit Event Data object data model."""
+
+
+class AdminAuditEvent(ImmutableData, AdminAuditEventBasicPropertiesMixin):
+    """Webex Teams Admin Audit Event data model."""
+
+    @property
+    def data(self):
+        """The event resource data."""
+        return AdminAuditEventData(self._json_data.get('data'))
+
+
 class AttachmentAction(ImmutableData, AttachmentActionBasicPropertiesMixin):
     """Webex Attachment Actions data model"""
 
@@ -251,6 +268,7 @@ class GuestIssuerToken(ImmutableData, GuestIssuerTokenBasicPropertiesMixin):
 immutable_data_models = defaultdict(
     lambda: ImmutableData,
     access_token=AccessToken,
+    admin_audit_event=AdminAuditEvent,
     attachment_action=AttachmentAction,
     event=Event,
     license=License,