맞춤 사용자 입력란 관리

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

시작하려면 도메인에 적합한 맞춤 필드를 정의하는 스키마를 하나 이상 만드세요. 필드 이름, 유형 (문자열, 불리언, 정수 등), 단일 값인지 다중 값인지, 값이 도메인의 모든 사용자에게 표시되는지 아니면 관리자와 연결된 사용자에게만 표시되는지 등 여러 속성을 지정할 수 있습니다.

스키마가 정의되면 맞춤 필드는 표준 필드와 똑같이 작동합니다. 도메인에서 사용자를 업데이트할 때 설정하고, 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자(영문 기준)입니다. 다중 값 맞춤 필드의 경우 허용되는 요소 수는 할당된 값의 크기에 따라 다릅니다. 예를 들어 각각 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"
        }
      ]
    }
  ]
}