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

僅供輸出。指出具備超級管理員權限的使用者。只能在「將使用者設為管理員」作業 ( 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)、連字號 (-)、正斜線 (/) 和半形句號 (.)。如要進一步瞭解字元使用規則,請參閱管理說明中心。這個欄位的資料大小上限為 1 KB。

kind

string

僅供輸出。API 資源的類型。如果是「使用者」資源,這個值為 admin#directory#user

etag

string

僅供輸出。資源的 ETag。

emails

value (Value format)

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

Fields

emails[].address

string

使用者的電子郵件地址。也可做為電子郵件 ID。這個值可以是使用者的主要電子郵件地址或別名。

emails[].customType

string

如果電子郵件地址 typecustom,這個屬性就會包含自訂值,必須設定。

emails[].primary

boolean

表示這是使用者的主要電子郵件地址。只能將一個項目標示為主要項目。

emails[].type

string

電子郵件帳戶的類型。如果設為 custom,則必須一併設定 customType

可接受的值:customhomeotherwork

externalIds

value (Value format)

使用者的外部 ID 清單,例如員工或網路 ID。允許的資料大小上限為 2 KB。

Fields

externalIds[].customType

string

如果外部 ID typecustom,則這個屬性含有自訂值,必須設定。

externalIds[].type

string

外部 ID 的類型。如果設為 custom,則必須一併設定 customType

可接受的值:accountcustomcustomerlogin_idnetworkorganization

externalIds[].value

string

外部 ID 的值。

relations

value (Value format)

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

Fields

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。

Fields

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)

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

Fields

organizations[].costCenter

string

使用者機構的成本中心。

organizations[].customType

string

如果類型的值為自訂,則此屬性會包含自訂類型。

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)

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

Fields

phones[].customType

string

如果電話號碼 typecustom,則此屬性包含必須設定的自訂值。

phones[].primary

boolean

如為 true,這就會是使用者的主要電話號碼。每位使用者只能有一個主要電話號碼。

phones[].type

string

電話號碼類型。如果設為 custom,必須一併設定 customType

可接受的值如下:assistantcallbackcarcompany_maingrand_centralhomehome_faxisdnmainmobileotherother_faxpagerradiotty_tddtelextty_tdd、。customworkwork_faxwork_mobilework_pager

phones[].value

string

使用者可理解的電話號碼。可以使用任何電話號碼格式。

suspensionReason

string

僅供輸出。瞭解使用者的帳戶因管理員或 Google 在停權時遭到停權的原因。只有在 suspended 屬性為 true 時,才會傳回屬性。

thumbnailPhotoUrl

string

僅供輸出。使用者個人資料相片的網址。這個網址可能是臨時或私人網址,

languages

value (Value format)

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

Fields

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 帳戶資訊清單。

Fields

posixAccounts[].accountId

string

POSIX 帳戶欄位 ID。

posixAccounts[].gecos

string

這個帳戶的 GECOS (使用者資訊)

posixAccounts[].gid

unsigned long

預設的群組 ID

posixAccounts[].homeDirectory

string

這個帳戶的主目錄路徑。

posixAccounts[].operatingSystemType

string

此帳戶的作業系統類型。

可接受的值:linuxunspecifiedwindows

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)

SSH 公開金鑰清單。

Fields

sshPublicKeys[].expirationTimeUsec

long

到期時間,以 Epoch 紀元時間起算的微秒為單位。

sshPublicKeys[].fingerprint

string

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

sshPublicKeys[].key

string

SSH 公開金鑰。

notes

value (Value format)

將使用者做為巢狀物件附註。

Fields

notes.contentType

string

附註的內容類型,純文字或 HTML。預設值為純文字。

可接受的值:text_plaintext_html

notes.value

string

附註內容。

websites

value (Value format)

使用者的網站清單。

Fields

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)

使用者的營業地點清單。允許的資料大小上限為 10 KB。

Fields

locations[].area

string

文字位置。這對顯示地點非常有用。例如 Mountain View, CANear Seattle

locations[].buildingId

string

建築物 ID。

locations[].customType

string

如果位置 typecustom,則這個屬性含有自訂值,必須設定。

locations[].deskCode

string

個別辦公桌位置的最具體文字代碼。

locations[].floorName

string

樓層名稱/號碼。

locations[].floorSection

string

樓層。地板內更精確的地點。舉例來說,如果樓層是 ABC 區段,則這個欄位會標示其中一個值。

locations[].type

string

地區類型。如果設為 custom,則必須一併設定 customType

可接受的值:customdefaultdesk

includeInGlobalAddressList

boolean

表示如果網域已啟用聯絡人共用功能,Google Workspace 全域通訊清單就會顯示使用者的個人資料。如要進一步瞭解如何排除使用者個人資料,請參閱管理說明中心

keywords

value (Value format)

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

Fields

keywords[].customType

string

如果關鍵字 typecustom,則這個屬性含有自訂值,必須設定。

keywords[].type

string

每個項目都可以擁有一個類型,表示該項目的標準類型。

舉例來說,關鍵字可以是 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)

包含使用者性別的巢狀物件。這個欄位的資料大小上限為 1 KB。

Fields

gender.addressMeAs

string

這個人類可讀的字串,含有使用者以適當的方式稱呼個人資料擁有者,例如「he/him/his」或「your/them/their」。

gender.customGender

string

自訂性別的名稱。

gender.type

string

性別類型。

可接受的值:
  • female
  • male
  • other
  • unknown

thumbnailPhotoEtag

string

僅供輸出。使用者相片的 ETag (唯讀)

ims

value (Value format)

使用者的即時 Messenger (IM) 帳戶。一個使用者帳戶可以有多個 ims 資源,但只能將其中一個 ims 資源設為主要的即時通訊聯絡人。

Fields

ims[].customProtocol

string

如果通訊協定值為 custom_protocol,此屬性會保留自訂通訊協定的字串。

ims[].customType

string

如果 IM typecustom,則這個屬性含有自訂值,必須設定。

ims[].im

string

使用者的 IM 網路 ID。

ims[].primary

boolean

如果這是使用者的主要 IM。即時訊息清單中只有一個項目的值只能設為 true。

ims[].protocol

string

IM 通訊協定可識別 IM 網路。這個值可以是自訂網路或標準網路。

可接受的值:
  • aim:AOL 即時傳訊通訊協定
  • 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

即時通訊帳戶類型。如果設為 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

使用 Patch 語意更新使用者。

signOut

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

undelete

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

update

更新使用者。

watch

監控使用者名單的變更。