Gérer les champs utilisateur personnalisés

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, leur emplacement physique, leur date d'embauche ou tout autre élément correspondant aux besoins de votre entreprise.

Pour commencer, créez un ou plusieurs schémas afin de définir les champs personnalisés qui conviennent à votre domaine. Vous pouvez spécifier un certain nombre d'attributs, tels que le nom du champ, le type (chaîne, valeur booléenne, 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 lorsque vous mettez à jour les utilisateurs de votre domaine, les récupérer avec users.get et users.list, et également rechercher des champs personnalisés.

Remarque : L'API Cloud Identity Groups peut également utiliser les champs personnalisés pour créer des requêtes de groupe dynamique permettant de définir les membres d'un groupe. Pour en savoir plus, consultez Formuler et tester une requête d'appartenance.

Avertissement : N'utilisez pas cette fonctionnalité pour stocker des informations personnelles sensibles telles que les identifiants de comptes, les numéros de carte d'identité nationale, les informations sur les titulaires de cartes, les données comptables, les informations de santé ou les informations concernant des parcours personnels.

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",
    ...
  },
  ...
}

Remarque : Chaque schemaName doit être unique pour un client. La réutilisation d'un nom génère une erreur 409: Entity already exists.

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 en tant que tableaux d'objets, comme les champs à valeurs multiples standards 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 : custom home other work
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 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 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

L'appel de l'exemple ci-dessous met à jour un utilisateur et définit des valeurs pour le schéma personnalisé 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" }
      ]
    }
  }
}

Lire les champs personnalisés dans un profil utilisateur

Vous pouvez récupérer des champs personnalisés dans 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 des recherches dans des champs personnalisés à l'aide du paramètre query dans une requête users.list. Vous demandez le champ personnalisé avec 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 dont le niveau de poste est supérieur à 7. Pour en savoir plus, consultez Rechercher des utilisateurs.

Créer un schéma d'utilisateur personnalisé

Vous pouvez ajouter un schéma utilisateur personnalisé à tous les domaines de votre compte Google Workspace. Pour créer un schéma utilisateur personnalisé dans vos domaines, utilisez la requête POST suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Pour en savoir plus sur les propriétés de la chaîne 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 demandes 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 de la langue de votre choix en objets de données JSON mis en forme.

Requête JSON

L'exemple suivant montre une requête permettant de créer 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"
    }
  ]
}

Une réponse réussie renvoie 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és dans un compte est de 100.
• Le nombre maximal de champs personnalisés autorisés dans un compte est de 100.
• 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 tirets (-).
• Vous ne pouvez pas modifier le type d'un champ.
• Un champ à valeur unique peut devenir un champ à valeurs multiples, mais l'opération inverse n'est pas autorisée.
• Il est impossible 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 Autoriser les requêtes. schemaKey peut être le nom du schéma ou l'id unique du schéma. Pour en savoir plus sur les propriétés de requête et de réponse, 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

Remarque : L'API est également compatible avec la sémantique des correctifs.

Requête JSON

Dans l'exemple ci-dessous, le schéma employmentData contenait un champ JobFamily lors de sa création. La requête met à jour employmentData pour qu'il ne contienne 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"
    }
  ]
}

Pour toutes les demandes de modification, vous devez fournir les informations nécessaires pour les traiter.

Une réponse réussie renvoie un code d'état HTTP 200, ainsi que 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 Autoriser les requêtes. schemaKey peut être le nom du schéma ou l'id unique du schéma. Pour en savoir plus sur les propriétés de requête et de réponse, 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

Une réponse réussie renvoie 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 utilisateur personnalisés

Pour récupérer tous les schémas personnalisés du même compte, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes.Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API.

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

Une réponse réussie renvoie un code d'état HTTP 200, ainsi que les schémas personnalisés pour le 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"
        }
      ]
    }
  ]
}