맞춤 사용자 필드 관리

도메인에 커스텀 사용자 스키마를 추가하여 도메인 사용자의 커스텀 필드를 정의할 수 있습니다. 이러한 필드를 사용하여 사용자가 작업하는 프로젝트, 실제 위치, 고용일 또는 비즈니스 요구사항에 맞는 기타 정보와 같은 정보를 저장할 수 있습니다.

시작하려면 스키마를 하나 이상 만들어 도메인에 적합한 커스텀 필드를 정의합니다. 필드 이름, 유형 (문자열, 불리언, 정수 등), 단일 값인지 다중 값인지 여부, 도메인의 모든 사용자 또는 관리자 및 연결된 사용자만 값을 볼 수 있는지 여부 등 다양한 속성을 지정할 수 있습니다.

스키마가 정의되면 맞춤 입력란이 표준 입력란처럼 작동합니다. 도메인의 사용자를 업데이트할 때 이를 설정하고, users.getusers.list를 사용하여 가져오고, 커스텀 필드를 검색할 수도 있습니다.

사용자 프로필에서 맞춤 입력란 설정

스키마를 업데이트하거나 만들려면 customSchemas 속성을 만들고 사용자 리소스에 추가합니다. customSchemas 속성 내에서 커스텀 필드는 표준 JSON 형식의 스키마별로 그룹화됩니다.

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

단일 값의 커스텀 필드는 "field1": "value1"와 같이 간단한 키-값 쌍으로 설정됩니다. 다중 값의 커스텀 필드는 addressesphones와 같은 API의 표준 다중 값 필드와 같은 객체의 배열로 설정됩니다. 이러한 값 객체는 다음과 같은 키를 지원합니다.

value 저장할 값입니다(필수).
type 값의 유형입니다(선택사항). 가능한 값은 다음과 같습니다.
  • custom
  • home
  • other
  • work
customType 값의 커스텀 유형입니다(선택사항). typecustom로 설정된 경우 사용해야 합니다.

업데이트 시 스키마의 커스텀 필드를 지정하지 않으면 변경되지 않은 상태로 유지됩니다. 업데이트 시 스키마 자체가 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자입니다. 다중 값의 맞춤 필드의 경우 허용되는 요소의 수는 할당된 값의 크기에 따라 다릅니다. 예를 들어 각각 100자(영문 기준)의 값 150개를 추가하거나 각각 500자(영문 기준)의 값 50개를 추가할 수 있습니다.
  • 커스텀 스키마와 필드 이름에 허용되는 문자는 영숫자 문자, 밑줄 (_), 하이픈 (-)입니다.
  • 필드 유형은 변경할 수 없습니다.
  • 단일 값 필드를 다중 값으로 만들 수 있지만 역 연산은 허용되지 않습니다.
  • 맞춤 스키마 또는 필드의 이름은 변경할 수 없습니다.

맞춤 사용자 스키마 업데이트

커스텀 스키마를 업데이트하려면 다음 PUT 요청을 사용하고 요청 승인에 설명된 승인을 포함합니다. schemaKey은 스키마 이름이거나 고유한 스키마 id일 수 있습니다. 요청 및 응답 속성은 API 참조를 확인하세요.

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

JSON 요청

아래 예시에서 employmentData 스키마는 원래 생성 당시에 JobFamily 필드를 포함했습니다. 요청이 EmployeeNumber 필드만 포함하도록 employmentData를 업데이트합니다.

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