Gestisci campi utente personalizzati

Puoi definire campi personalizzati per gli utenti del tuo dominio aggiungendo schemi personalizzati per gli utenti al dominio. Puoi utilizzare questi campi per archiviare informazioni quali i progetti su cui lavorano gli utenti, le loro sedi fisiche, la data di assunzione o qualsiasi altra informazione adatta alle esigenze della tua attività.

Per iniziare, crea uno o più schemi per definire i campi personalizzati appropriati per il tuo dominio. Puoi specificare un numero di attributi, ad esempio il nome del campo, il tipo (stringa, booleano, intero e così via), se è a valore singolo o multiplo e se i relativi valori sono visibili a qualsiasi utente del tuo dominio o solo agli amministratori e all'utente associato.

Una volta definito uno schema, i campi personalizzati si comportano come i campi standard. Puoi impostarli quando aggiorni gli utenti nel tuo dominio, recuperarli con users.get e users.list e anche cercare i campi personalizzati.

Impostare campi personalizzati in un profilo utente

Per aggiornare o creare uno schema, crea una customSchemasproprietà e aggiungila alla risorsa utente. All'interno della proprietà customSchemas, i campi personalizzati sono raggruppati per schema in formato JSON standard:

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

I campi personalizzati con un solo valore vengono impostati come semplici coppie chiave-valore, ad esempio "field1": "value1". I campi personalizzati a più valori vengono impostati come array di oggetti, come i campi a più valori standard dell'API, ad esempio addresses e phones. Questi oggetti valore supportano le seguenti chiavi:

Chiavi
value Il valore da memorizzare, obbligatorio.
type Tipo del valore, facoltativo. I valori possibili sono:
  • custom
  • home
  • other
  • work
customType Tipo personalizzato del valore, facoltativo. Deve essere utilizzato quando type è impostato su custom.

Se un campo personalizzato in uno schema non viene specificato al momento dell'aggiornamento, viene lasciato immutato. Se uno schema non è specificato in customFields al momento dell'aggiornamento, tutti i campi personalizzati in quel determinato schema rimangono invariati. Per eliminare un campo personalizzato o uno schema personalizzato da un profilo, devi impostarlo su null esplicitamente:

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

Richiesta JSON

La chiamata nell'esempio seguente aggiorna un utente e imposta i valori per lo schema personalizzato 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" }
      ]
    }
  }
}

Leggere i campi personalizzati in un profilo utente

Puoi recuperare i campi personalizzati in un profilo utente impostando il parametro projection in una richiesta users.get o users.list su custom o full.

Cercare i campi personalizzati in un profilo utente

Puoi eseguire ricerche nei campi personalizzati utilizzando il parametro query in una richiesta users.list. Richiedi il campo personalizzato con una sintassi schemaName.fieldName. Ad esempio:

employmentData.projects:"GeneGnome"

restituisce tutti i dipendenti che lavorano al progetto GeneGnome. La query

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

restituisce tutti i dipendenti di Atlanta di livello superiore a 7. Per ulteriori informazioni, consulta Cercare utenti.

Creare uno schema utente personalizzato

Uno schema utente personalizzato può essere aggiunto a tutti i domini del tuo account Google Workspace. Per creare uno schema utente personalizzato nei tuoi domini, utilizza la seguente richiestaPOST e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. Per le proprietà della stringa di query della richiesta, consulta il riferimento API.

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

Per tutte le richieste di creazione è necessario inviare le informazioni necessarie per soddisfare la richiesta. Se utilizzi le librerie client, queste convertono gli oggetti dati dalla lingua scelta in oggetti formattati con dati JSON.

Richiesta JSON

L'esempio seguente mostra una richiesta per creare uno schema personalizzato. Per un elenco completo delle proprietà di richiesta e risposta, consulta il riferimento API.

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

Una risposta riuscita restituisce un codice di stato HTTP 201, insieme alle proprietà per il nuovo schema personalizzato.

Limiti degli schemi personalizzati

  • Il numero massimo di schemi personalizzati consentiti in un account è 100.
  • Il numero massimo di campi personalizzati consentiti in un account è 100.
  • Il numero massimo di caratteri consentiti in un campo string per un campo personalizzato con un solo valore è 500. Per i campi personalizzati con più valori, il numero di elementi consentiti dipende dalle dimensioni dei valori assegnati. Ad esempio, puoi aggiungere 150 valori di 100 caratteri ciascuno o 50 valori di 500 caratteri ciascuno.
  • I caratteri consentiti negli schemi personalizzati e nei nomi dei campi sono caratteri alfanumerici, trattini bassi (_) e trattini (-).
  • Non è consentita la modifica del tipo di un campo.
  • Un campo con un unico valore può essere reso multivalore, ma l'operazione inversa non è consentita.
  • Non è possibile rinominare campi o schemi personalizzati.

Aggiornare uno schema utente personalizzato

Per aggiornare uno schema personalizzato, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. schemaKey può essere il nome dello schema o lo schema univoco id. Per le proprietà della richiesta e della risposta, consulta il riferimento API.

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

Richiesta JSON

Nell'esempio seguente, lo schema employmentData conteneva un campo JobFamily quando è stato creato inizialmente. La richiesta aggiorna employmentData in modo che 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"
    }
  ]
}

Per tutte le richieste di aggiornamento devi inviare le informazioni necessarie per soddisfare la richiesta.

Una risposta riuscita restituisce un codice di stato HTTP 200, insieme alla risorsa schema aggiornata.

Recuperare uno schema utente personalizzato

Per recuperare uno schema personalizzato, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. schemaKey può essere il nome dello schema o lo schema univoco id. Per le proprietà della richiesta e della risposta, consulta il riferimento API.

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

Una risposta riuscita restituisce un codice di stato HTTP 200, insieme alle proprietà per lo schema personalizzato.

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

Recuperare tutti gli schemi utente personalizzati

Per recuperare tutti gli schemi personalizzati nello stesso account, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste.Per le proprietà della richiesta e della risposta, consulta il Riferimento API.

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

Una risposta riuscita restituisce un codice di stato HTTP 200, insieme agli schemi personalizzati per l'account.

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