本頁面由 Cloud Translation API 翻譯而成。

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 }

{
  "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 方法) 中編輯。若是在使用者 insert 或 update 方法中編輯的，API 服務會忽略該編輯動作。

isDelegatedAdmin

boolean

僅供輸出。指出使用者是否為委派管理員。
API 支援委派的管理員，但無法建立或取消刪除使用者，或設為使用者管理員。API 服務會忽略這些要求。
管理員的角色和權限是透過管理控制台指派。

agreedToTerms

boolean

僅供輸出。如果使用者已完成初始登入程序並接受《服務條款》協議，這個屬性就會是 true。

suspended

boolean

指出使用者是否遭到停權。

changePasswordAtNextLogin

boolean

指出系統是否強制使用者在下次登入時變更密碼。如果使用者透過第三方識別資訊提供者登入，則不適用這項設定。

ipWhitelisted

boolean

如果設為 true，系統會根據已淘汰的 IP 位址 allowlist 設定，套用使用者的 IP 位址。

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、tty_tdd、tty_tdd、tty_tdd、tty_tdd、tty_tdd、isdn、isdn、main、mobile。workwork_faxwork_mobilework_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

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)

使用者所在地點清單。允許的資料大小上限為 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

使用者容易理解的字串，內含用來代表個人資料擁有者的正確方式，例如「he/him/his」或「他們」或「他們」

gender.customGender

string

自訂性別的名稱。

gender.type

string

性別類型，

可接受的值如下：

female
male
other
unknown

thumbnailPhotoEtag

string

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

ims

value (Value format)

使用者的即時 Messenger (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

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」。

可接受的值如下：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`	觀察使用者清單的變化。

REST Resource: users

資源：User

UserName

方法

`delete`

`get`

`insert`

`list`

`makeAdmin`

`patch`

`signOut`

`undelete`

`update`

`watch`