Administrar campos de usuario personalizados

Puedes definir campos personalizados para los usuarios de tu dominio agregando esquemas de usuario personalizados al dominio. Puedes usar estos campos para almacenar información como los proyectos en los que trabajan tus usuarios, sus ubicaciones físicas, su fecha de contratación o cualquier otra información que se ajuste a las necesidades de tu empresa.

Para comenzar, crea uno o más esquemas para definir los campos personalizados que tengan sentido para tu dominio. Puedes especificar varios atributos, como el nombre del campo, el tipo (cadena, booleano, número entero, etcétera), si es de un solo valor o de varios valores, y si sus valores pueden verlos todos los usuarios de tu dominio o solo los administradores y el usuario asociado.

Una vez que se define un esquema, los campos personalizados se comportan como los campos estándar. Puedes configurarlos cuando actualices usuarios en tu dominio, recuperarlos con users.get y users.list, y también buscar campos personalizados.

Nota: La API de Grupos de Cloud Identity también puede usar campos personalizados para crear consultas de grupos dinámicos para definir la membresía de grupos. Consulta Cómo formular y probar una consulta de membresía para obtener más información.

Advertencia: No debes usar esta función para almacenar información de identificación personal sensible, como credenciales de cuentas, números de identificación emitidos por el Gobierno, datos de titulares de tarjetas, datos de cuentas financieras, información de atención médica o información sensible de antecedentes.

Cómo configurar campos personalizados en un perfil de usuario

Para actualizar o crear un esquema, crea una customSchemaspropiedad y agrégala al recurso de usuario. Dentro de la propiedad customSchemas, los campos personalizados se agrupan por esquema en formato JSON estándar:

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

Nota: Cada schemaName debe ser único dentro de un cliente. Si se vuelve a usar un nombre, se produce un error 409: Entity already exists.

Los campos personalizados de un solo valor se configuran como pares clave-valor simples, como "field1": "value1". Los campos personalizados de varios valores se configuran como arrays de objetos, como los campos estándar de varios valores en la API, como addresses y phones. Estos objetos de valor admiten las siguientes claves:

Claves
value	Es el valor que se almacenará (obligatorio).
type	Es el tipo del valor (opcional). Los valores posibles son los siguientes: custom home other work
customType	Es el tipo personalizado del valor (opcional). Se debe usar cuando type se establece en custom.

Si no se especifica un campo personalizado en un esquema en el momento de la actualización, se deja sin cambios. Si no se especifica un esquema en customFields en el momento de la actualización, todos los campos personalizados de ese esquema se dejan sin cambios. Para borrar un campo personalizado o un esquema personalizado de un perfil, debes establecerlo en null de forma explícita:

"schema1": {
  "field1": null
}

Solicitud JSON

La llamada del siguiente ejemplo actualiza un usuario y establece valores para el esquema personalizado employmentData:

PATCH https://admin.googleapis.com/admin/directory/v1/users/[e-mail]

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering",
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

Cómo leer campos personalizados en un perfil de usuario

Puedes recuperar campos personalizados en un perfil de usuario si estableces el projection parámetro en una solicitud users.get o users.list en custom o full.

Cómo buscar campos personalizados en un perfil de usuario

Puedes buscar dentro de los campos personalizados con el query parámetro en una users.list solicitud. Solicitas el campo personalizado con una sintaxis schemaName.fieldName. Por ejemplo:

employmentData.projects:"GeneGnome"

muestra todos los empleados que trabajan en el proyecto GeneGnome. La consulta

employmentData.location="Atlanta" employmentData.jobLevel>=7

muestra todos los empleados de Atlanta que superan el nivel de trabajo 7. Para obtener más información, consulta Cómo buscar usuarios.

Cómo crear un esquema de usuario personalizado

Se puede agregar un esquema de usuario personalizado a todos los dominios de tu cuenta de Google Workspace. Para crear un esquema de usuario personalizado en tus dominios, usa la siguiente POST solicitud e incluye la autorización descrita en Autorizar solicitudes. Para conocer las propiedades de la cadena de consulta de la solicitud, consulta la referencia de la API.

POST https://admin.googleapis.com/admin/directory/v1/customer/<var>my_customer or customerId</var>/schemas

Todas las solicitudes de creación requieren que envíes la información necesaria para satisfacer la solicitud. Si usas bibliotecas cliente, estas convierten los objetos de datos del lenguaje elegido en objetos con formato de datos JSON.

Solicitud JSON

En el siguiente ejemplo, se muestra una solicitud para crear un esquema personalizado. Para obtener la lista completa de propiedades de solicitud y respuesta, consulta la referencia de la API.

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

Una respuesta correcta devuelve un código de estado HTTP 201, junto con las propiedades del nuevo esquema personalizado.

Límites del esquema personalizado

• La cantidad máxima de esquemas personalizados permitidos en una cuenta es 100.
• La cantidad máxima de campos personalizados permitidos en una cuenta es 100.
• La cantidad máxima de caracteres permitidos en un campo string para un campo personalizado de un solo valor es 500. En el caso de los campos personalizados de varios valores, la cantidad de elementos permitidos depende del tamaño de los valores asignados. Por ejemplo, puedes agregar 150 valores de 100 caracteres cada uno o 50 valores de 500 caracteres cada uno.
• Los caracteres permitidos en los esquemas personalizados y los nombres de los campos son caracteres alfanuméricos, guiones bajos (_) y guiones (-).
• No se permite cambiar el tipo de un campo.
• Un campo de un solo valor se puede convertir en un campo de varios valores, pero no se permite la operación inversa.
• No es posible cambiar el nombre de los esquemas o campos personalizados.

Cómo actualizar un esquema de usuario personalizado

Para actualizar un esquema personalizado, usa la siguiente PUT solicitud e incluye la autorización descrita en Autorizar solicitudes. schemaKey puede ser el nombre del esquema o el id único del esquema. Para conocer las propiedades de solicitud y respuesta, consulta la referencia de la API.

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

Nota: La API también admite la semántica de parches.

Solicitud JSON

En el siguiente ejemplo, el esquema employmentData contenía un campo JobFamily cuando se creó originalmente. La solicitud actualiza employmentData para que solo contenga un campo 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"
    }
  ]
}

Todas las solicitudes de actualización requieren que envíes la información necesaria para satisfacer la solicitud.

Una respuesta correcta devuelve un código de estado HTTP 200, junto con el recurso de esquema actualizado.

Cómo recuperar un esquema de usuario personalizado

Para recuperar un esquema personalizado, usa la siguiente GET solicitud e incluye la autorización descrita en Autorizar solicitudes. schemaKey puede ser el nombre del esquema o el id único del esquema. Para conocer las propiedades de solicitud y respuesta, consulta la referencia de la API.

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

Una respuesta correcta devuelve un código de estado HTTP 200, junto con las propiedades del esquema personalizado.

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

Cómo recuperar todos los esquemas de usuario personalizados

Para recuperar todos los esquemas personalizados de la misma cuenta, usa la siguiente GET solicitud e incluye la autorización descrita en Autorizar solicitudes.Para conocer las propiedades de solicitud y respuesta, consulta la referencia de la API.

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

Una respuesta correcta devuelve un código de estado HTTP 200, junto con los esquemas personalizados de la cuenta.

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