管理使用者帳戶

Directory API 提供程式輔助方法，可建立、更新及刪除使用者。您也可以取得符合指定條件的個別使用者或使用者清單資訊。以下列舉幾個基本使用者作業的範例。

建立使用者帳戶

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

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

如要使用其中一個網域建立使用者帳戶，請使用下列 POST 要求，並附上「瞭解驗證和授權」一節中所述的授權。如要查看 Directory API 的可用範圍，請參閱 OAuth 2.0 範圍清單。如需要求查詢字串屬性，請參閱 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 支援修補語意，因此您只需要在要求中提交更新的欄位。

要求範例

在下方範例中，使用者建立帳戶時的 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 說明其他使用者與擁有者的關係。舉例來說，在管理員與員工的關係中，員工是擁有者使用者，您可以在員工的帳戶中新增 relations 欄位，並將類型設為 manager。如要瞭解允許的類型，請參閱 User 物件參考資料。

如要設定關係，請建立或更新擁有者使用者，並在 JSON 要求內文中加入 relations 欄位。您可以在一個要求中建立多個關係。

{
  "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 網域中的 2 個使用者帳戶 (maxResults=2)：

注意：擷取網域中的所有使用者時，lastLoginTime 的值可能不準確。如要取得最準確的 lastLoginTime 值，請改為擷取使用者。

{
 "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_customer 或 customerId 值。
使用字串 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 狀態碼。除了狀態碼，回應還會傳回這個帳戶中的所有使用者：

注意：擷取所有帳戶使用者時，lastLoginTime 的值可能不準確。如要取得最準確的 lastLoginTime 值，請改為擷取使用者。

{
 "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

注意：使用 showDeleted=false 設定時，要求會傳回與「在網域中擷取所有使用者」相同的回應。

如果帳戶有多個網域，您可以從整個帳戶中擷取過去 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_customer 或 customerId 值。
身為帳戶管理員，請使用 my_customer 字串代表您帳戶的 customerId。
經銷商管理員可以使用轉售客戶的 customerId。如要使用 customerId，請在「在網域中擷取所有使用者」作業的要求中，使用帳戶的主網域名稱。產生的回應會包含 customerId 值。

如需要求和回應屬性的相關資訊，請參閱 API 參考資料。

注意：使用 showDeleted=false 設定時，要求會傳回與「擷取所有帳戶使用者」相同的回應。如需使用者要求和回應屬性的相關資訊，請參閱 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 包含 Base64 編碼和解碼函式，這些函式是依據 Apache 授權發布。

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

使用者帳戶只能由管理員修改，但網域中的任何使用者都可以讀取使用者設定檔。非管理員使用者可以提出 users.get 或 users.list 要求，並將 viewType 參數設為 domain_public，即可擷取使用者的公開個人資料。這個用途非常適合使用 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 會忽略 height 和 width。

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 是在「Retrieve users deleted within the past 20 days」(擷取過去 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 狀態碼。如要查看未刪除的使用者帳戶，請使用「Retrieve a user」作業。

管理使用者帳戶 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立使用者帳戶

JSON 要求

更新使用者帳戶

要求範例

將使用者設為管理員

JSON 要求

管理使用者關係

建立使用者之間的關係

更新或刪除關係

擷取使用者

JSON 回應

擷取網域中的所有使用者

JSON 回應

擷取所有帳戶使用者

JSON 回應

擷取最近刪除的使用者

JSON 回應

擷取使用者的相片

JSON 回應

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

更新使用者的相片

JSON 回應

刪除使用者的相片

刪除使用者帳戶

取消刪除使用者帳戶

管理使用者帳戶