管理使用者帳戶

Directory API 提供透過程式建立、更新及刪除使用者的方法。您也可以取得個別使用者的相關資訊,或是符合特定條件的使用者清單。以下是一些基本使用者作業的範例。

建立使用者帳戶

您可以將使用者帳戶新增至任何 Google Workspace 帳戶的網域。新增使用者帳戶前,請先確認網域擁有權

如果將個人 Gmail 帳戶升級為使用自有網域名稱的企業電子郵件帳戶,您必須解鎖其他 Google Workspace 設定,才能建立新的使用者帳戶。詳情請參閱已升級至 G Suite Basic 的 G Suite 企業電子郵件帳戶

如要使用您的任一網域建立使用者帳戶,請使用以下 POST 要求,並加入「瞭解驗證和授權」一節中所述的授權要求。您可以在 OAuth 2.0 範圍清單中查看 Directory API 的可用範圍。如需要求查詢字串屬性,請參閱 users.insert() 方法。

POST https://admin.googleapis.com/admin/directory/v1/users

所有建立要求都必須提交完成要求所需的資訊。如果您使用的是用戶端程式庫,這類程式庫會將所選語言的資料物件轉換為 JSON 資料格式的物件。

JSON 要求

下列 JSON 顯示建立使用者的要求範例。如需要求和回應屬性的完整清單,請參閱 API 參考資料

{
"primaryEmail": "liz@example.com",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "liz_im@talk.example.com",
  "primary": true
 }
],
"emails": [
 {
  "address": "liz@example.com",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

如果建立要求的查詢率過高,API 伺服器可能會發出 HTTP 503 回應,指出已超過配額。如果收到這些回應,請使用指數輪詢演算法重試要求。

關於新帳戶的注意事項:

  • 如果 Google 帳戶已購買郵件授權,系統會自動為新的使用者帳戶指派信箱。這項作業可能需要幾分鐘才能完成完成並啟用。
  • 如果在要求中編輯唯讀欄位 (例如 isAdmin),API 服務會在不發出通知的情況下略過。
  • 一個帳戶最多可包含 600 個網域 (1 個主網域 + 599 個其他網域)
  • 如果使用者的帳戶在建立時並未指派給特定機構單位,該帳戶會屬於頂層機構單位。使用者可存取的 Google Workspace 服務取決於其機構單位,如果使用者移至新機構,存取權也會跟著改變。如要進一步瞭解機構架構,請參閱管理說明中心。如要進一步瞭解如何將使用者移至其他機構,請參閱「更新使用者」一文。
  • 新的使用者帳戶必須具備 password。如果指定 hashFunction,則密碼必須是有效的雜湊鍵。如未指定,則密碼應以明文撰寫,並介於 8–100 個 ASCII 字元之間。詳情請參閱 API 參考資料
  • 如果是採用 Google Workspace 彈性方案的使用者,透過這個 API 建立使用者將會在收益方面產生影響,我們也會向您的客戶帳單帳戶收費。詳情請參閱 API 帳單資訊
  • Google Workspace 帳戶可包含您的任一網域,使用多個網域帳戶時,其中一個網域的使用者皆可與其他帳戶網域的使用者共用服務。如要進一步瞭解多個網域的使用者,請參閱 API 多網域資訊
  • 可能有相衝突的帳戶。查看您想新增的使用者是否已有 Google 帳戶。然後按照步驟操作,避免與這些帳戶相衝突。請參閱「尋找並解決相衝突的帳戶」。
  • 可能是訪客帳戶。如果使用者邀請沒有 Google 帳戶的使用者在雲端硬碟上進行協作,他們會收到協作者帳戶,格式為「<使用者名稱>@<您的網域>.com」。如果您新增與訪客帳戶相同的使用者名稱,帳戶將轉換成完整的 Google Workspace 帳戶。並保留目前的雲端硬碟檔案權限。請參閱「與協作者共用文件」。

成功的回應會傳回 HTTP 200 狀態碼。除了狀態碼,回應還會傳回新使用者帳戶的屬性。

更新使用者帳戶

如要更新使用者帳戶,請使用下列 PUT 要求,並加入授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、不重複使用者 id 或使用者的別名電子郵件地址。

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

要求和回應主體都包含 User 的執行個體。不過,Directory API 支援 patch 語意,因此您只需要在要求中提交已更新的欄位。

要求範例

在以下範例中,使用者帳戶建立時,使用者的 givenName 為「Elizabeth」,且僅提供公司電子郵件地址。

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
}

下方要求會將 givenName 從「Elizabeth」更新為「Liz」,並新增住家地址。請注意,由於欄位是陣列,因此這兩個電子郵件地址都是完整提供。

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    },
    {
      "address": "liz@home.com",
      "type": "home"
    }
  ]
}

成功的回應會傳回 HTTP 200 狀態碼和包含更新欄位的 User 資源。

更新使用者帳戶名稱時,請注意下列事項:

  • 重新命名使用者帳戶會變更使用者的主要電子郵件地址,以及擷取這位使用者資訊時使用的網域。重新命名使用者之前,建議您先將使用者從所有瀏覽器工作階段和服務中登出。
  • 重新命名使用者帳戶的程序最多可能需要 10 分鐘,才會在所有服務中全面生效。
  • 重新命名使用者時,系統會將舊使用者名稱保留為別名,以確保電子郵件轉寄設定可以持續傳送郵件,且無法將舊使用者名稱當做新使用者名稱使用。
  • 一般而言,我們建議您不要使用使用者電子郵件地址做為永久資料的金鑰,因為電子郵件地址可能會有所變動。
  • 如需在 Google Workspace 應用程式中重新命名使用者的完整影響清單,請參閱管理員說明中心

將使用者設為管理員

如要讓使用者成為超級管理員,請使用下列 POST 要求,並加入授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、不重複使用者 id 或使用者的別名電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料。如要進一步瞭解超級管理員,請參閱管理說明中心

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

JSON 要求

在這個範例中,當使用者的 userKey 為 liz@example.com 時,已成為超級管理員:

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{
 "status": true
}

成功的回應會傳回 HTTP 200 狀態碼

管理使用者關係

Directory API 會使用 relations 欄位定義使用者間的不同關係類型。在業務性質中,使用者通常會使用此欄位來處理主管與助理關係,但欄位也支援許多其他類型。凡是支援該資訊卡的 Google Workspace 應用程式,都會在使用者的「相關人物」資訊卡中顯示關係。如需資訊卡的顯示位置範例,請參閱「在使用者的目錄個人資料中新增資訊」。

建立使用者之間的關係

您可以從「擁有」使用者 (其記錄包含 relations 欄位) 開始,只定義一個方向的關係。type 會說明其他人與擁有使用者的關係。例如,在經理和員工關係中,員工是擁有的使用者,而您要使用 manager 類型的帳戶新增 relations 欄位。如需允許類型,請參閱 User 物件參考資料。

透過包含 relations 欄位的 JSON 要求主體建立更新其使用者,藉此設定關係。您可以在一個要求中建立多個關係。

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

更新或刪除關係

您只能更新整個 relations 欄位,不能要求列出的個別使用者變更關係類型,或將其移除。在上述範例中,如要移除現有的經理關係,並將虛線管理員設為擁有者使用者的管理員,請視需要更新所屬使用者帳戶,加入所有欄位的值。

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

如要移除自有使用者的所有關係,請將 relations 設為空白:

{
  "relations": []
}

擷取使用者

如要擷取使用者,請使用下列 GET 要求,並加入授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、不重複使用者 id 或使用者的別名電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

這個範例會傳回主要或別名電子郵件地址為 liz@example.com 的使用者帳戶屬性:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼。除了狀態碼,回應還會傳回使用者帳戶的屬性。

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "lizim@talk.example.com",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "liz@example.com",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "lizsmith@example.com",
  "lsmith@example.com"
 ],
 "nonEditableAliases": [
  "liz@test.com"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

擷取網域中所有使用者

如要擷取同一網域中的所有使用者,請使用下列 GET 要求,並加入授權要求中所述的授權。為了方便閱讀,本範例使用換行字元:

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

如需要求和回應屬性,請參閱 API 參考資料

JSON 回應

在本例中,系統會傳回 example.com 網域中的所有使用者,每個回應網頁最多包含 2 個使用者網域。此回應中有一個 nextPageToken 代表後續的使用者名單。根據預設,系統會依據使用者電子郵件地址的字母順序,傳回 100 位使用者的清單:

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

成功的回應會傳回 HTTP 200 狀態碼。除了狀態碼以外,回應還傳回 example.com 網域 (maxResults=2) 中的 2 個使用者帳戶:

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "liz@example.com",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "lizim@talk.example.com",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "liz@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "second_admin@example.com"
   ],
   "nonEditableAliases": [
    "admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

擷取所有帳戶使用者

如要擷取帳戶包含多個網域的所有使用者,請使用下列 GET 要求,並加入授權要求中所述的授權。為了方便閱讀,本範例使用換行字元:

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes
  • customer 查詢字串是 my_customercustomerId 值。
  • 使用 my_customer 字串代表帳戶的 customerId
  • 經銷商管理員請使用經銷商客戶的 customerId。如果是 customerId,請在「擷取網域中的所有使用者」作業要求中使用帳戶的主網域名稱。產生的回應中有 customerId 值。
  • 選用的 orderBy 查詢字串會決定清單是依使用者的主要電子郵件地址、姓氏或名字排序。使用 orderBy 時,您也可以使用 sortOrder 查詢字串,以遞增或遞減順序列出結果。
  • 選用的 query 查詢字串可讓您搜尋使用者個人資料中的多個欄位,包括核心和自訂欄位。如需範例,請參閱「搜尋使用者」一文。

如需要求和回應屬性,請參閱 API 參考資料

在本例中,帳戶管理員要求帳戶內所有使用者,每個回應頁都顯示一個使用者項目。nextPageToken 會前往後續的結果頁面:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

在這個範例中,經銷商管理員要求經銷商帳戶 (customerId 值為 C03az79cb) 中的所有使用者。

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼。除了狀態碼,回應也會傳回這個帳戶中的所有使用者:

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

擷取最近刪除的使用者

如要擷取過去 20 天內從帳戶或帳戶其中一個網域中刪除的所有使用者,請使用下列 GET 要求,並加入授權要求中所述的授權。如要取消刪除使用者,請參閱取消刪除使用者一文。

如要擷取過去 20 天內從帳戶的主網域或子網域刪除的使用者,請使用以下 GET 要求。domain 查詢字串是網域的主網域名稱。如需使用者要求和回應屬性,請參閱 API 參考資料。此外,為了方便閱讀,本範例使用換行字元:

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true
如果帳戶有多個網域,您可以將整個帳戶最近 20 天內刪除的使用者擷取為下列 GET 要求。為了方便閱讀,本範例使用換行字元:
GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true
  • customer 查詢字串是 my_customercustomerId 值。
  • 帳戶管理員可以使用 my_customer 字串來代表帳戶的 customerId
  • 經銷商管理員請使用經銷商客戶的 customerId。如果是 customerId,請在「擷取網域中的所有使用者」作業要求中使用帳戶的主網域名稱。產生的回應中有 customerId 值。

如需要求和回應屬性,請參閱 API 參考資料

在這個範例中,帳戶管理員正在要求帳戶中所有已刪除的使用者:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼。除了狀態碼,回應也會傳回過去 20 天內刪除的所有帳戶使用者:

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user1@example.com"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user3@example.com"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

擷取使用者的相片

API 會擷取一個相片縮圖,也就是最新的 Google 個人資料相片。如要擷取使用者最新的相片,請使用下列 GET 要求,並加入授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、使用者 id 或任何使用者的別名電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

本範例會傳回 liz@example.com 的最新相片:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

API 的相片在網路安全的 Base64 編碼與 RFC 4648 'base64url' 類似,因此:

  • 斜線 (/) 字元會替換為底線 (_) 字元。
  • 加號 (+) 字元會替換成連字號 (-) 字元。
  • 等號 (=) 字元會替換為星號 (*)。
  • 針對邊框間距,系統會使用半形句號 (.) 字元,而非 RFC-4648 baseURL 定義,當中使用等號 (=) 做為邊框間距。這樣做可以簡化網址剖析程序。
  • 無論正在上傳的相片大小為何,API 都會將其比例縮減至 96x96 像素。

如果需要從 JavaScript 建立相容的連結,Google Closure Library 包含 Apache 授權發布的 Base64 編碼和解碼函式

以非管理員的身分擷取使用者

雖然只有管理員能修改使用者帳戶,但網域中的所有使用者都可以讀取使用者個人資料。非管理員使用者可以使用 viewType 參數等於 domain_public 發出 users.getusers.list 要求,以擷取使用者的公開個人資料。範圍 https://www.googleapis.com/auth/admin.directory.user.readonly 非常適合此用途。

domain_public 檢視畫面允許非管理員使用者存取一組標準的核心欄位。以自訂欄位來說,定義結構定義時,您可以選擇為公開或私人欄位。

更新使用者的相片

如要更新使用者的相片,請使用下列 PUT 要求,並加入授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、使用者 id 或任何使用者別名的電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

在本範例中,liz@example.com 相片已更新:

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}

更新相片時,API 會忽略 heightwidth

JSON 回應

成功的回應會傳回 HTTP 200 狀態碼

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

刪除使用者的相片

如要刪除使用者的相片,請使用下列 DELETE 要求,並附上授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、使用者 id 或任何使用者別名的電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

刪除後,使用者的相片就不會顯示。在使用者需要相片的情況下,系統會改為顯示剪影。

刪除使用者帳戶

如要刪除使用者帳戶,請使用下列 DELETE 要求,並附上授權要求中所述的授權。userKey 可以是使用者的主要電子郵件地址、不重複使用者 id 或使用者的別名電子郵件地址。如需要求和回應屬性,請參閱 API 參考資料

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

在這個範例中,liz@example.com 使用者帳戶遭到刪除:

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

成功的回應只會傳回 HTTP 200 狀態碼

請謹慎考量下列事項,再刪除使用者:

  • 刪除的使用者將無法再登入。
  • 如要進一步瞭解使用者帳戶刪除功能,請參閱管理說明中心

取消刪除使用者帳戶

過去 20 天內刪除的使用者必須符合特定條件,才能還原使用者帳戶

如要取消刪除使用者帳戶,請使用下列 POST 要求並加入授權要求中所述的授權。userKey 是「擷取使用者在過去 20 天內刪除的使用者」作業回應中找到的不重複使用者 id。使用者的主要電子郵件地址或其中一個使用者的別名電子郵件地址不得用於 userKey 中。如需要求和回應屬性,請參閱 API 參考資料

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

在這個例子中,系統會取消刪除 liz@example.com 使用者。這位使用者先前的所有帳戶資源都會還原:

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

成功的回應只會傳回 HTTP 204 狀態碼,如要查看未刪除的使用者帳戶,請使用擷取使用者作業。