Vous pouvez définir des champs personnalisés pour les utilisateurs de votre domaine en ajoutant des schémas utilisateur personnalisés au domaine. Vous pouvez utiliser ces champs pour stocker des informations telles que les projets sur lesquels vos utilisateurs travaillent, leurs emplacements physiques, leur date d'embauche ou tout autre élément qui correspond aux besoins de votre entreprise.
Pour commencer, créez un ou plusieurs schémas afin de définir les champs personnalisés pertinents pour votre domaine. Vous pouvez spécifier un certain nombre d'attributs, tels que le nom du champ, le type (chaîne, booléen, entier, etc.), s'il s'agit d'une valeur unique ou multiple, et si ses valeurs sont visibles par tous les utilisateurs de votre domaine, ou uniquement par les administrateurs et l'utilisateur associé.
Une fois le schéma défini, les champs personnalisés se comportent comme des champs standards.
Vous pouvez les définir lors de la mise à jour des utilisateurs de votre domaine, les récupérer avec users.get
et users.list
, et également rechercher des champs personnalisés.
Définir des champs personnalisés dans un profil utilisateur
Pour mettre à jour ou créer un schéma, créez une propriété customSchemas
et ajoutez-la à la ressource utilisateur. Dans la propriété customSchemas
, les champs personnalisés sont regroupés par schéma au format JSON standard:
"customSchemas": {
"schema1": {
"field1": "value1",
"field2": [
{ "value": "value2a" },
{ "value": "value2b" },
...
],
...
},
"schema2": {
"field3": "value3",
...
},
...
}
Les champs personnalisés à valeur unique sont définis sous forme de paires clé/valeur simples, comme "field1": "value1"
. Les champs personnalisés à valeurs multiples sont définis comme des tableaux d'objets, comme les champs standards à valeurs multiples de l'API tels que addresses
et phones
. Ces objets de valeur acceptent les clés suivantes:
clés | |
---|---|
value |
Valeur à stocker (obligatoire). |
type |
Type de la valeur (facultatif). Les valeurs possibles du champ sont les suivantes :
|
customType |
Type personnalisé de la valeur, facultatif. Doit être utilisé lorsque type est défini sur custom . |
Si un champ personnalisé d'un schéma n'est pas spécifié au moment de la mise à jour, il reste inchangé. Si un schéma lui-même n'est pas spécifié dans customFields
au moment de la mise à jour, tous les champs personnalisés de ce schéma restent inchangés. Pour supprimer un champ personnalisé ou un schéma personnalisé d'un profil, vous devez le définir explicitement sur null
:
"schema1": {
"field1": null // deletes field1 from this profile.
}
Requête JSON
Dans l'exemple ci-dessous, l'appel met à jour un utilisateur et définit des valeurs pour le schéma personnalisé 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" }
]
}
}
}
Lire les champs personnalisés d'un profil utilisateur
Vous pouvez extraire les champs personnalisés d'un profil utilisateur en définissant le paramètre projection
dans une requête users.get
ou users.list
sur custom
ou full
.
Rechercher des champs personnalisés dans un profil utilisateur
Vous pouvez effectuer une recherche dans des champs personnalisés à l'aide du paramètre query
dans une requête users.list
. Vous demandez le champ personnalisé à l'aide d'une syntaxe schemaName.fieldName
. Exemple :
employmentData.projects:"GeneGnome"
renvoie tous les employés qui travaillent sur le projet GeneGnome. La requête
employmentData.location="Atlanta" employmentData.jobLevel>=7
renvoie tous les employés d’Atlanta au-dessus du niveau de travail 7. Pour en savoir plus, consultez la section Rechercher des utilisateurs.
Créer un schéma d'utilisateur personnalisé
Vous pouvez ajouter un schéma d'utilisateur personnalisé à tous les domaines de votre compte Google Workspace. Pour créer un schéma d'utilisateur personnalisé dans vos domaines, utilisez la requête POST
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes. Pour connaître les propriétés de la chaîne de requête de requête, consultez la documentation de référence de l'API.
POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas
Toutes les requêtes de création nécessitent que vous fournissiez les informations nécessaires pour les traiter. Si vous utilisez des bibliothèques clientes, elles convertissent les objets de données du langage de votre choix en objets au format de données JSON.
Requête JSON
L'exemple suivant montre une requête de création d'un schéma personnalisé. Pour obtenir la liste complète des propriétés de requête et de réponse, consultez la documentation de référence de l'API.
{
"schemaName": "employmentData",
"fields": [
{
"fieldName": "EmployeeNumber",
"fieldType": "STRING",
"multiValued": "false"
},
{
"fieldName": "JobFamily",
"fieldType": "STRING",
"multiValued": "false"
}
]
}
Les appels réussis renvoient un code d'état HTTP 201 ainsi que les propriétés du nouveau schéma personnalisé.
Limites des schémas personnalisés
- Le nombre maximal de schémas personnalisés autorisé par compte est de 100.
- Un compte peut comporter jusqu'à 100 champs personnalisés.
- Le nombre maximal de caractères autorisés dans un champ
string
pour un champ personnalisé à valeur unique est de 500. Pour les champs personnalisés à valeurs multiples, le nombre d'éléments autorisés dépend de la taille des valeurs attribuées. Par exemple, vous pouvez ajouter 150 valeurs de 100 caractères chacune ou 50 valeurs de 500 caractères chacune. - Les caractères autorisés dans les schémas et les noms de champs personnalisés sont les caractères alphanumériques, les traits de soulignement (
_
) et les traits d'union (-
). - La modification du type d'un champ n'est pas autorisée.
- Un champ à valeur unique peut devenir à valeurs multiples, mais l'opération inverse n'est pas autorisée.
- Il n'est pas possible de renommer les schémas ou les champs personnalisés.
Mettre à jour un schéma utilisateur personnalisé
Pour mettre à jour un schéma personnalisé, utilisez la requête PUT
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes. schemaKey
peut être le nom du schéma ou le schéma unique id
. Pour les propriétés des requêtes et des réponses, consultez la documentation de référence de l'API.
PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey
Requête JSON
Dans l'exemple ci-dessous, le schéma employmentData
contenait un champ JobFamily
lors de sa création initiale. La requête met à jour employmentData
pour ne contenir qu'un champ 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"
}
]
}
Toutes les demandes de mise à jour nécessitent que vous fournissiez les informations nécessaires pour les traiter.
Les réponses réussies renvoient un code d'état HTTP 200 avec la ressource de schéma mise à jour.
Récupérer un schéma d'utilisateur personnalisé
Pour récupérer un schéma personnalisé, utilisez la requête GET
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes. schemaKey
peut être le nom du schéma ou le schéma unique id
. Pour les propriétés des requêtes et des réponses, consultez la documentation de référence de l'API.
GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey
Les réponses réussies renvoient un code d'état HTTP 200 ainsi que les propriétés du schéma personnalisé.
{
"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"
}
]
}
Récupérer tous les schémas d'utilisateur personnalisés
Pour récupérer tous les schémas personnalisés d'un même compte, utilisez la requête GET
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.Pour connaître les propriétés des requêtes et des réponses, consultez la documentation de référence de l'API.
GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas
Les réponses réussies renvoient un code d'état HTTP 200 ainsi que les schémas personnalisés du compte.
{
"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"
}
]
}
]
}