管理使用者帳戶

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

建立使用者帳戶

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

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

如要使用其中一個網域建立使用者帳戶，請使用下列 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 帳戶已購買郵件授權，系統會自動為新使用者帳戶指派信箱。這項指派作業可能需要幾分鐘才能完成及啟用。
  • API 服務會默默忽略在要求中編輯唯讀欄位 (例如 isAdmin)。
  • 帳戶最多可加入 600 個網域 (1 個主網域 + 599 個次要網域)
  • 如果使用者在建立使用者帳戶時未指派至特定機構單位，該帳戶就會位於頂層機構單位。使用者所屬的機構單位會決定使用者可存取哪些 Google Workspace 服務。如果使用者移至新機構，使用者的存取權就會變更。如要進一步瞭解機構結構，請參閱管理說明中心。如要進一步瞭解如何將使用者移至其他機構，請參閱「更新使用者」。
  • 新使用者帳戶必須有 password。如果指定了 hashFunction，密碼必須是有效的雜湊金鑰。如果未指定，密碼應為明文，且長度介於 8 到 100 個 ASCII 字元之間。詳情請參閱 API 參考資料。
  • 如果使用者採用 Google Workspace 彈性方案，使用這個 API 建立使用者會產生金錢影響，並且會向客戶帳單帳戶收取費用。詳情請參閱 API 帳單資訊。
  • Google Workspace 帳戶可包含任何網域。在多網域帳戶中，一個網域的使用者可以與其他帳戶網域中的使用者共用服務。如要進一步瞭解多個網域中的使用者，請參閱 API 多個網域資訊。
  • 可能有相衝突的帳戶。確認您想新增的使用者是否已擁有 Google 帳戶，然後按照步驟操作，避免與這些帳戶衝突。請參閱「尋找並排除相衝突的帳戶」。
  • 可能有訪客帳戶。如果使用者邀請機構外部沒有 Google 帳戶的使用者在 Drive 上協同合作，對方會收到訪客帳戶，格式為訪客帳戶_使用者名稱@你的網域名稱.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 會說明其他人與擁有者之間的關係。舉例來說，在主管與員工的關係中，員工是擁有者使用者，您可以使用 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 網域中的 2 個使用者帳戶 (maxResults=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_customer 或 customerId 值。
  • 使用字串 my_customer 代表帳戶的 customerId。
  • 經銷商管理員應使用轉售客戶的 customerId。針對 customerId，請在Retrieve all users in a domain 作業要求中使用帳戶的主網域名稱。產生的回應包含 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
如果帳戶有多個網域，您可以使用下列 GET 要求，從整個帳戶中擷取過去 20 天內刪除的使用者。為了方便閱讀，本範例使用換行符號： 
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，請在Retrieve all users in a domain 作業要求中使用帳戶的主網域名稱。產生的回應包含 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 編碼和解碼函式。

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

雖然只有管理員可以修改使用者帳戶，但網域中的任何使用者都可以讀取使用者個人資料。非管理員使用者可以提出 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 作業回應中找到的不重複使用者 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 狀態碼。如要查看未刪除的使用者帳戶，請使用擷取使用者作業。