本頁面由 Cloud Translation API 翻譯而成。

管理自訂使用者欄位

您可以為網域使用者新增自訂使用者結構定義，藉此定義自訂使用者欄位。您可以使用這些欄位來儲存資訊，例如使用者執行的專案、實際位置、受僱日期，或是任何其他符合您業務需求的項目。

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

定義結構定義之後，自訂欄位的運作方式就跟標準欄位一樣。您可以在更新網域使用者、設定users.get及users.list，以及搜尋與自訂欄位。

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

如要更新或建立結構定義，請建立 customSchemas 屬性並新增至使用者資源。在 customSchemas 屬性中，自訂欄位會依結構定義以標準 JSON 格式分組：

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

單一值的自訂欄位已設為簡單的鍵/值組合，例如 "field1": "value1"。多值自訂欄位會設為物件陣列，例如 addresses 和 phones 等 API 的標準多重值欄位。這些值物件支援下列鍵：

評估作業彙整鍵
`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"
        }
      ]
    }
  ]
}