REST Resource: users

资源：User

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

JSON 表示法

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, "isGuestUser": boolean, "guestAccountInfo": { object (`GuestAccountInfo`) } }

{
  "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,
  "isGuestUser": boolean,
  "guestAccountInfo": {
    object (GuestAccountInfo)
  }
}

字段

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

仅限输出。表示具有超级用户权限的用户。isAdmin 属性只能在将用户设为管理员操作（makeAdmin 方法）中进行修改。如果在用户 insert 或 update 方法中进行修改，API 服务会忽略相应修改。

isDelegatedAdmin

boolean

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

agreedToTerms

boolean

仅限输出。如果用户已完成初始登录并接受服务条款协议，则此属性为 true。

suspended

boolean

指示用户是否已被中止。

changePasswordAtNextLogin

boolean

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

ipWhitelisted

boolean

如果值为 true，则用户的 IP 地址受已弃用的 IP 地址 allowlist 配置的约束。

name

object (UserName)

包含用户的名字和姓氏，以及只读的 fullName 值。givenName 和 familyName 值中的字符数上限为 60。此外，名称值支持 Unicode/UTF-8 字符，并且可以包含空格、字母 (a-z)、数字 (0-9)、短划线 (-)、正斜线 (/) 和英文句号 (.)。如需详细了解字符使用规则，请参阅管理帮助中心。相应字段允许的数据大小上限为 1 KB。

kind

string

仅限输出。API 资源的类型。对于 Users 资源，该值为 admin#directory#user。

etag

string

仅限输出。资源的 ETag。

emails

value (Value format)

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

字段

emails[].address

string

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

emails[].customType

string

如果电子邮件地址 type 为 custom，则此属性包含自定义值，并且必须进行设置。

emails[].primary

boolean

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

emails[].type

string

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

可接受的值：custom、home、other、work。

externalIds

value (Value format)

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

字段

externalIds[].customType

string

如果外部 ID type 为 custom，则此属性包含自定义值，并且必须设置。

externalIds[].type

string

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

可接受的值：account、custom、customer、login_id、network、organization。

externalIds[].value

string

外部 ID 的值。

relations

value (Value format)

用户与其他用户的关系列表。此字段允许的最大数据大小为 2KB。如需了解详情，请参阅管理用户账号。

字段

relations[].customType

string

如果关系 type 为 custom，则此属性包含自定义值，并且必须设置。

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

如果地址 type 为 custom，则此属性包含自定义值，并且必须设置。

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。

可接受的值：custom、home、other、work。

organizations

value (Value format)

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

字段

organizations[].costCenter

string

用户所在组织的成本中心。

organizations[].customType

string

如果类型的值为“自定义”，则此属性包含自定义类型。

organizations[].department

string

指定组织内的部门，例如 sales 或 engineering。

organizations[].description

string

组织的说明。

organizations[].domain

string

组织所属的网域。

organizations[].fullTimeEquivalent

integer

组织内的全时等效毫百分比（100000 = 100%）。

organizations[].location

string

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

organizations[].name

string

机构的名称。

organizations[].primary

boolean

指示相应组织是否为用户的主要组织。用户只能有一个主要组织。

organizations[].symbol

string

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

organizations[].title

string

用户在组织中的职位。例如，member 或 engineer。

organizations[].type

string

组织的类型。

可接受的值：domain_only、school、unknown、work。

lastLoginTime

string

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

phones

value (Value format)

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

字段

phones[].customType

string

如果电话号码 type 为 custom，则此属性包含自定义值，并且必须设置。

phones[].primary

boolean

如果值为 true，则这是用户的主要电话号码。用户只能有一个主要电话号码。

phones[].type

string

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

可接受的值：assistant、callback、car、company_main、custom、grand_central、home、home_fax、isdn、main、mobile、other、other_fax、pager、radio、telex、tty_tdd、work、work_fax、work_mobile、work_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，则无法设置此属性。允许的值包括 preferred 和 not_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

相应账号的操作系统类型。

可接受的值：linux、unspecified、windows。

posixAccounts[].primary

boolean

如果这是用户在 SystemId 中的主账户。

posixAccounts[].shell

string

相应账号的登录 shell 的路径。

posixAccounts[].systemId

string

账号用户名或 UID 所适用的系统标识符。

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

自纪元以来的过期时间（以微秒为单位）。

sshPublicKeys[].fingerprint

string

SSH 公钥的 SHA-256 指纹。（只读）

sshPublicKeys[].key

string

SSH 公钥。

notes

value (Value format)

以嵌套对象形式呈现的用户备注。

字段

notes.contentType

string

注释的内容类型，可以是纯文本或 HTML。默认值为纯文本。

可接受的值：text_plain、text_html。

notes.value

string

笔记的内容。

websites

value (Value format)

用户的网站列表。

字段

websites[].customType

string

如果网站 type 为 custom，则此属性包含自定义值，并且必须设置。

websites[].primary

boolean

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

websites[].type

string

网站的类型或用途。例如，网站可以标记为 home 或 blog。或者，条目也可以具有 custom 类型。如果设置为 custom，则还必须设置 customType。

可接受的值：app_install_page、blog、custom、ftp、home、home_page、other、profile、reservations、resume、work。

websites[].value

string

网站的网址。

locations

value (Value format)

用户位置信息的列表。允许的最大数据大小为 10KB。

字段

locations[].area

string

文字位置。文字最能准确描述用户的工作地点。例如，Mountain View, CA 或 Near Seattle。

locations[].buildingId

string

建筑标识符。

locations[].customType

string

如果位置 type 为 custom，则此属性包含自定义值，并且必须设置。

locations[].deskCode

string

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

locations[].floorName

string

楼层名称/编号。

locations[].floorSection

string

楼层分区。楼层内更具体的位置。例如，如果某个楼层分为 A、B 和 C 三个分区，此字段将标识其中一个值。

locations[].type

string

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

可接受的值：custom、default、desk。

includeInGlobalAddressList

boolean

表示当网域启用联系人共享功能时，用户的个人资料是否在 Google Workspace 全局地址列表中可见。如需详细了解如何排除用户个人资料，请参阅管理帮助中心。

keywords

value (Value format)

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

字段

keywords[].customType

string

如果关键字 type 为 custom，则此属性包含自定义值，并且必须设置。

keywords[].type

string

每个条目都可以有一个类型，用于指明相应条目的标准类型。

例如，关键字可以是 occupation 或 outlook 类型。除了标准类型外，条目还可以具有 custom 类型，并且可以为其指定任意名称。如果设置为 custom，则还必须设置 customType。

可接受的值：custom、mission、occupation、outlook。

keywords[].value

string

关键字。

deletionTime

string

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

gender

value (Value format)

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

字段

gender.addressMeAs

string

一个直观易懂的字符串，包含人类指代个人资料所有者的正确方式，例如“他/他/他的”或“他们/他们/他们的”。

gender.customGender

string

自定义性别的名称。

gender.type

string

性别类型。

可接受的值：

female
male
other
unknown

thumbnailPhotoEtag

string

仅限输出。用户照片的 ETag（只读）

ims

value (Value format)

用户的即时通讯 (IM) 账号。一个用户账号可以有多个 ims 媒体资源，但只能有一个 ims 媒体资源作为主要即时通讯联系方式。

字段

ims[].customProtocol

string

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

ims[].customType

string

如果 IM type 为 custom，则此属性包含自定义值，并且必须设置。

ims[].im

string

用户的即时通讯网络 ID。

ims[].primary

boolean

如果这是用户的主要即时通讯账号。IM 列表中的条目只能有一个具有 true 值。

ims[].protocol

string

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

可接受的值：

aim：AOL 即时通讯协议
custom_protocol：自定义即时通讯网络协议
gtalk：Google Talk 协议
icq：ICQ 协议
jabber：Jabber 协议
msn：MSN Messenger 协议
net_meeting：Net Meeting 协议
qq：QQ 协议
skype：Skype 协议
yahoo：Yahoo Messenger 协议

ims[].type

string

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

可接受的值：custom、home、other、work。

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。

isGuestUser

boolean

不可变。指示用户是否为访客。

guestAccountInfo

object (GuestAccountInfo)

不可变。与嘉宾相关的其他元数据字段

用户名

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

字段
`fullName`	`string` 通过连接名字和姓氏值形成的用户全名。
`familyName`	`string` 用户的姓氏。创建用户账号时必需。
`givenName`	`string` 用户的名字。创建用户账号时必需。
`displayName`	`string` 用户的显示名称。限制：最多 256 个字符。

GuestAccountInfo

特定于访客用户的账号信息。

JSON 表示法
{ "primaryGuestEmail": string }

字段

字段
`primaryGuestEmail`	`string` 不可变。邀请对象的外部电子邮件地址。

primaryGuestEmail

string

不可变。邀请对象的外部电子邮件地址。

方法
`createGuest`	创建可使用部分 Workspace 功能的访客用户。
`delete`	删除用户。
`get`	检索用户。
`insert`	创建用户。
`list`	检索网域中已删除用户或所有用户的分页列表。
`makeAdmin`	将用户设为超级用户。
`patch`	使用 patch 语义更新用户。
`signOut`	让用户退出所有网页和设备会话，并重置其登录 Cookie。
`undelete`	取消删除已删除的用户。
`update`	更新用户。
`watch`	监听用户列表中的更改。

REST Resource: users

资源：User

用户名

GuestAccountInfo

方法

`createGuest`

`delete`

`get`

`insert`

`list`

`makeAdmin`

`patch`

`signOut`

`undelete`

`update`

`watch`

REST Resource: users 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

资源：User

用户名

GuestAccountInfo

方法

REST Resource: users