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,
  "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)

使用者電子郵件地址清單。資料大小上限為 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

帳戶使用者名稱或 UID 適用的系統 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)

安全殼層公開金鑰清單。

欄位

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

如果這是使用者的主要即時通訊帳戶，即時訊息清單中只能有一個項目為 true。

ims[].protocol

string

 即時通訊協定可識別即時通訊網路。值可以是自訂聯播網或標準聯播網。

可接受的值：
  • aim：AOL 即時通訊協定
  • custom_protocol：自訂即時通訊網路通訊協定
  • gtalk：Google Talk 通訊協定
  • icq：ICQ 通訊協定
  • jabber：Jabber 通訊協定
  • msn：MSN Messenger 通訊協定
  • 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

不可變動。訪客的外部電子郵件地址。

方法

createGuest

 建立訪客使用者，並授予部分 Workspace 功能的存取權。

delete

 刪除使用者。

get

 擷取使用者。

insert

 建立使用者。

list

 擷取網域中已刪除的使用者或所有使用者的分頁清單。

makeAdmin

 將使用者設為超級管理員。

patch

 使用 patch 語義更新使用者。

signOut

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

undelete

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

update

 更新使用者。

watch

 監看使用者清單的變更。