CloudWatchOmni / Client / search_principals

search_principals

CloudWatchOmni.Client.search_principals(**kwargs)

Searches Identity Center for users and groups in a domain. The domain must be configured with Identity Center.

To grant access to a result, pass its principalId to CreateAccessGrant with a principalType of IDC_USER for a user or IDC_GROUP for a group.

See also: AWS API Documentation

Request Syntax

response = client.search_principals(
    domainId='string',
    searchQuery='string',
    maxResults=123,
    nextToken='string'
)
Parameters:

  • domainId (string) –

    [REQUIRED]

    The ID of the domain to search within.

  • searchQuery (string) –

    [REQUIRED]

    A search term to match against user names, display names, and IDs. Pass * to list all principals. Maximum 128 characters.

  • maxResults (integer) – The maximum number of results to return. Defaults to 10. Valid only when searchQuery is *; other searches reject this parameter and return at most 10 results.

  • nextToken (string) – A token to retrieve the next page of results. Valid only when searchQuery is *; other searches do not paginate and reject this parameter. Tokens expire after 24 hours.

Return type:

dict

Returns:

Response Syntax

{
    'results': [
        {
            'principalId': 'string',
            'principalType': 'USER'|'GROUP',
            'displayName': 'string',
            'userName': 'string',
            'description': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) –

    • results (list) –

      The list of matching principals.

      • (dict) –

        A user or group matched by SearchPrincipals.

        • principalId (string) –

          The unique ID of the principal.

        • principalType (string) –

          Whether the principal is a user or a group.

        • displayName (string) –

          The display name of the principal.

        • userName (string) –

          The user name of the principal. Present for users only.

        • description (string) –

          An optional description of the principal.

    • nextToken (string) –

      A token to retrieve the next page of results, or null if there are no more results.

Exceptions