REST Resource: users

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

資源:User

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

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 Crypt 程式庫。支援 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 或網路 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

機構中的全職同等毫秒 (100000 = 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

電話號碼的類型。如果設定改為 customcustomType<ph class="<-2- - <ph class="<- class> <br - <br class="<- class ></ph> <br class="<- class ></ph> <br 類別 - <br class="ph-2- - <br class="<ph class="ph-2-1"><br class="<ph class="ph-2-2"><br class="<ph class="<ph class="ph-2-2"><br class="<ph class="<ph class="ph-2-2"><br class="<ph class="ph-2-2"><br class="<ph class="ph-2-2"><br class="<ph class="ph-2-2"><br class="<ph class="ph-2-2"><br class="<ph class="ph-2-4"><br class="<ph class="ph-2-4">, <br class="<ph class="ph-2-4">,

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,則無法設定。允許的值為 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)

安全殼層公開金鑰清單。

Fields

sshPublicKeys[].expirationTimeUsec

long

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

sshPublicKeys[].fingerprint

string

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

sshPublicKeys[].key

string

安全殼層公開金鑰。

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

每個項目可以是一種類型,表示該項目的標準類型。

舉例來說,關鍵字可以是「occupation」或「outlook」類型。除了標準類型之外,項目也可以擁有 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」或「the/them/the」。

gender.customGender

string

自訂性別的名稱。

gender.type

string

性別類型。

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

thumbnailPhotoEtag

string

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

ims

value (Value format)

使用者的免安裝應用程式 (IM) 帳戶。使用者帳戶可以有多個 ims 屬性,但只有其中一個 ims 屬性可以成為主要的 IM 聯絡人。

Fields

ims[].customProtocol

string

如果通訊協定值為 custom_protocol,這個屬性會傳回自訂通訊協定的字串。

ims[].customType

string

如果 IM typecustom,此屬性包含自訂值,且必須設定。

ims[].im

string

使用者的 IM 網路 ID。

ims[].primary

boolean

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

ims[].protocol

string

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

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

ims[].type

string

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

使用者名稱

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

留意使用者清單的變化。