此页面由 Cloud Translation API 翻译。

管理自定义用户字段

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

首先，请创建一个或多个架构来定义对您的网域有意义的自定义字段。您可以指定多个属性，例如字段名称、类型（字符串、布尔值、整数等）、字段是单值还是多值，以及网域中的任何用户都可以查看或者只有管理员和关联用户才能看到其值。

定义架构后，自定义字段的行为与标准字段类似。您可以在更新网域中的用户时设置这些用户，使用 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/liz@example.com

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