管理自定义用户字段

您可以通过向网域添加自定义用户架构，为网域中的用户定义自定义字段。您可以使用这些字段存储用户所参与的项目、用户的实际位置、用户的入职日期或任何其他符合您业务需求的信息。

首先，创建一个或多个架构，以定义适合您的网域的自定义字段。您可以指定多个属性，例如字段的名称、类型（字符串、布尔值、整数等）、是单值还是多值，以及其值是否可供您网域中的任何用户查看，还是仅供管理员和关联用户查看。

定义架构后，自定义字段的行为与标准字段完全相同。您可以在更新网域中的用户时设置这些字段，使用 users.get 和 users.list 提取这些字段，还可以搜索自定义字段。

在用户个人资料中设置自定义字段

如需更新或创建架构，请创建 customSchemas 属性并将其添加到用户资源。在 customSchemas 属性中，自定义字段按架构分组，采用标准 JSON 格式：

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

单值自定义字段会设置为简单的键值对，例如 "field1": "value1"。多值自定义字段会设置为对象数组，就像 API 中的标准多值字段（例如 addresses 和 phones）一样。这些值对象支持以下键：

键
value 要存储的值，必填。
type 值的类型，可选。可能的
    值如下：
  • custom
  • home
  • other
  • work
customType 值的自定义类型，可选。将 type 设置为 custom 时必须使用。

如果在更新时未指定架构中的自定义字段，则该字段将保持不变。如果在更新时未在 customFields 中指定架构本身，则该架构中的所有自定义字段都保持不变。如需从配置文件中删除自定义字段或自定义架构，您必须将其明确设置为 null：

"schema1": {
  "field1": null // deletes field1 from this profile.
}

JSON 请求

以下示例中的调用会更新用户并为 employmentData 自定义架构设置值：

PATCH https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

读取用户个人资料中的自定义字段

您可以通过将 users.get 或 users.list 请求中的 projection 参数设置为 custom 或 full，从而提取用户个人资料中的自定义字段。

在用户个人资料中搜索自定义字段

您可以在 users.list 请求中使用 query 参数在自定义字段中进行搜索。您可以使用 schemaName.fieldName 语法请求自定义字段。例如：

employmentData.projects:"GeneGnome"

返回参与 GeneGnome 项目的所有员工。查询

employmentData.location="Atlanta" employmentData.jobLevel>=7

返回亚特兰大工作级别高于 7 的所有员工。如需了解详情，请参阅搜索用户。

创建自定义用户架构

您可以将自定义用户架构添加到 Google Workspace 账号的所有网域。如需在您的网域中创建自定义用户架构，请使用以下 POST 请求，并在其中添加为请求授权中所述的授权。如需了解请求查询字符串属性，请参阅 API 参考文档。

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

您必须提交创建请求所需的信息，才能完成相应请求。如果您使用的是客户端库，则这些库会将您所选语言的数据对象转换为 JSON 数据格式的对象。

JSON 请求

以下示例展示了创建自定义架构的请求。如需查看请求和响应属性的完整列表，请参阅 API 参考文档。

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

成功的响应会返回 HTTP 201 状态代码，以及新自定义架构的属性。

自定义架构限制

  • 一个账号中允许的自定义架构数量上限为 100 个。
  • 一个账号中允许的自定义字段数量上限为 100 个。
  • 单值自定义字段的 string 字段中允许的字符数上限为 500。对于多值自定义字段，允许的元素数量取决于分配的值的大小。例如，您可以添加 150 个值（每个值 100 个字符），也可以添加 50 个值（每个值 500 个字符）。
  • 自定义架构和字段名称中允许使用的字符包括字母数字字符、下划线 (_) 和连字符 (-)。
  • 不允许更改字段的类型。
  • 单值字段可以设为多值，但不允许执行相反的操作。
  • 无法重命名自定义架构或字段。

更新自定义用户架构

如需更新自定义架构，请使用以下 PUT 请求，并在其中添加授权请求中所述的授权。schemaKey 可以是架构名称，也可以是唯一的架构 id。如需了解请求和响应属性，请参阅 API 参考文档。

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

JSON 请求

在以下示例中，架构 employmentData 在最初创建时包含 JobFamily 字段。该请求会将 employmentData 更新为仅包含 EmployeeNumber 字段：

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber",
      "multiValued": "false"
    }
  ]
}

您必须提交所有更新请求所需的信息，我们才能处理您的请求。

成功的响应会返回 HTTP 200 状态代码以及更新后的架构资源。

检索自定义用户架构

如需检索自定义架构，请使用以下 GET 请求，并包含为请求授权中所述的授权。schemaKey 可以是架构名称，也可以是唯一的架构 id。如需了解请求和响应属性，请参阅 API 参考文档。

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

成功的响应会返回 HTTP 200 状态代码以及自定义架构的属性。

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber"
    },
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
      "fieldType": "STRING",
      "fieldName": "JobFamily"
    }
  ]
}

检索所有自定义用户架构

如需检索同一账号中的所有自定义架构，请使用以下 GET 请求，并在其中添加为请求授权中所述的授权。如需了解请求和响应属性，请参阅 API 参考文档。

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

成功的响应会返回 HTTP 200 状态代码，以及账号的自定义架构。

{
  "kind": "admin#directory#schemas",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"",
  "schemas": [
    {
      "kind": "admin#directory#schema",
      "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
      "schemaName": "employmentData",
      "fields": [
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
          "fieldType": "STRING",
          "fieldName": "EmployeeNumber"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}