Gestisci 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 quali i progetti a cui gli utenti lavorano, la loro posizione fisica, 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 pertinenti per il tuo dominio. Puoi specificare una serie di attributi, ad esempio il nome del campo, il tipo (stringa, booleano, numero intero e così via), se si tratta di un valore singolo o multivalore e se i relativi valori possono essere visualizzati da qualsiasi utente del dominio o solo dagli amministratori e dall'utente associato.

Una volta definito uno schema, i campi personalizzati si comportano come i campi standard. Puoi impostarle durante l'aggiornamento degli utenti sul tuo dominio, recuperarli con users.get e users.list e anche cercare campi personalizzati.

Nota: i campi personalizzati possono essere utilizzati anche dall'API Cloud Identity Groups per creare query di gruppi dinamici al fine di definire l'appartenenza ai gruppi. Per ulteriori informazioni, consulta Formulazione e test di una query di appartenenza.

Avviso: non utilizzare questa funzionalità per archiviare informazioni sensibili che consentono l'identificazione personale, come credenziali dell'account, numeri di identificazione ufficiali, dati del titolare della carta, dati del conto finanziario, informazioni sanitarie o informazioni di base sensibili.

Impostazione di campi personalizzati in un profilo utente

Per aggiornare o creare uno schema, crea una proprietà customSchemas 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",
    ...
  },
  ...
}

Nota: ogni schemaName deve essere univoco all'interno di un cliente. Il riutilizzo di un nome genera un errore 409: Entity already exists.

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

Chiavi
value	Il valore da archiviare, 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 al momento dell'aggiornamento non viene specificato un campo personalizzato in uno schema, il campo rimane invariato. Se uno schema non viene specificato in customFields al momento dell'aggiornamento, tutti i campi personalizzati nello schema rimangono invariati. Per eliminare un campo o uno schema personalizzato da un profilo, devi impostarlo esplicitamente su null:

"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/[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" }
      ]
    }
  }
}

Lettura di 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 cercare all'interno dei campi personalizzati utilizzando il parametro query in una richiesta users.list. Puoi richiedere 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 ad Atlanta sopra il livello di lavoro 7. Per scoprire di più, consulta Ricerca di utenti.

Creare uno schema utente personalizzato

Puoi aggiungere uno schema utente personalizzato a tutti i domini del tuo account Google Workspace. Per creare uno schema utente personalizzato nei tuoi domini, utilizza la seguente richiesta POST e includi l'autorizzazione descritta in Autorizzare le richieste. Per le proprietà della stringa di query di richiesta, consulta la documentazione di 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 librerie client, queste convertono gli oggetti dati del linguaggio scelto in oggetti con formato dati JSON.

Richiesta JSON

Il seguente esempio mostra una richiesta di creazione di uno schema personalizzato. Per l'elenco completo delle proprietà delle richieste e delle risposte, consulta la documentazione di riferimento API.

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

Una risposta corretta restituisce un codice di stato HTTP 201, insieme alle proprietà del nuovo schema personalizzato.

Limiti degli schemi personalizzati

• Il numero massimo di schemi personalizzati consentito 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 a 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 è consentito modificare il tipo di un campo.
• Un campo con un solo valore può essere impostato su più valori, ma l'operazione inversa non è consentita.
• Non è possibile rinominare schemi o campi personalizzati.

Aggiorna uno schema utente personalizzato

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

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

Nota: l'API supporta anche la semantica della patch.

Richiesta JSON

Nell'esempio seguente, lo schema employmentData conteneva un campo JobFamily quando creato inizialmente. La richiesta è in fase di aggiornamento di employmentData in modo da contenere 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, usa 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à richiesta e risposta, consulta la documentazione di riferimento API.

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

Una risposta corretta 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"
    }
  ]
}

Recupera 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à di richiesta e risposta, consulta la documentazione di riferimento API.

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

Una risposta corretta 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"
        }
      ]
    }
  ]
}