REST Resource: users

资源:User

借助 Directory API,您可以创建和管理帐号的用户、用户别名和用户 Google 个人资料照片。如需详细了解常见任务,请参阅用户帐号开发者指南用户别名开发者指南

JSON 表示法
{
  "id": string,
  "primaryEmail": string,
  "password": value,
  "hashFunction": string,
  "isAdmin": boolean,
  "isDelegatedAdmin": boolean,
  "agreedToTerms": boolean,
  "suspended": boolean,
  "changePasswordAtNextLogin": boolean,
  "ipWhitelisted": boolean,
  "name": {
    object (UserName)
  },
  "kind": string,
  "etag": string,
  "emails": value,
  "externalIds": value,
  "relations": value,
  "aliases": [
    string
  ],
  "isMailboxSetup": boolean,
  "customerId": string,
  "addresses": value,
  "organizations": value,
  "lastLoginTime": string,
  "phones": value,
  "suspensionReason": string,
  "thumbnailPhotoUrl": string,
  "languages": value,
  "posixAccounts": value,
  "creationTime": string,
  "nonEditableAliases": [
    string
  ],
  "sshPublicKeys": value,
  "notes": value,
  "websites": value,
  "locations": value,
  "includeInGlobalAddressList": boolean,
  "keywords": value,
  "deletionTime": string,
  "gender": value,
  "thumbnailPhotoEtag": string,
  "ims": value,
  "customSchemas": value,
  "isEnrolledIn2Sv": boolean,
  "isEnforcedIn2Sv": boolean,
  "archived": boolean,
  "orgUnitPath": string,
  "recoveryEmail": string,
  "recoveryPhone": string
}
字段
id

string

用户的唯一 ID。用户 id 可用作用户请求 URI 的 userKey

primaryEmail

string

用户的主电子邮件地址。在创建用户账号的请求中,必须使用此属性。primaryEmail必须是唯一的,并且不能是其他用户的别名。

password

value (Value format)

存储用户帐号的密码。创建用户帐号时,需要提供用户的密码值。在更新用户时,此字段是可选的,只有在用户更新帐号密码时才应提供。API 的响应正文中绝不会返回密码值。

密码可以包含 ASCII 字符的任意组合,并且长度必须介于 8-100 个字符之间。

我们建议您以十六进制编码哈希值的形式发送 password 参数,并相应地设置 hashFunction。如果指定了 hashFunction,则密码必须是有效的哈希键。

hashFunction

string

存储 password 属性的哈希格式。允许使用以下 hashFunction 值:

  • MD5 - 接受简单的十六进制编码值。
  • SHA-1 - 接受简单的十六进制编码值。
  • crypt - 符合 C crypt 库。支持 DES、MD5(哈希前缀 $1$)、SHA-256(哈希前缀 $5$)和 SHA-512(哈希前缀 $6$)哈希算法。

如果将轮数指定为前缀的一部分,则取整值不得超过 10,000。

isAdmin

boolean

仅供输出。表示具有超级用户权限的用户。只能在让用户成为管理员操作(makeAdmin 方法)中修改 isAdmin 属性。如果您在用户执行的 insertupdate 方法中进行了修改,则 API 服务会忽略该修改。

isDelegatedAdmin

boolean

仅供输出。指明用户是否为委派管理员。
委派管理员受 API 支持,但无法创建或取消删除用户,也无法将用户设为管理员。API 服务会忽略这些请求。
管理员的角色和权限是通过管理控制台分配的。

agreedToTerms

boolean

仅供输出。如果用户完成首次登录并接受服务条款协议,则此媒体资源为true

suspended

boolean

指明用户是否已暂停。

changePasswordAtNextLogin

boolean

指明用户是否在下次登录时必须更改密码。如果用户通过第三方身份提供方登录,则此设置不适用。

ipWhitelisted

boolean

如果为 true,则表示用户的 IP 地址遵循已弃用的 IP 地址 allowlist 配置。

name

object (UserName)

保存用户的给定名字和姓氏,以及只读 fullName 值。givenNamefamilyName 值最多可包含 60 个字符。此外,名称值支持 Unicode/UTF-8 字符,可以包含空格、字母 (a-z)、数字 (0-9)、短划线 (-)、正斜杠 (/) 和句点 (.)。要详细了解字符使用规则,请访问管理帮助中心。此字段允许的数据大小上限为 1KB。

kind

string

仅供输出。API 资源的类型。对于用户资源,该值为 admin#directory#user

etag

string

仅供输出。资源的 ETag。

emails

value (Value format)

用户的电子邮件地址列表。允许的数据大小上限为 10KB。

字段

emails[].address

string

用户的电子邮件地址。也用作电子邮件 ID。此值可以是用户的主电子邮件地址或别名。

emails[].customType

string

如果电子邮件地址 typecustom,则此属性包含自定义值,并且必须设置。

emails[].primary

boolean

指明这是否是用户的主电子邮件地址。只能将一个条目标记为主要条目。

emails[].type

string

电子邮件帐号的类型。如果设为 custom,则还必须设置 customType

可接受的值:customhomeotherwork

externalIds

value (Value format)

该用户的外部 ID(例如员工或网络 ID)的列表。允许的数据大小上限为 2KB。

字段

externalIds[].customType

string

如果外部 ID typecustom,则此属性包含自定义值,并且必须设置。

externalIds[].type

string

外部 ID 的类型。如果设为 custom,还必须设置 customType

可接受的值:accountcustomcustomerlogin_idnetworkorganization

externalIds[].value

string

外部 ID 的值。

relations

value (Value format)

用户与其他用户的关系列表。此字段允许的数据大小上限为 2KB。有关详情,请参阅管理用户帐号

字段

relations[].customType

string

如果关系 typecustom,则此属性包含自定义值,并且必须设置。

relations[].type

string

关系的类型。如果设为 custom,则还必须设置 customType

可接受以下值:
  • admin_assistant
  • assistant
  • brother
  • child
  • custom
  • domestic_partner
  • dotted_line_manager
  • exec_assistant
  • father
  • friend
  • manager
  • mother
  • parent
  • partner
  • referred_by
  • relative
  • sister
  • spouse

relations[].value

string

与用户相关的人员的电子邮件地址。

aliases[]

string

仅供输出。用户的别名电子邮件地址列表。

isMailboxSetup

boolean

仅供输出。指明用户的 Google 邮箱是否已创建。仅当用户已分配 Gmail 许可时,此资源才适用。

customerId

string

仅供输出。客户 ID,用于检索所有账号用户
您可以使用别名 my_customer 代表自己账号的 customerId
作为转销商管理员,您可以使用转销客户账号的 customerId。要获取 customerId,请在 users.list 请求的 domain 参数中使用帐号的主域名。

addresses

value (Value format)

用户地址的列表。允许的数据大小上限为 10KB。

字段

addresses[].country

string

国家/地区。

addresses[].countryCode

string

国家/地区代码。使用 ISO 3166-1 标准。

addresses[].customType

string

如果地址 typecustom,则此属性包含自定义值,并且必须设置。

addresses[].extendedAddress

string

用于扩展地址,例如包含子区域的地址。

addresses[].formatted

string

完整的非结构化邮政地址。这不会与结构化地址字段同步。包括以下属性:街道地址、邮政信箱、城市、州/省/自治区/直辖市、邮政编码、国家/地区。

addresses[].locality

string

地址所在的城镇或城市。

addresses[].poBox

string

邮政信箱(如果有)。

addresses[].postalCode

string

邮政编码(如果适用)。

addresses[].primary

boolean

如果这是您的主要地址。地址列表只能包含一个主要地址。

addresses[].region

string

省/直辖市/自治区的缩写。

addresses[].sourceIsStructured

boolean

指明用户提供的地址是否带有格式。目前不支持带有格式的地址。

addresses[].streetAddress

string

街道地址,例如 1600 Amphitheatre Parkway。字符串内的空格将被忽略;但是换行符很重要。

addresses[].type

string

地址类型。如果设为 custom,则还必须设置 customType

可接受的值:customhomeotherwork

organizations

value (Value format)

用户所属的组织的列表。允许的数据大小上限为 10KB。

字段

organizations[].costCenter

string

用户组织的成本中心。

organizations[].customType

string

如果 type 的值为 custom,则该属性包含自定义类型。

organizations[].department

string

指定组织内的部门,如 salesengineering

organizations[].description

string

组织的说明。

organizations[].domain

string

组织所属的网域。

organizations[].fullTimeEquivalent

integer

组织内等效的全日制工时百分比 (100,000 = 100%)。

organizations[].location

string

组织的实际位置。该地址无需是完全限定地址。

organizations[].name

string

机构的名称。

organizations[].primary

boolean

指明这是否是用户的主要组织。一位用户只能有一个主要组织。

organizations[].symbol

string

组织的文本字符串符号。例如,Google 的文本符号为 GOOG

organizations[].title

string

用户在组织中的职位。例如,memberengineer

organizations[].type

string

组织的类型。

可接受的值:domain_onlyschoolunknownwork

lastLoginTime

string

仅供输出。用户上次登录用户账号的时间。该值采用 ISO 8601 日期和时间格式。时间是完整日期加时、分、秒,格式为 YYYY-MM-DDThh:mm:ssTZD。例如 2010-04-05T17:30:04+01:00

phones

value (Value format)

用户的电话号码列表。允许的数据大小上限为 1KB。

字段

phones[].customType

string

如果电话号码 typecustom,则此属性包含自定义值,并且必须设置。

phones[].primary

boolean

如果为 true,则为用户的主电话号码。一位用户只能有一个主要电话号码。

phones[].type

string

电话号码的类型。如果设为 custom,还必须设置 customType

可接受的值:assistantcallbackcarcompany_maincustomgrand_centralhomehome_faxisdnmainmobileotherother_faxpagerradiotelex
tty_tdd、{1.}、{1workwork_faxwork_mobilework_pager

phones[].value

string

人类可读的电话号码。它可以是任何电话号码格式。

suspensionReason

string

仅供输出。包含管理员或 Google 在暂停时暂停用户帐号的原因。仅当 suspended 属性为 true 时,系统才会返回该属性。

thumbnailPhotoUrl

string

仅供输出。用户的个人资料照片的网址。该网址可能是临时网址或私有网址。

languages

value (Value format)

用户所用语言的列表。允许的数据大小上限为 1KB。

字段

languages[].customLanguage

string

其他语言。如果没有相应的 ISO 639 语言代码,用户可以提供自己的语言名称。如果已设置此参数,就无法设置 languageCode

languages[].languageCode

string

语言的 ISO 639 字符串表示。如需查看受支持代码的列表,请参阅语言代码。API 可接受受支持集合之外的有效语言代码,但可能会导致意外行为。非法值会导致 SchemaException。如果已设置此参数,就无法设置 customLanguage

languages[].preference

string

可选。如果存在,则用于控制指定的 languageCode 是否为用户的首选语言。如果已设置 customLanguage,则无法进行此设置。允许的值为 preferrednot_preferred

posixAccounts

value (Value format)

用户的 POSIX 帐号信息列表。

字段

posixAccounts[].accountId

string

POSIX 帐号字段标识符。

posixAccounts[].gecos

string

此帐号的 GECOS(用户信息)

posixAccounts[].gid

unsigned long

默认群组 ID

posixAccounts[].homeDirectory

string

此帐号的主目录的路径。

posixAccounts[].operatingSystemType

string

此帐号的操作系统类型。

可接受的值:linuxunspecifiedwindows

posixAccounts[].primary

boolean

如果这是系统 ID 内用户的主账号。

posixAccounts[].shell

string

此帐号的登录 Shell 的路径。

posixAccounts[].systemId

string

“用户名”或“用户 ID”所应用到的系统标识符。

posixAccounts[].uid

unsigned long

符合 POSIX 标准的用户 ID。

posixAccounts[].username

string

帐号的用户名。

creationTime

string

仅供输出。用户帐号的创建时间。该值采用 ISO 8601 日期和时间格式。时间是完整日期加时、分、秒,格式为 YYYY-MM-DDThh:mm:ssTZD。例如 2010-04-05T17:30:04+01:00

nonEditableAliases[]

string

仅供输出。用户不可修改的别名电子邮件地址列表。这些网域通常在帐号的主域名或子网域之外。

sshPublicKeys

value (Value format)

SSH 公钥列表。

字段

sshPublicKeys[].expirationTimeUsec

long

到期时间(以微秒为单位,从 Epoch 起算)。

sshPublicKeys[].fingerprint

string

SSH 公钥的 SHA-256 指纹。(只读)

sshPublicKeys[].key

string

SSH 公钥。

notes

value (Value format)

作为嵌套对象的用户备注。

字段

notes.contentType

string

备注的内容类型(纯文本或 HTML)。默认值为纯文本。

可接受的值:text_plaintext_html

notes.value

string

备注内容。

websites

value (Value format)

用户网站的列表。

字段

websites[].customType

string

如果网站 typecustom,则此属性包含自定义值,并且必须设置。

websites[].primary

boolean

如果为 true,则表示用户的主要网站。

websites[].type

string

网站的类型或目的。例如,网站可能会被标记为 homeblog。或者,条目可以具有 custom 类型。如果设为 custom,还必须设置 customType

可接受的值:app_install_pageblogcustomftphomehome_pageotherprofilereservationsresumework

websites[].value

string

网站的网址。

locations

value (Value format)

用户所在位置的列表。允许的数据大小上限为 10KB。

字段

locations[].area

string

文字位置。这最有助于显示目的,以简明描述位置。例如,Mountain View, CANear Seattle

locations[].buildingId

string

建筑物标识符。

locations[].customType

string

如果 type 位置为 custom,则此属性包含自定义值,必须进行设置。

locations[].deskCode

string

单个办公桌位置的最具体文本代码。

locations[].floorName

string

楼层名称/编号。

locations[].floorSection

string

楼层分区。更具体地在楼层内的位置。例如,如果楼层分为 ABC 部分,则此字段将标识其中一个值。

locations[].type

string

位置类型。如果设为 custom,则还必须设置 customType

可接受的值:customdefaultdesk

includeInGlobalAddressList

boolean

指明在为网域启用联系人共享功能后,用户的个人资料是否显示在 Google Workspace 全局地址列表中。要详细了解如何排除用户个人资料,请参阅管理帮助中心

keywords

value (Value format)

用户关键字列表。允许的数据大小上限为 1KB。

字段

keywords[].customType

string

如果关键字 typecustom,则此属性包含自定义值,并且必须设置。

keywords[].type

string

每个条目都可以有一个 type,用于表示该条目的标准类型。

例如,关键字的类型可以是 occupationoutlook。除了标准类型之外,条目还可以具有 custom 类型,并且可以为其指定任何名称。如果设为 custom,则还必须设置 customType

可接受的值:custommissionoccupationoutlook

keywords[].value

string

关键字。

deletionTime

string

仅供输出。删除用户帐号的时间。该值采用 ISO 8601 日期和时间格式。时间是完整日期加时、分、秒,格式为 YYYY-MM-DDThh:mm:ssTZD。例如:2010-04-05T17:30:04+01:00

gender

value (Value format)

包含用户性别的嵌套对象。此字段允许的数据大小上限为 1KB。

字段

gender.addressMeAs

string

人类可读的字符串,其中包含人类指代个人资料所有者的正确方式,例如“he/him/his”或“them/them/them”。

gender.customGender

string

自定义性别的名称。

gender.type

string

性别的类型。

可接受以下值:
  • female
  • male
  • other
  • unknown

thumbnailPhotoEtag

string

仅供输出。用户照片的 ETag(只读)

ims

value (Value format)

用户的 Instant Messenger (IM) 帐号。一个用户帐号可以有多个 ims 属性,但这些 ims 属性中只能有一个可以作为主要即时通讯联系人。

字段

ims[].customProtocol

string

如果协议值为 custom_protocol,则此属性会保留自定义协议的字符串。

ims[].customType

string

如果 IM typecustom,则说明此属性包含自定义值,必须设置。

ims[].im

string

用户的 IM 网络 ID。

ims[].primary

boolean

如果这是该用户的主要即时通讯信息。即时通讯列表中只能有一个条目的值为 true。

ims[].protocol

string

IM 协议用于标识 IM 网络。该值可以是自定义网络或标准网络。

可接受以下值:
  • aim:AOL Instant Messenger 协议
  • custom_protocol:自定义 IM 网络协议
  • gtalk:Google Talk 协议
  • icq:ICQ 协议
  • jabber:Jabber 协议
  • msn:MSN Messenger 协议
  • net_meeting:网络会议协议
  • qq:QQ 协议
  • skype:Skype 协议
  • yahoo:Yahoo Messenger 协议

ims[].type

string

即时通讯账号的类型。如果设为 custom,则还必须设置 customType

可接受的值:customhomeotherwork

customSchemas

value (Value format)

用户的自定义字段。键是 schemaName,其值为 'fieldName': 'field_value'

  • customSchemas.(key) 是一个嵌套对象。
  • customSchemas.(key).(key) 可以是任何值。
isEnrolledIn2Sv

boolean

仅供输出。已注册两步验证(只读)

isEnforcedIn2Sv

boolean

仅供输出。是否已强制执行两步验证(只读)

archived

boolean

指明用户是否已归档。

orgUnitPath

string

与用户关联的上级组织的完整路径。如果父级组织是顶级组织,则以正斜杠 (/) 表示。

recoveryEmail

string

用户的辅助邮箱。

recoveryPhone

string

用户的辅助电话号码。电话号码必须采用 E.164 格式,以加号 (+) 开头。示例:+16506661212

UserName

JSON 表示法
{
  "fullName": string,
  "familyName": string,
  "givenName": string,
  "displayName": string
}
字段
fullName

string

通过将名字和姓氏值串联形成的用户全名。

familyName

string

用户的姓氏。创建用户账号时必填。

givenName

string

用户的名字。创建用户账号时必填。

displayName

string

用户的显示名。限制:最多 256 个字符。

方法

delete

删除用户。

get

检索用户。

insert

创建用户。

list

检索已删除用户或网域中所有用户的分页列表。

makeAdmin

使用户成为超级用户。

patch

使用补丁语义更新用户。

signOut

让用户退出所有网页会话和设备会话,并重置其登录 Cookie。

undelete

恢复已删除的用户。

update

更新用户。

watch

监控用户列表的变化。