🔍 Code Extractor

Represents an Azure Active Directory object, serving as the base type for directory entities like users, groups, service principals, and organizational contacts.

Purpose

This class provides methods to interact with Azure Active Directory objects, including checking group memberships, retrieving member objects and groups, and restoring deleted directory objects. It inherits from Entity and provides a foundation for more specific directory entity types in the Microsoft Graph API.

Source Code

class DirectoryObject(Entity):
    """Represents an Azure Active Directory object. The directoryObject type is the base type for many other
    directory entity types."""

    def check_member_objects(self, ids=None):
        """
        Check for membership in a list of group IDs, administrative unit IDs, or directory role IDs, for the IDs of
        the specified user, group, service principal, organizational contact, device, or directory object.

        :param list[str] ids: The unique identifiers for the objects
        """
        return_type = ClientResult(self.context, StringCollection())
        payload = {"ids": StringCollection(ids)}
        qry = ServiceOperationQuery(
            self, "checkMemberObjects", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def get_member_objects(self, security_enabled_only=True):
        """Returns all the groups and directory roles that a user, group, or directory object is a member of.
        This function is transitive.

        :type security_enabled_only: bool"""
        return_type = ClientResult(self.context, StringCollection())
        payload = {"securityEnabledOnly": security_enabled_only}
        qry = ServiceOperationQuery(
            self, "getMemberObjects", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def get_member_groups(self, security_enabled_only=True):
        """Return all the groups that the specified user, group, or directory object is a member of. This function is
        transitive.

        :param bool security_enabled_only: true to specify that only security groups that the entity is a member
            of should be returned; false to specify that all groups and directory roles that the entity is a member
            of should be returned. true can be specified only for users or service principals to return security-enabled
            groups.
        """
        return_type = ClientResult(self.context, StringCollection())
        payload = {"securityEnabledOnly": security_enabled_only}
        qry = ServiceOperationQuery(
            self, "getMemberGroups", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def check_member_groups(self, group_ids=None):
        """Check for membership in the specified list of groups. Returns from the list those groups of which
        the specified group has a direct or transitive membership.

        You can check up to a maximum of 20 groups per request. This function supports Microsoft 365 and other types
        of groups provisioned in Azure AD. Note that Microsoft 365 groups cannot contain groups.
        So membership in a Microsoft 365 group is always direct.

        :param list[str] group_ids: A collection that contains the object IDs of the groups in which to
            check membership. Up to 20 groups may be specified.
        """
        return_type = ClientResult(self.context, StringCollection())
        payload = {"groupIds": group_ids}
        qry = ServiceOperationQuery(
            self, "checkMemberGroups", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def restore(self):
        """
        Restore a recently deleted application, group, servicePrincipal, administrative unit, or user object from
        deleted items. If an item was accidentally deleted, you can fully restore the item. This is not applicable
        to security groups, which are deleted permanently.

        A recently deleted item will remain available for up to 30 days. After 30 days, the item is permanently deleted.
        """
        qry = ServiceOperationQuery(self, "restore")
        self.context.add_query(qry)
        return self

    @property
    def deleted_datetime(self):
        """Date and time when this object was deleted. Always null when the object hasn't been deleted."""
        return self.properties.get("deletedDateTime", datetime.min)

Parameters

Parameter Details

inherited_from_Entity: This class inherits from Entity, which likely provides context and base functionality for API operations. The constructor parameters are inherited from the Entity base class and typically include a context object for API communication.

Return Value

Instantiation returns a DirectoryObject instance. Methods return either ClientResult objects containing StringCollection (for membership and group queries) or self (for the restore method to enable method chaining). The deleted_datetime property returns a datetime object representing when the object was deleted, or datetime.min if not deleted.

Class Interface

Methods

Attributes

Dependencies

• datetime
• office365

Required Imports

from datetime import datetime
from office365.entity import Entity
from office365.runtime.client_result import ClientResult
from office365.runtime.queries.service_operation import ServiceOperationQuery
from office365.runtime.types.collections import StringCollection

Usage Example

# Assuming you have an authenticated context and directory_object instance
from office365.directory.directory_object import DirectoryObject

# Get member groups for a directory object
result = directory_object.get_member_groups(security_enabled_only=True)
context.execute_query()
group_ids = result.value

# Check membership in specific groups
group_ids_to_check = ['group-id-1', 'group-id-2']
membership_result = directory_object.check_member_groups(group_ids=group_ids_to_check)
context.execute_query()
matching_groups = membership_result.value

# Get all member objects (groups and roles)
member_objects = directory_object.get_member_objects(security_enabled_only=False)
context.execute_query()
all_memberships = member_objects.value

# Restore a deleted directory object
directory_object.restore()
context.execute_query()

# Check deleted status
if directory_object.deleted_datetime != datetime.min:
    print(f'Object was deleted on: {directory_object.deleted_datetime}')

Best Practices

• Always call context.execute_query() after invoking methods to execute the queued operations against the Microsoft Graph API
• Use security_enabled_only=True when querying for security groups to filter out distribution lists and Microsoft 365 groups
• The check_member_groups method supports up to 20 groups per request - batch larger requests accordingly
• Deleted items remain available for restoration for 30 days; after that they are permanently deleted (except security groups which are deleted immediately)
• Methods return ClientResult objects that contain the actual data in their 'value' property after query execution
• The restore() method returns self to enable method chaining
• Check the deleted_datetime property before attempting restoration to verify the object is actually deleted
• Ensure proper OAuth scopes are configured for directory read/write operations

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Group 79.5% similar

  Represents an Azure Active Directory (Azure AD) group, which can be an Office 365 group or a security group, providing methods to manage group operations, memberships, and associated resources.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/groups/group.py

• class DirectoryRole 77.7% similar

  Represents an Azure AD directory role (also known as administrator roles) with properties like description, display name, and members.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/role.py

• class Directory 67.5% similar

  Represents a directory of deleted items in Microsoft Graph API, providing access to recently deleted users, groups, applications, and service principals that can be restored within 30 days.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/directory.py

• class User_v3 66.0% similar

  Represents an Azure AD user account. Inherits from directoryObject.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/users/user.py

• class DirectoryRoleTemplate 65.2% similar

  A class representing a directory role template in Microsoft Graph API, which specifies property values for directory roles.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/template.py