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 加密編譯庫。支援 DES、MD5 (雜湊前置字串 $1$)、SHA-256 (雜湊前置字串 $5$) 和 SHA-512 (雜湊前置字串 $6$) 雜湊演算法。

如果您在前置字串中指定回合數，則回合數不得超過 10,000。
isAdmin

boolean

僅供輸出。表示使用者具備超級管理員權限。isAdmin 屬性只能在將使用者設為管理員 ( makeAdmin 方法) 的作業中編輯。如果在使用者 插入或 更新方法中進行編輯，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 資源的類型。使用者資源的值為 admin#directory#user。
etag

string

僅供輸出。資源的 ETag。
emails

value (Value format)

使用者的電子郵件地址清單。資料大小上限為 10 KB。

欄位

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。允許的資料大小上限為 2 KB。

欄位

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)

使用者與其他使用者的關係清單。這個欄位的資料大小上限為 2 KB。詳情請參閱「管理使用者帳戶」。

欄位

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)

使用者的地址清單。資料大小上限為 10 KB。

欄位

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)

使用者所屬機構的清單。資料大小上限為 10 KB。

欄位

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)

使用者的電話號碼清單。允許的資料大小上限為 1 KB。

欄位

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)

使用者的語言清單。允許的資料大小上限為 1 KB。

欄位

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 帳戶欄位 ID。

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

這個帳戶的登入殼層路徑。

posixAccounts[].systemId

string

系統 ID，用於指定使用者名稱或 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)

安全殼層公開金鑰清單。

欄位

sshPublicKeys[].expirationTimeUsec

long

自 Epoch 起算的到期時間 (以微秒為單位)。

sshPublicKeys[].fingerprint

string

SSH 公開金鑰的 SHA-256 指紋。(唯讀)

sshPublicKeys[].key

string

安全殼層公開金鑰。
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)

使用者所在位置的清單。資料大小上限為 10 KB。

欄位

locations[].area

string

以文字表示的地點。以文字表示的地點資訊最能夠顯示使用者的確切工作地點，例如 Mountain View, CA 或 Near Seattle

locations[].buildingId

string

建築物 ID。

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)

使用者的關鍵字清單。允許的資料大小上限為 1 KB。

欄位

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

 即時訊息通訊協定會標示即時訊息網路。這個值可以是自訂網路或標準網路。

可接受的值：
  • aim：AOL Instant Messenger 通訊協定
  • custom_protocol：自訂 IM 網路通訊協定
  • gtalk：Google Talk 通訊協定
  • icq：ICQ 通訊協定
  • jabber：Jabber 通訊協定
  • msn：MSN Messenger 通訊協定
  • net_meeting：Net Meeting 通訊協定
  • qq：QQ 通訊協定
  • skype：Skype 通訊協定
  • yahoo：Yahoo Messenger 通訊協定

ims[].type

string

IM 帳戶類型。如果設為 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。

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

 使用 patch 語義更新使用者。

signOut

 將使用者登出所有網頁和裝置工作階段，並重設他們的登入 Cookie。

undelete

 取消刪除已刪除的使用者。

update

 更新使用者。

watch

 監控使用者清單中的變更。