管理自訂使用者欄位

您可以將自訂使用者結構定義新增至網域，為網域中的使用者定義自訂欄位。您可以使用這些欄位儲存資訊，例如使用者所從事的專案、實際位置、聘用日期，或其他符合業務需求的資訊。

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

定義好結構定義後，自訂欄位的運作方式就會和標準欄位一樣。您可以在更新網域中的使用者時設定這些欄位，也可以使用 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 參數，擷取使用者個人資料中的自訂欄位。customfull

搜尋使用者個人資料中的自訂欄位

您可以在 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"
        }
      ]
    }
  ]
}