FilterUsers-阿里云帮助中心

Filter and query accounts by user attributes.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecd:FilterUsers

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
MaxResults	integer	No	The number of entries to return on each page. If you specify a value greater than 100, the system automatically resets the value to 100.	10
NextToken	string	No	The next token for retrieving the next page of results. You do not need to specify this parameter for the first request. If the number of results exceeds the value of `MaxResults`, the response includes a `NextToken`. Include this token in a subsequent request to retrieve the next page of results.	caeba0bbb2be03f84eb48b699f0a****
Filter	string	No	A string for fuzzy search. This filter matches the user name (`EndUserId`) and email (`Email`). The asterisk () wildcard is supported. For example, if you set this parameter to "am", the query returns all results where the user name or email starts with "a" and ends with "m".	a*m
PropertyFilterParam	array<object>	No	A list of user properties for fuzzy search.
	object	No	A user property for fuzzy search.
PropertyId	integer	No	The property ID.	328
PropertyValueIds	string	No	The property value ID.	1255
PropertyKeyValueFilterParam	array<object>	No	A list of property key and property value pairs.
	object	No	The property key and property value pair.
PropertyKey	string	No	The property key.	job
PropertyValues	string	No	The property value.	dev
IncludeDesktopCount	boolean	No	Specifies whether to return the number of cloud desktops that are assigned to the user. Valid values: true : The number of assigned cloud desktops is returned. false : The number of assigned cloud desktops is not returned.	true
IncludeDesktopGroupCount	boolean	No	Specifies whether to return the number of cloud desktop pools that are assigned to the user. Valid values: true : The number of assigned cloud desktop pools is returned. false : The number of assigned cloud desktop pools is not returned.	false
OrgId	string	No	The organization ID.	org-aliyun-wy-org-id
OwnerType	string	No	The account activation type. Valid values: CreateFromManager : Administrator activation Normal : User activation	Normal
IncludeEndUserIds	array	No
	string	No
ExcludeEndUserIds	array	No	A list of user names (`EndUserId`) to exclude from the results by exact match.
	string	No	The user name (`EndUserId`) to exclude by exact match. The query excludes users with this user name.	tony
OrderParam	object	No	The sorting parameters.
OrderField	string	No	The field by which to sort the results. Valid values: EndUserId : The user name id : The user ID gmt_created : The creation time	id
OrderType	string	No	The sort order for the results. Valid values: ASC : Ascending order DESC : Descending order (default)	DESC
Status	integer	No	Filters the results by user status. Valid values: 0 : Normal 11 : Resigned	0
IsQueryAllSubOrgs	boolean	No	Specifies whether to query all sub-organizations.
IncludeOrgInfo	boolean	No	Specifies whether to include organization information in the response.
IncludeSupportIdps	boolean	No	Specifies whether to include supported sign-in types in the response.
BusinessChannel	string	No	The channel.	ENTERPRISE
FilterMap	object	No
	string	No

Response elements

Element	Type	Description	Example
	object	The data returned.
RequestId	string	The request ID.	1CBAFFAB-B697-4049-A9B1-67E1FC5F****
NextToken	string	The token used to retrieve the next page of results. This parameter is returned when the results are paginated. To retrieve the next page, include this token in your subsequent request.	caeba0bbb2be03f84eb48b699f0a****
Users	array<object>	A list of convenience accounts.
	array<object>	The details of a convenience account.
Id	integer	The user ID.	4205**
EndUserId	string	The username.	alice
Email	string	The email address.	username@example.com
Phone	string	The phone number.	1381111****
Status	integer	The status of the convenience account. Valid values: Valid values: 0 : Active 9 : Locked 11 : Disabled	0
UserSetPropertiesModels	array<object>	A list of user properties.
	array<object>	The details of a user property.
UserId	integer	The user ID associated with the property.	4205**
UserName	string	The username associated with the property.	alice
PropertyId	integer	The ID of the user property.	12
PropertyKey	string	The key of the user property.	department
PropertyType	integer	The type of the user property.	2
PropertyValues	array<object>	The values of the user property.
	object	The details of a user property value.
PropertyValueId	integer	The ID of the user property value.	42
PropertyValue	string	The user property value.	dev
DesktopCount	integer	The number of cloud desktops assigned to the user.	1
ExternalInfo	object	The extended information about the user.
ExternalName	string	The name of the external account mapped to the user.	account
JobNumber	string	The employee ID, student ID, or account number from an external system.	030801
DesktopGroupCount	integer	The number of desktop groups the user is authorized to access. This parameter is returned only if `IncludeDesktopGroupCount` is set to `true`.	2
OwnerType	string	The account ownership type. Valid values: Valid values: CreateFromManager : The account was created by an administrator. Normal : The account was created by the user.	Normal
Remark	string	The remark for the user.	测试专用
IsTenantManager	boolean	Indicates whether the user is a tenant administrator. Valid values: Valid values: true : The user is a tenant administrator. false : The user is not a tenant administrator.	true
EnableAdminAccess	boolean	Indicates whether the user has local administrator permissions. Valid values: Valid values: true : The user has local administrator permissions. false : The user does not have local administrator permissions.	true
RealNickName	string	The user's nickname.	小明
AutoLockTime	string	The date when the account will be automatically locked.	2023-03-03
PasswordExpireDays	integer	The password validity period in days. The value can range from 30 to 365. By default, passwords never expire. After a password expires, the user must change it to log on. Note This feature is in invitation-only preview. To use this feature, submit a ticket.	30
PasswordExpireRestDays	integer	The number of days remaining before the password expires.	10
OrgList	array<object>	A list of organizations to which the user belongs.
	object	The details of an organization to which the user belongs.
OrgId	string	The organization ID.
OrgName	string	The organization name.
OrgNamePath	string	The hierarchical path of organization names.
SupportLoginIdps	array<object>	A list of supported identity providers (IdPs) for logon.
	object	The details of a supported identity provider (IdP).
IdpId	string	The ID of the identity provider (IdP).
IdpName	string	The name of the identity provider (IdP).
Groups	array<object>
	object
GroupId	string
GroupName	string
ResourcePolicyList	array<object>
	object
PolicyId	string
PolicyName	string

Examples

Success response

JSON format

{
  "RequestId": "1CBAFFAB-B697-4049-A9B1-67E1FC5F****",
  "NextToken": "caeba0bbb2be03f84eb48b699f0a****",
  "Users": [
    {
      "Id": 0,
      "EndUserId": "alice",
      "Email": "username@example.com",
      "Phone": "1381111****",
      "Status": 0,
      "UserSetPropertiesModels": [
        {
          "UserId": 0,
          "UserName": "alice",
          "PropertyId": 12,
          "PropertyKey": "department",
          "PropertyType": 2,
          "PropertyValues": [
            {
              "PropertyValueId": 42,
              "PropertyValue": "dev"
            }
          ]
        }
      ],
      "DesktopCount": 1,
      "ExternalInfo": {
        "ExternalName": "account",
        "JobNumber": "030801"
      },
      "DesktopGroupCount": 2,
      "OwnerType": "Normal",
      "Remark": "测试专用",
      "IsTenantManager": true,
      "EnableAdminAccess": true,
      "RealNickName": "小明",
      "AutoLockTime": "2023-03-03",
      "PasswordExpireDays": 30,
      "PasswordExpireRestDays": 10,
      "OrgList": [
        {
          "OrgId": "",
          "OrgName": "",
          "OrgNamePath": ""
        }
      ],
      "SupportLoginIdps": [
        {
          "IdpId": "",
          "IdpName": ""
        }
      ],
      "Groups": [
        {
          "GroupId": "",
          "GroupName": ""
        }
      ],
      "ResourcePolicyList": [
        {
          "PolicyId": "",
          "PolicyName": ""
        }
      ]
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.