Gestire i campi utente personalizzati

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

Per iniziare, crea uno o più schemi per definire i campi personalizzati più adatti al tuo dominio. Puoi specificare un numero di attributi, come il nome del campo, il tipo (stringa, booleano, intero e così via), se è a valore singolo o multiplo e se i suoi 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 del 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 a valore singolo sono impostati come semplici coppie chiave-valore, ad esempio "field1": "value1". I campi personalizzati a più valori sono impostati come array di oggetti, come i campi standard a più valori nell'API, ad esempio addresses e phones. Questi oggetti valore supportano le seguenti chiavi:

Chiavi
value Il valore da memorizzare, obbligatorio.
type Tipo di 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, rimane invariato. Se uno schema non è specificato in customFields al momento dell'aggiornamento, tutti i campi personalizzati dello schema rimangono invariati. Per eliminare un campo personalizzato o uno schema personalizzato da un profilo, devi impostarlo su null in modo esplicito:

"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 campi personalizzati in un profilo utente

Puoi eseguire ricerche all'interno dei 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 con un livello di lavoro superiore a 7. Per saperne di più, vedi Cercare utenti.

Creare uno schema utente personalizzato

È possibile aggiungere uno schema utente personalizzato a tutti i domini dell'account Google Workspace. Per creare uno schema utente personalizzato nei tuoi domini, utilizza la seguente richiesta POST 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

Tutte le richieste di creazione richiedono l'invio delle informazioni necessarie per soddisfare la richiesta. Se utilizzi le librerie client, queste convertono gli oggetti dati della lingua scelta in oggetti dati JSON formattati.

Richiesta JSON

Il seguente esempio mostra una richiesta per creare uno schema personalizzato. Per l'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à del 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 a valore singolo è 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 trasformato in un campo con più valori, ma l'operazione inversa non è consentita.
  • Non è possibile rinominare schemi o campi 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 al momento della creazione. La richiesta sta aggiornando 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"
    }
  ]
}

Tutte le richieste di aggiornamento richiedono l'invio delle informazioni necessarie per soddisfare la richiesta.

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

Recuperare uno schema utente personalizzato

Per recuperare uno schema personalizzato, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in 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à dello 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 nell'articolo 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"
        }
      ]
    }
  ]
}