Administrar campos de usuario personalizados

Si deseas definir campos personalizados para los usuarios de tu dominio, agrega 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 cosa que se ajuste a tus necesidades empresariales.

Para comenzar, crea uno o más esquemas a fin de definir los campos personalizados que sean relevantes para tu dominio. Puedes especificar una cantidad de atributos, como el nombre del campo, el tipo (string, booleano, número entero, etc.), si se trata de valores únicos o múltiples, y si sus valores son visibles para cualquier usuario del 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 configurarlas cuando actualizas los usuarios en tu dominio, los recuperas con users.get y users.list, y también buscas campos personalizados.

Nota: La API de Grupos de Cloud Identity también puede usar campos personalizados para crear consultas de grupo dinámicas a fin de definir la membresía del grupo. Consulta Formula y prueba 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 gubernamentales, datos del titular de la tarjeta, datos de cuentas financieras, información de atención médica o información sensible de contexto.

Configurar campos personalizados en un perfil de usuario

Para actualizar o crear un esquema, crea una propiedad customSchemas y agrégala al recurso del 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 única dentro de un cliente. Cuando se vuelve a usar un nombre, se genera un error 409: Entity already exists.

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

Claves
value	El valor que se almacenará, obligatorio.
type	Tipo del valor (opcional). Los valores posibles son los siguientes: custom home other work
customType	Tipo personalizado del valor, opcional. Se debe usar cuando type se configura como custom.

Si no se especifica un campo personalizado en un esquema en el momento de la actualización, no se modifica. Si no se especifica un esquema en customFields en el momento de la actualización, todos los campos personalizados en ese esquema no se modifican. Para borrar un campo personalizado o un esquema personalizado de un perfil, debes configurarlo como null de forma explícita:

"schema1": {
  "field1": null // deletes field1 from this profile.
}

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 los campos personalizados de un perfil de usuario

Para recuperar campos personalizados en un perfil de usuario, configura el parámetro projection 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 parámetro query en una solicitud users.list. 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 que todos los empleados de Atlanta están por encima del nivel 7 de trabajo. Para obtener más información, consulta Buscar usuarios.

Crea 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 solicitud POST e incluye la autorización que se describe en Autoriza solicitudes. Para ver las propiedades de la cadena de consulta de la solicitud, revisa la Referencia de la API.

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

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

Solicitud JSON

En el siguiente ejemplo, se muestra una solicitud para crear un esquema personalizado. Para ver 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 muestra un código de estado HTTP 201 junto con las propiedades del esquema personalizado nuevo.

Límites de esquemas personalizados

• La cantidad máxima de esquemas personalizados que se permite en una cuenta es 100.
• La cantidad máxima de campos personalizados que se permite en una cuenta es 100.
• La cantidad máxima de caracteres permitida en un campo string para un campo personalizado con un solo valor es de 500. En el caso de los campos personalizados con valores múltiples, la cantidad de elementos permitida 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 campos son caracteres alfanuméricos, guiones bajos (_) y guiones (-).
• No está permitido cambiar el tipo de un campo.
• Un campo de valor único puede tener valores múltiples, pero no se permite la operación inversa.
• No es posible cambiar el nombre de esquemas o campos personalizados.

Actualizar un esquema de usuario personalizado

Para actualizar un esquema personalizado, usa la siguiente solicitud PUT y, además, incluye la autorización que se describe en Autoriza solicitudes. El schemaKey puede ser el nombre del esquema o el esquema único id. Para ver 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 contenga solo 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 completarla.

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

Recuperar un esquema de usuario personalizado

Para recuperar un esquema personalizado, usa la siguiente solicitud GET y, además, incluye la autorización que se describe en Autoriza solicitudes. El schemaKey puede ser el nombre del esquema o el esquema único id. Para ver 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 muestra 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"
    }
  ]
}

Recuperar todos los esquemas de usuario personalizados

Para recuperar todos los esquemas personalizados en la misma cuenta, usa la siguiente solicitud GET e incluye la autorización que se describe en Autoriza solicitudes.Para obtener información sobre 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 muestra 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"
        }
      ]
    }
  ]
}