new types & methods for Teams API

Author: vgrem

examples/reports/get_user_mfa_status.py

@@ -1,3 +1,8 @@
+"""
+Get a list of the authentication methods registered for a user as defined in the userRegistrationDetails object.
+This method doesn't work for disabled users.
+
+"""
 from office365.graph_client import GraphClient
 from tests import test_client_id, test_client_secret, test_tenant
 

office365/communications/onlinemeetings/broadcast_settings.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class BroadcastMeetingSettings(ClientValue):
+    """Represents settings related to a live event in Microsoft Teams."""

office365/communications/onlinemeetings/online_meeting.py

@@ -124,7 +124,7 @@ def video_teleconference_id(self):
     @property
     def recordings(self):
         # type: () -> EntityCollection[CallRecording]
-        """he recordings of an online meeting"""
+        """The recordings of an online meeting"""
         return self.properties.get(
             "recordings",
             EntityCollection(

office365/directory/audit/directory.py

@@ -2,7 +2,9 @@
 from typing import Optional
 
 from office365.directory.audit.activity_initiator import AuditActivityInitiator
+from office365.directory.audit.target_resource import TargetResource
 from office365.entity import Entity
+from office365.runtime.client_value_collection import ClientValueCollection
 
 
 class DirectoryAudit(Entity):
@@ -25,6 +27,14 @@ def activity_display_name(self):
         """
         return self.properties.get("activityDisplayName", None)
 
+    @property
+    def additional_details(self):
+        # type: () -> Optional[dict]
+        """
+        Indicates additional details on the activity.
+        """
+        return self.properties.get("additionalDetails", None)
+
     @property
     def category(self):
         # type: () -> Optional[str]
@@ -69,6 +79,14 @@ def logged_by_service(self):
         """
         return self.properties.get("loggedByService", None)
 
+    @property
+    def result(self):
+        # type: () -> Optional[str]
+        """
+        Indicates the result of the activity. Possible values are: success, failure, timeout, unknownFutureValue.
+        """
+        return self.properties.get("result", None)
+
     @property
     def result_reason(self):
         # type: () -> Optional[str]
@@ -77,11 +95,24 @@ def result_reason(self):
         """
         return self.properties.get("resultReason", None)
 
+    @property
+    def target_resources(self):
+        # type: () -> Optional[str]
+        """
+        Indicates information on which resource was changed due to the activity. Target Resource Type can be User,
+        Device, Directory, App, Role, Group, Policy or Other. Supports $filter (eq) for id and displayName;
+        and $filter (startswith) for displayName.
+        """
+        return self.properties.get(
+            "targetResources", ClientValueCollection(TargetResource)
+        )
+
     def get_property(self, name, default_value=None):
         if default_value is None:
             property_mapping = {
                 "activityDateTime": self.activity_datetime,
                 "initiatedBy": self.initiated_by,
+                "targetResources": self.target_resources,
             }
             default_value = property_mapping.get(name, None)
         return super(DirectoryAudit, self).get_property(name, default_value)

office365/directory/audit/signins/signin.py

@@ -3,8 +3,12 @@
 
 from office365.directory.audit.signins.location import SignInLocation
 from office365.directory.audit.signins.status import SignInStatus
+from office365.directory.policies.applied_conditional_access import (
+    AppliedConditionalAccessPolicy,
+)
 from office365.entity import Entity
 from office365.intune.devices.detail import DeviceDetail
+from office365.runtime.client_value_collection import ClientValueCollection
 
 
 class SignIn(Entity):
@@ -24,6 +28,15 @@ def app_id(self):
         """Unique GUID representing the app ID in the Azure Active Directory."""
         return self.properties.get("appId", None)
 
+    @property
+    def applied_conditional_access_policies(self):
+        # type: () -> Optional[str]
+        """Provides a list of conditional access policies that the corresponding sign-in activity triggers."""
+        return self.properties.get(
+            "appliedConditionalAccessPolicies",
+            ClientValueCollection(AppliedConditionalAccessPolicy),
+        )
+
     @property
     def client_app_used(self):
         # type: () -> Optional[str]
@@ -122,6 +135,7 @@ def status(self):
     def get_property(self, name, default_value=None):
         if default_value is None:
             property_mapping = {
+                "appliedConditionalAccessPolicies": self.applied_conditional_access_policies,
                 "createdDateTime": self.created_datetime,
                 "deviceDetail": self.device_detail,
             }

office365/directory/audit/target_resource.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class TargetResource(ClientValue):
+    """Represents target resource types associated with audit activity."""

office365/directory/identitygovernance/accessreview/instance.py

@@ -0,0 +1,27 @@
+from office365.directory.identitygovernance.accessreview.stages import AccessReviewStageCollection
+from office365.entity import Entity
+from office365.runtime.paths.resource_path import ResourcePath
+
+
+class AccessReviewInstance(Entity):
+    """
+    Represents a Microsoft Entra access review recurrence. If the parent accessReviewScheduleDefinition is a
+    recurring access review, instances represent each recurrence. A review that does not recur will have exactly
+    one instance. Instances also represent each unique group being reviewed in the schedule definition.
+    If a schedule definition reviews multiple groups, each group will have a unique instance for each recurrence.
+
+    Every accessReviewInstance contains a list of decisions that reviewers can take action on.
+    There is one decision per identity being reviewed.
+    """
+
+    @property
+    def stages(self):
+        # type: () -> AccessReviewStageCollection
+        """If the instance has multiple stages, this returns the collection of stages.
+        A new stage will only be created when the previous stage ends"""
+        return self.properties.get(
+            "stages",
+            AccessReviewStageCollection(
+                self.context, ResourcePath("stages", self.resource_path)
+            ),
+        )

office365/directory/identitygovernance/accessreview/stage.py

@@ -0,0 +1,13 @@
+from office365.entity import Entity
+
+
+class AccessReviewStage(Entity):
+    """
+    Represents a stage of a Microsoft Entra access review. If the parent accessReviewScheduleDefinition has defined
+    the stageSettings property, the accessReviewInstance is comprised of up to three subsequent stages.
+    Each stage may have a different set of reviewers who can act on the stage decisions, and settings determining
+    which decisions pass from stage to stage.
+
+    Every accessReviewStage contains a list of decision items for reviewers.
+    There's only one decision per identity being reviewed.
+    """

office365/directory/identitygovernance/accessreview/stages.py

@@ -0,0 +1,9 @@
+from office365.directory.identitygovernance.accessreview.stage import AccessReviewStage
+from office365.entity_collection import EntityCollection
+
+
+class AccessReviewStageCollection(EntityCollection[AccessReviewStage]):
+    """AccessReviewStage collection"""
+
+    def __init__(self, context, resource_path=None):
+        super(AccessReviewStageCollection, self).__init__(context, AccessReviewStage, resource_path)

office365/directory/insights/trending.py

@@ -1,3 +1,7 @@
+from datetime import datetime
+from typing import Optional
+
+from office365.directory.insights.resource_reference import ResourceReference
 from office365.entity import Entity
 from office365.runtime.paths.resource_path import ResourcePath
 
@@ -8,10 +12,31 @@ class Trending(Entity):
     OneDrive files, and files stored on SharePoint team sites can trend around the user.
     """
 
+    @property
+    def last_modified_datetime(self):
+        # type: () -> Optional[datetime]
+        """Gets date and time the item was last modified."""
+        return self.properties.get("lastModifiedDateTime", datetime.min)
+
+    @property
+    def resource_reference(self):
+        # type: () -> ResourceReference
+        """Reference properties of the trending document, such as the url and type of the document."""
+        return self.properties.get("resourceReference", ResourceReference())
+
     @property
     def resource(self):
         """Used for navigating to the trending document."""
         return self.properties.get(
             "resource",
             Entity(self.context, ResourcePath("resource", self.resource_path)),
         )
+
+    def get_property(self, name, default_value=None):
+        if default_value is None:
+            property_mapping = {
+                "lastModifiedDateTime": self.last_modified_datetime,
+                "resourceReference": self.resource_reference,
+            }
+            default_value = property_mapping.get(name, None)
+        return super(Trending, self).get_property(name, default_value)

office365/directory/licenses/assignment_state.py

@@ -18,8 +18,8 @@ def __init__(
         assigned_by_group=None,
         disabled_plans=None,
         error=None,
-        lastUpdatedDateTime=None,
-        skuId=None,
+        last_updated_datetime=None,
+        sku_id=None,
         state=None,
     ):
         """
@@ -31,13 +31,13 @@ def __init__(
              The possible values are CountViolation, MutuallyExclusiveViolation, DependencyViolation,
              ProhibitedInUsageLocationViolation, UniquenessViolation, and Other.
              For more information on how to identify and resolve license assignment errors, see here.
-        :param str skuId: The unique identifier for the SKU. Read-Only.
+        :param str sku_id: The unique identifier for the SKU. Read-Only.
         :param str state: Indicate the current state of this assignment. Read-Only.
              The possible values are Active, ActiveWithError, Disabled, and Error.
         """
         self.assignedByGroup = assigned_by_group
         self.disabledPlans = StringCollection(disabled_plans)
         self.error = error
-        self.lastUpdatedDateTime = lastUpdatedDateTime
-        self.skuId = skuId
+        self.lastUpdatedDateTime = last_updated_datetime
+        self.skuId = sku_id
         self.state = state

office365/directory/permissions/scoped_role_membership.py

@@ -0,0 +1,8 @@
+from office365.entity import Entity
+
+
+class ScopedRoleMembership(Entity):
+    """A scoped-role membership describes a user's membership of a directory role that is further
+    scoped to an Administrative Unit. Scoped-role membership provides a mechanism to allow a tenant-wide company
+    administrator to delegate administrative privileges to a user, to manage users and groups in a subset
+    of the organization."""

office365/directory/policies/applied_conditional_access.py

@@ -0,0 +1,31 @@
+from office365.runtime.client_value import ClientValue
+from office365.runtime.types.collections import StringCollection
+
+
+class AppliedConditionalAccessPolicy(ClientValue):
+    """Indicates the attributes related to applied conditional access policy or policies that are triggered
+    by a sign-in activity.
+
+    The data in this object is returned only for callers with privileges to read conditional access data.
+    For more information, see Permissions for viewing applied conditional access (CA) policies in sign-ins.
+    """
+
+    def __init__(
+        self,
+        display_name=None,
+        enforced_grant_controls=None,
+        enforced_session_controls=None,
+        id_=None,
+        result=None,
+    ):
+        """
+        :param str display_name: Refers to the name of the conditional access policy
+        :param list[str] enforced_grant_controls: Refers to the grant controls enforced by the conditional access policy
+        :param list[str] enforced_session_controls: Refers to the session controls enforced by the conditional
+            access policy
+        """
+        self.displayName = display_name
+        self.enforcedGrantControls = StringCollection(enforced_grant_controls)
+        self.enforcedSessionControls = StringCollection(enforced_session_controls)
+        self.id = id_
+        self.result = result

office365/directory/rolemanagement/role.py

@@ -1,6 +1,8 @@
 from typing import Optional
 
 from office365.directory.object import DirectoryObject
+from office365.directory.permissions.scoped_role_membership import ScopedRoleMembership
+from office365.entity_collection import EntityCollection
 from office365.runtime.paths.resource_path import ResourcePath
 
 
@@ -36,3 +38,16 @@ def members(self):
                 self.context, ResourcePath("members", self.resource_path)
             ),
         )
+
+    @property
+    def scoped_members(self):
+        """Members of this directory role that are scoped to administrative units. """
+
+        return self.properties.get(
+            "scopedMembers",
+            EntityCollection(
+                self.context,
+                ScopedRoleMembership,
+                ResourcePath("scopedMembers", self.resource_path),
+            ),
+        )

office365/reports/internal/queries/create_report_query.py

@@ -1,20 +1,30 @@
+from typing import TYPE_CHECKING
+
 from office365.reports.report import Report
 from office365.runtime.client_result import ClientResult
 from office365.runtime.queries.function import FunctionQuery
 
+if TYPE_CHECKING:
+    from office365.reports.root import ReportRoot
+
 
-def create_report_query(report_root, report_name, period=None):
+def create_report_query(report_root, report_name, period=None, return_stream=False):
+    # type: (ReportRoot, str, str, bool) -> FunctionQuery
     """
     Construct Report query
 
-    :param office365.reports.root.ReportRoot report_root: Report container
+    :param ReportRoot report_root: Report container
     :param str report_name: Report name
     :param str period: Specifies the length of time over which the report is aggregated.
         The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
         Dn where n represents the number of days over which the report is aggregated. Required.
+    :param bool return_stream: If true, return a stream of report data.
     """
     params = {
         "period": period,
     }
-    return_type = ClientResult(report_root.context, Report())
+    if return_stream:
+        return_type = ClientResult(report_root.context, bytes())
+    else:
+        return_type = ClientResult(report_root.context, Report())
     return FunctionQuery(report_root, report_name, params, return_type)

office365/reports/root.py

@@ -89,7 +89,7 @@ def get_email_activity_user_detail(self, period):
             The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
             Dn where n represents the number of days over which the report is aggregated. Required.
         """
-        qry = create_report_query(self, "getEmailActivityUserDetail", period)
+        qry = create_report_query(self, "getEmailActivityUserDetail", period, return_stream=True)
         self.context.add_query(qry)
         return qry.return_type