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

REST Resource: users

資源：User

Directory API 可讓您建立及管理帳戶的使用者、使用者別名，以及使用者的 Gmail 即時通訊個人資料相片。如要進一步瞭解常見工作，請參閱《使用者帳戶開發人員指南》和《使用者別名開發人員指南》。

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

如果指定的前置字元是前置字元的一部分，則長度不得超過 10,000。

isAdmin

boolean

僅供輸出。表示具有超級管理員權限的使用者。您只能在「將使用者設為管理員」作業 ( makeAdmin 方法) 中編輯 isAdmin 屬性。如果在使用者 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 資源類型。以使用者資源來說，值為 admin#directory#user。

etag

string

僅供輸出。資源的 ETag。

emails

value (Value format)

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

Fields

emails[].address

string

使用者的電子郵件地址。這個 ID 也可當做電子郵件 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。系統允許的資料大小上限為 2 KB。

Fields

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。詳情請參閱管理使用者帳戶。

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

如果 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。

Fields

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。

Fields

phones[].customType

string

如果電話號碼 type 為 custom，這個屬性即包含自訂值，必須加以設定。

phones[].primary

boolean

如果為 true，這是指使用者的主要電話號碼。每位使用者只能設定一個主要電話號碼。

phones[].type

string

電話號碼類型。如果設定值是 custom，customType 則為 <br-p- - <br- -1-

phones[].value

string

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

suspensionReason

string

僅供輸出。在使用者帳戶或管理員停權時，將他們的帳戶停權。只有在 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，則無法設定。允許的值為 preferred 和 not_preferred。

posixAccounts

value (Value format)

使用者的 POSIX 帳戶資訊清單。

Fields

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

此帳戶登入殼層的路徑。

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)

安全殼層公開金鑰清單。

Fields

sshPublicKeys[].expirationTimeUsec

long

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

sshPublicKeys[].fingerprint

string

安全殼層公開金鑰的 SHA-256 指紋。(唯讀)

sshPublicKeys[].key

string

安全殼層公開金鑰。

notes

value (Value format)

使用者為巢狀物件的附註。

Fields

notes.contentType

string

記事的內容類型，可以是純文字或 HTML。預設值為純文字。

可接受的值：text_plain、text_html。

notes.value

string

記事內容。

websites

value (Value format)

使用者網站清單。

Fields

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。

Fields

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。

Fields

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。

Fields

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 屬性可以是主要 IM 聯絡人。

Fields

ims[].customProtocol

string

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

ims[].customType

string

如果 IM type 為 custom，此屬性包含自訂值，且必須設定。

ims[].im

string

使用者的 IM 網路 ID。

ims[].primary

boolean

這是指使用者的主要即時訊息。IM 清單中只有一個項目的值可以是 true。

ims[].protocol

string

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

可接受的值：

aim：AOL 即時 Messenger 通訊協定
custom_protocol：自訂 IM 網路通訊協定
gtalk：Google Talk 通訊協定
icq：ICQ 通訊協定
jabber：Jabber 通訊協定
msn：MSN Messenger 通訊協定
net_meeting：Net Meeting Protocol
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。

使用者名稱

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

欄位
`fullName`	`string` 透過連結名字和姓氏值來建立使用者的全名。
`familyName`	`string` 使用者的姓氏，建立使用者帳戶時必須提供。
`givenName`	`string` 使用者的名字。建立使用者帳戶時必須提供。
`displayName`	`string` 使用者的顯示名稱。上限：256 個字元。

方法
`delete`	刪除使用者。
`get`	擷取使用者。
`insert`	建立使用者。
`list`	擷取已刪除使用者或網域中所有使用者的分頁清單。
`makeAdmin`	將使用者設為超級管理員。
`patch`	使用修補程式語意更新使用者。
`signOut`	將使用者登出所有網路和裝置工作階段，並重設登入 Cookie。
`undelete`	取消刪除已刪除的使用者。
`update`	更新使用者。
`watch`	觀察使用者清單的變化。

REST Resource: users

資源：User

使用者名稱

方法

`delete`

`get`

`insert`

`list`

`makeAdmin`

`patch`

`signOut`

`undelete`

`update`

`watch`