管理自訂使用者欄位

您可以將自訂使用者結構定義新增至網域，為網域中的使用者定義自訂欄位。您可以使用這些欄位來儲存各種資訊，例如使用者處理的專案、實體地點、聘僱日期，或者其他符合您業務需求的資訊。

如要開始使用，請建立一或多個結構定義，以定義適合您網域的自訂欄位。您可以指定多個屬性，例如欄位名稱、類型 (字串、布林值、整數等)、是單一值或多值，以及網域的值是否可供網域中的任何使用者查看，或僅限管理員和相關使用者查看。

定義結構定義後，自訂欄位的行為會與標準欄位相同。您可以在更新網域使用者時設定使用者、使用 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"
        }
      ]
    }
  ]
}