管理用户帐号

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Directory API 提供用于创建、更新和删除用户的程序化方法。您还可以获取个别用户或符合指定条件的用户列表的信息。以下是一些基本用户操作的示例。

创建用户帐号

您可以将用户帐号添加到任意 Google Workspace 帐号的网域。在添加用户帐号之前，请确认域名所有权。

如果您将个人 Gmail 帐号升级为采用自己域名的企业电子邮件帐号，则必须先解锁其他 Google Workspace 设置，才能创建新用户帐号。有关详情，请参阅将 G Suite 企业电子邮件帐号更新为 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 帐号的用户在云端硬盘中协作，那么他们将收到访客帐号（格式为 visitor's_username@your_domain.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 对象参考。

如需设置关系，请使用包含 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_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 状态代码。响应将返回状态代码以及此帐号中的所有用户： 

{
 "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_customer 或 customerId 值。
  • 作为帐号管理员，请使用字符串 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 base网址 定义，后者使用等号 (=) 进行填充。这样做是为了简化网址解析。
  • 无论上传的照片大小如何，API 都会按比例将其缩小至 96x96 像素。

如果您需要从 JavaScript 创建兼容的链接，则可以使用 Google Closure 库，其中包含根据 Apache 许可发布的 Base64 编码和解码函数。

以非管理员身份检索用户

虽然用户帐号只能由管理员修改，但网域中的任何用户都可以读取用户个人资料。非管理员用户可以发出 viewType 参数等于 domain_public 的 users.get 或 users.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 会忽略 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 是位于“检索过去 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 状态代码。如需查看未删除用户的帐号，请使用检索用户操作。