🔍 Code Extractor

A SharePoint web service interface class that provides static methods for querying and resolving principals (users, groups) using the People Picker functionality.

Purpose

This class serves as a wrapper around SharePoint's ClientPeoplePickerWebServiceInterface, providing methods to search for principals, resolve user identities, and retrieve entity information. It's designed to work with SharePoint's people picker UI component and claims-based authentication. All methods are static and return ClientResult or PickerEntityInformation objects that can be used to retrieve principal data in JSON format.

Source Code

class ClientPeoplePickerWebServiceInterface(Entity):
    """Specifies an interface that can be used to query principals."""

    @staticmethod
    def get_search_results(
        context,
        search_pattern,
        provider_id=None,
        hierarchy_node_id=None,
        entity_types=None,
    ):
        """
        Specifies a JSON formatted CSOM String of principals found in the search.

        :type context: office365.sharepoint.client_context.ClientContext
        :param str search_pattern: Specifies a pattern used to search for principals.
            The value is implementation-specific.
        :param str provider_id: The identifier of a claims provider.
        :param str hierarchy_node_id: The identifier of a node in the hierarchy. The search MUST be conducted under
            this node.
        :param str entity_types: The type of principals to search for.
        """
        return_type = ClientResult(context, str())
        payload = {
            "searchPattern": search_pattern,
            "providerID": provider_id,
            "hierarchyNodeID": hierarchy_node_id,
            "entityTypes": entity_types,
        }
        svc = ClientPeoplePickerWebServiceInterface(context)
        qry = ServiceOperationQuery(
            svc, "GetSearchResults", None, payload, None, return_type, True
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def get_search_results_by_hierarchy(
        context,
        provider_id=None,
        hierarchy_node_id=None,
        entity_types=None,
        context_url=None,
    ):
        """
        Specifies a JSON formatted CSOM String of principals found in the search grouped by hierarchy.

        :type context: office365.sharepoint.client_context.ClientContext
        :param str provider_id: The identifier of a claims provider.
        :param str hierarchy_node_id: The identifier of a node in the hierarchy. The search MUST be conducted under
            this node.
        :param str entity_types: The type of principals to search for.
        :param str context_url: The URL to use as context when searching for principals.
        """
        return_type = ClientResult(context, str())
        payload = {
            "providerID": provider_id,
            "hierarchyNodeID": hierarchy_node_id,
            "entityTypes": entity_types,
            "contextUrl": context_url,
        }
        svc = ClientPeoplePickerWebServiceInterface(context)
        qry = ServiceOperationQuery(
            svc, "GetSearchResultsByHierarchy", None, payload, None, return_type, True
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def client_people_picker_resolve_user(context, query_string):
        """
        Resolves the principals to a string of JSON representing users in people picker format.

        :param str query_string: Specifies the value to be used in the principal query.
        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context

        """
        return_type = ClientResult(context, str())
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        payload = {
            "queryParams": ClientPeoplePickerQueryParameters(query_string=query_string)
        }
        qry = ServiceOperationQuery(
            binding_type,
            "ClientPeoplePickerResolveUser",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def client_people_picker_search_user(
        context, query_string, maximum_entity_suggestions=100
    ):
        """
        Returns for a string of JSON representing users in people picker format of the specified principals.

        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context
        :param str query_string: Specifies the value to be used in the principal query.
        :param int maximum_entity_suggestions: Specifies the maximum number of principals to be returned by the
        principal query.
        """
        return_type = ClientResult(context, str())
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        params = ClientPeoplePickerQueryParameters(
            query_string=query_string,
            maximum_entity_suggestions=maximum_entity_suggestions,
        )
        payload = {"queryParams": params}
        qry = ServiceOperationQuery(
            binding_type,
            "ClientPeoplePickerSearchUser",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def get_picker_entity_information(context, email_address):
        """
        Gets information of the specified principal.
        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context
        :param str email_address: Specifies the principal for which information is being requested.

        """
        request = PickerEntityInformationRequest(
            email_address=email_address, principal_type=PrincipalType.All
        )
        return_type = PickerEntityInformation(context)
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        payload = {"entityInformationRequest": request}
        qry = ServiceOperationQuery(
            binding_type,
            "GetPickerEntityInformation",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @property
    def entity_type_name(self):
        return "SP.UI.ApplicationPages.ClientPeoplePickerWebServiceInterface"

Parameters

Name	Type	Default	Kind
bases	Entity	-

Parameter Details

context: A ClientContext instance representing the SharePoint client context, required for all operations to communicate with SharePoint services

search_pattern: A string pattern used to search for principals; implementation-specific and typically matches against user names, email addresses, or display names

provider_id: Optional string identifier of a claims provider to limit the search scope to a specific authentication provider

hierarchy_node_id: Optional string identifier of a node in the hierarchy under which the search should be conducted, used for organizational structure filtering

entity_types: Optional string specifying the type of principals to search for (e.g., 'User', 'Group', 'SharePointGroup')

context_url: Optional URL string to use as context when searching for principals, helps scope the search to a specific site or location

query_string: String value to be used in the principal query, typically a partial name or email address to search for

maximum_entity_suggestions: Integer specifying the maximum number of principals to return from the search query, defaults to 100

email_address: String email address of the principal for which detailed information is being requested

Return Value

For search methods (get_search_results, get_search_results_by_hierarchy, client_people_picker_resolve_user, client_people_picker_search_user), returns a ClientResult object containing a string of JSON-formatted principal data. For get_picker_entity_information, returns a PickerEntityInformation object containing detailed information about a specific principal. All return types are deferred execution objects that will be populated when the query is executed through the context.

Class Interface

Methods

Attributes

Name	Type	Description	Scope
entity_type_name	str	The SharePoint entity type name identifier for this web service interface	instance

Dependencies

• office365

Required Imports

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.ui.applicationpages.peoplepicker.web_service_interface import ClientPeoplePickerWebServiceInterface

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.ui.applicationpages.peoplepicker.web_service_interface import ClientPeoplePickerWebServiceInterface

# Initialize SharePoint context
ctx = ClientContext('https://yourtenant.sharepoint.com/sites/yoursite').with_credentials(user_credentials)

# Search for users matching a pattern
result = ClientPeoplePickerWebServiceInterface.get_search_results(
    context=ctx,
    search_pattern='john',
    entity_types='User'
)
ctx.execute_query()
print(result.value)  # JSON string of matching users

# Resolve a specific user
resolved = ClientPeoplePickerWebServiceInterface.client_people_picker_resolve_user(
    context=ctx,
    query_string='john.doe@company.com'
)
ctx.execute_query()
print(resolved.value)  # JSON string of resolved user

# Get detailed entity information
entity_info = ClientPeoplePickerWebServiceInterface.get_picker_entity_information(
    context=ctx,
    email_address='john.doe@company.com'
)
ctx.execute_query()
print(entity_info.entity_data)  # Detailed principal information

Best Practices

• Always call ctx.execute_query() after invoking any method to actually execute the query and populate the return value
• All methods are static, so no instance creation is needed - call methods directly on the class
• The class internally creates instances for query binding but these are not exposed to the caller
• Return values are deferred execution objects - access the .value property only after execute_query()
• Use appropriate entity_types parameter to filter results and improve performance
• Consider setting maximum_entity_suggestions to limit result sets for better performance
• Ensure the ClientContext has appropriate permissions before querying principals
• The JSON strings returned contain SharePoint-specific principal formats - parse accordingly
• Use get_picker_entity_information for detailed information about a known principal
• Use search methods for discovering principals based on partial information

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class PickerEntityInformation 71.5% similar

  A class representing additional information about a principal (user, group, or security entity) in SharePoint's people picker system.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/ui/applicationpages/peoplepicker/entity_information.py

• class PeoplePickerQuerySettings 71.4% similar

  A data class representing additional settings for SharePoint principal queries, specifically for people picker operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/ui/applicationpages/peoplepicker/query_settings.py

• class PickerSettings 66.7% similar

  Configuration settings class for the SharePoint client people picker control, providing access to picker behavior settings and query configurations.

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

• class PickerEntityInformationRequest 66.3% similar

  A data transfer object (DTO) class that represents a request for retrieving picker entity information in SharePoint, encapsulating principal identification parameters.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/ui/applicationpages/peoplepicker/entity_information_request.py

• class SharePointSharingSettings 65.9% similar

  A class representing SharePoint UI-specific sharing settings, providing access to people picker properties and other sharing-related configurations.

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

class ClientPeoplePickerWebServiceInterface(Entity):
    """Specifies an interface that can be used to query principals."""

    @staticmethod
    def get_search_results(
        context,
        search_pattern,
        provider_id=None,
        hierarchy_node_id=None,
        entity_types=None,
    ):
        """
        Specifies a JSON formatted CSOM String of principals found in the search.

        :type context: office365.sharepoint.client_context.ClientContext
        :param str search_pattern: Specifies a pattern used to search for principals.
            The value is implementation-specific.
        :param str provider_id: The identifier of a claims provider.
        :param str hierarchy_node_id: The identifier of a node in the hierarchy. The search MUST be conducted under
            this node.
        :param str entity_types: The type of principals to search for.
        """
        return_type = ClientResult(context, str())
        payload = {
            "searchPattern": search_pattern,
            "providerID": provider_id,
            "hierarchyNodeID": hierarchy_node_id,
            "entityTypes": entity_types,
        }
        svc = ClientPeoplePickerWebServiceInterface(context)
        qry = ServiceOperationQuery(
            svc, "GetSearchResults", None, payload, None, return_type, True
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def get_search_results_by_hierarchy(
        context,
        provider_id=None,
        hierarchy_node_id=None,
        entity_types=None,
        context_url=None,
    ):
        """
        Specifies a JSON formatted CSOM String of principals found in the search grouped by hierarchy.

        :type context: office365.sharepoint.client_context.ClientContext
        :param str provider_id: The identifier of a claims provider.
        :param str hierarchy_node_id: The identifier of a node in the hierarchy. The search MUST be conducted under
            this node.
        :param str entity_types: The type of principals to search for.
        :param str context_url: The URL to use as context when searching for principals.
        """
        return_type = ClientResult(context, str())
        payload = {
            "providerID": provider_id,
            "hierarchyNodeID": hierarchy_node_id,
            "entityTypes": entity_types,
            "contextUrl": context_url,
        }
        svc = ClientPeoplePickerWebServiceInterface(context)
        qry = ServiceOperationQuery(
            svc, "GetSearchResultsByHierarchy", None, payload, None, return_type, True
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def client_people_picker_resolve_user(context, query_string):
        """
        Resolves the principals to a string of JSON representing users in people picker format.

        :param str query_string: Specifies the value to be used in the principal query.
        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context

        """
        return_type = ClientResult(context, str())
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        payload = {
            "queryParams": ClientPeoplePickerQueryParameters(query_string=query_string)
        }
        qry = ServiceOperationQuery(
            binding_type,
            "ClientPeoplePickerResolveUser",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def client_people_picker_search_user(
        context, query_string, maximum_entity_suggestions=100
    ):
        """
        Returns for a string of JSON representing users in people picker format of the specified principals.

        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context
        :param str query_string: Specifies the value to be used in the principal query.
        :param int maximum_entity_suggestions: Specifies the maximum number of principals to be returned by the
        principal query.
        """
        return_type = ClientResult(context, str())
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        params = ClientPeoplePickerQueryParameters(
            query_string=query_string,
            maximum_entity_suggestions=maximum_entity_suggestions,
        )
        payload = {"queryParams": params}
        qry = ServiceOperationQuery(
            binding_type,
            "ClientPeoplePickerSearchUser",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @staticmethod
    def get_picker_entity_information(context, email_address):
        """
        Gets information of the specified principal.
        :param office365.sharepoint.client_context.ClientContext context: SharePoint client context
        :param str email_address: Specifies the principal for which information is being requested.

        """
        request = PickerEntityInformationRequest(
            email_address=email_address, principal_type=PrincipalType.All
        )
        return_type = PickerEntityInformation(context)
        binding_type = ClientPeoplePickerWebServiceInterface(context)
        payload = {"entityInformationRequest": request}
        qry = ServiceOperationQuery(
            binding_type,
            "GetPickerEntityInformation",
            None,
            payload,
            None,
            return_type,
            True,
        )
        context.add_query(qry)
        return return_type

    @property
    def entity_type_name(self):
        return "SP.UI.ApplicationPages.ClientPeoplePickerWebServiceInterface"