Puedes definir campos personalizados para los usuarios de tu dominio si agregas esquemas de usuario personalizados al dominio. Puedes usar estos campos para almacenar información como los proyectos en los que trabajan los usuarios, sus ubicaciones físicas, la fecha de contratación o cualquier otra opción que se adapte 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 varios atributos, como el nombre del campo, el tipo (string, booleano, número entero, etc.), si tiene un valor único o múltiple, y si sus usuarios pueden ver sus valores 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 actualices a los usuarios de tu dominio, recuperarlos con users.get
y users.list
, y también buscar campos personalizados.
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",
...
},
...
}
Los campos personalizados de un solo valor se establecen como pares clave-valor simples, como "field1": "value1"
. Los campos personalizados con valores múltiples se configuran como arreglos de objetos, como 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:
|
customType |
Tipo personalizado del valor, opcional. Se debe usar cuando type se establezca en custom . |
Si un campo personalizado en un esquema no se especifica en el momento de la actualización, no se modifica. Si un esquema en sí no se especifica en customFields
en el momento de la actualización, todos los campos personalizados de 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 en el siguiente ejemplo actualiza un usuario y establece valores para el esquema personalizado 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" }
]
}
}
}
Leer los campos personalizados de un perfil de usuario
Puedes recuperar campos personalizados de un perfil de usuario si configuras el parámetro projection
en una solicitud users.get
o users.list
como custom
o full
.
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 todos los empleados de Atlanta por encima del nivel de trabajo 7. Para obtener más información, consulta Usuarios de búsqueda.
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
y, luego, incluye la autorización que se describe en Autorizar solicitudes. Para obtener las propiedades de la string de consulta de solicitud, consulta 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 completar la solicitud. Si usas bibliotecas cliente, estas convierten los objetos de datos del lenguaje que elegiste en objetos con formato 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 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 permitida en un campo
string
para un campo personalizado de valor único es 500. En el caso de los campos personalizados con valores múltiples, 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 campos son caracteres alfanuméricos, guiones bajos (
_
) y guiones (-
). - No se permite cambiar el tipo de un campo.
- Un campo de valor único puede hacerse de varios valores, 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
e incluye la autorización descrita en Autorizar 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 API.
PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey
Solicitud JSON
En el siguiente ejemplo, el esquema employmentData
contenía un campo JobFamily
cuando se creó originalmente. La solicitud está actualizando 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 completar la solicitud.
Una respuesta correcta muestra un código de estado HTTP 200, junto con el recurso de esquema actualizado.
Recupera un esquema de usuario personalizado
Para recuperar un esquema personalizado, usa la siguiente solicitud GET
e incluye la autorización descrita en Autorizar 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 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"
}
]
}
Recupera 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 descrita en Autoriza solicitudes.Para las propiedades de solicitud y respuesta, consulta la Referencia de 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 para 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"
}
]
}
]
}