管理自訂使用者欄位

您可以在網域中新增自訂使用者結構定義,為網域使用者定義自訂欄位。您可以使用這些欄位儲存資訊,例如使用者工作的專案、實際位置、聘僱日期,或符合業務需求的任何資訊。

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

定義結構定義後,自訂欄位的行為與標準欄位相同。您可以在更新網域使用者時設定這些自訂欄位,使用 users.getusers.list 擷取使用者,以及搜尋自訂欄位。

在使用者設定檔中設定自訂欄位

如要更新或建立結構定義,請建立 customSchemas 屬性,並將其新增到使用者資源中。在 customSchemas 屬性中,自訂欄位會以標準 JSON 格式按結構定義分組:

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

單一值自訂欄位設定為簡單的鍵/值組合,例如 "field1": "value1"。多值自訂欄位會設為物件的陣列,例如 API 中的標準多值欄位,例如 addressesphones。這些值物件支援下列鍵:

索引鍵
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.getusers.list 要求中的 projection 參數設為 customfull,藉此擷取使用者設定檔中的自訂欄位。

搜尋使用者設定檔中的自訂欄位

您可以使用 users.list 要求中的 query 參數搜尋自訂欄位。您可以使用 schemaName.fieldName 語法要求自訂欄位。例如:

employmentData.projects:"GeneGnome"

傳回所有參與 Project 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"
        }
      ]
    }
  ]
}