Il Common Expression Language (CEL) è un linguaggio di espressione semplice progettato da Google. CEL viene utilizzato per scrivere formule veloci, portatili e sicure. Questa guida ti mostra tutte le funzioni che puoi utilizzare quando scrivi formule per creare espressioni efficaci.

Buono a sapersi

Per ulteriori informazioni, consulta le risorse ufficiali:

• Specifiche di CEL
• Implementazione di CEL Go
• Definizione del linguaggio CEL

Operazioni di base (Operatori)

La tabella seguente mostra i simboli di base che puoi usare nelle tue formule.

➡️ Per ulteriori informazioni, consulta Operatori CEL.

Funzioni disponibili

Conversione tra tipi

Le seguenti funzioni ti permettono di cambiare dati da un tipo all'altro.

➡️ Per ulteriori informazioni, consulta Conversioni dei tipi CEL.

bool() Converti in vero/falso

Cambia testo o altri valori in vero/falso.

Ad esempio:

bool(vero)        // restituisce: vero
bool("vero")      // restituisce: vero (converte il testo in vero/falso)
bool("falso")     // restituisce: falso

bytes() Conversione in dati binari

Converte i dati in byte (formato binario raw). La maggior parte degli utenti non ne avrà bisogno.

Ad esempio:

bytes(b'ciao')   // restituisce b'ciao'
bytes("ciao")    // restituisce: b'ciao' (converte il testo in binario)

doppio() Converte in numero decimale

Cambia valori in numeri decimali (numeri con una virgola, come 3,14).

Ad esempio:

double(3,14)      // restituisce: 3,14
double(42)        // restituisce: 42,0 (aggiunge una virgola decimale)
double("3,14")    // restituisce: 3,14 (converte il testo in numero)
double(100)       // restituisce: 100,0

int() Converte in numero intero

Cambia i valori in numeri interi (senza decimali).

Ad esempio:

int(42)                                 // restituisce: 42
int(3,14)                               // restituisce: 3 (rimuove ,14)
int(durata("1h"))                     // restituisce: 3600 (secondi in 1 ora)
int("123")                              // restituisce: 123 (converte testo)
int(timestamp("2024-01-01T00:00:00Z"))  // restituisce: 1704067200

stringa() Converte in testo

Trasforma qualsiasi valore in testo.

Ad esempio:

string("ciao")                        // restituisce: "ciao"
string(vero)                           // restituisce: "vero"
string(3,14)                           // restituisce: "3,14"
string(123)                            // restituisce: "123"
string(timestamp("2024-01-01T00:00:00Z")) // restituisce: "2024-01-01T00:00:00Z"

type() Scopri il tipo di un elemento

Ti dice che tipo di dati possiedi (testo, numero, vero/falso, etc.).

Ad esempio:

type(42)          // restituisce: int (tipo numero intero)
type("ciao")     // restituisce: stringa (tipo testo)
type(3,14)        // restituisce: doppio (tipo numero decimale)
type(vero)        // restituisce: bool (tipo vero/falso)

Lavorare con date e orari

Le seguenti funzioni ti permettono di lavorare con date, orari e timestamp.

➡️ Per ulteriori informazioni, consulta la documentazione Timestamp di CEL.

timestamp() Crea o converti una data/orario

Crea un valore di data e orario da origini diverse.

Ad esempio:

timestamp("2024-01-01T00:00:00Z")             // crea: gennaio 1, 2024 a mezzanotte
timestamp(1704067200)                         // crea: 2024-01-01T00:00:00Z

getFullYear() Restituisce l'anno

Restituisce l'anno da una data (come il 2024).

Ad esempio:

timestamp("2024-01-15T10:30:00Z").getFullYear()                      // restituisce: 2024
timestamp("2024-01-01T02:00:00Z").getFullYear("America/New_York")   // restituisce: 2023 (la sera del 31 dic.)
createdAt.getFullYear()                                              // restituisce un anno da createdAt

getMonth() Restituisce il mese

Restituisce il mese da una data.

Ad esempio:

timestamp("2024-03-15T10:30:00Z").getMonth()                        // restituisce: 2 (marzo è il terzo mese)
timestamp("2024-03-01T02:00:00Z").getMonth("America/New_York")     // restituisce: 1 (febbraio)
createdAt.getMonth()                                                // restituisce il mese da createdAt

// Ricorda: gennaio=0, febbraio=1, marzo=2, aprile=3, maggio=4, giugno=5,
//           luglio=6, agosto=7, settembre=8, ottobre=9, novembre=10, dicembre=11

getDate() Restituisce il giorno del mese

Restituisce il giorno del mese (1-31).

Ad esempio:

timestamp("2024-03-15T10:30:00Z").getDate()                         // restituisce: 15 (il giorno 15)
timestamp("2024-03-01T02:00:00Z").getDate("America/New_York")      // restituisce: 28 (28 febbraio)
createdAt.getDate()                                                 // restituisce il giorno da createdAt

getDayOfWeek() Restituisce il giorno della settimana

Restituisce il giorno della settimana.

Ad esempio:

timestamp("2024-03-15T10:30:00Z").getDayOfWeek()                    // restituisce: 5 (venerdì)
timestamp("2024-03-17T02:00:00Z").getDayOfWeek("America/New_York") // restituisce: 6 (sabato)

// Ricorda: domenica=0, lunedì=1, martedì=2, mercoledì=3,
//           giovedì=4, venerdì=5, sabato=6

getHours() Restituisce l'ora

Prende l'ora da un orario (0-23, dove 0 è mezzanotte e 23 sono le 23:00).

Ad esempio:

timestamp("2024-03-15T14:30:00Z").getHours()                        // restituisce: 14 (2:30 PM)
timestamp("2024-03-15T14:30:00Z").getHours("America/New_York")     // restituisce: 10 (10:30 AM EST)
durata("2h30m").getHours()                                        // restituisce: 2 ore

getMinutes() Restituisce i minuti

Restituisce i minuti da un orario (0-59).

Ad esempio:

timestamp("2024-03-15T14:45:00Z").getMinutes()                      // restituisce: 45 minuti
timestamp("2024-03-15T14:45:00Z").getMinutes("America/New_York")   // restituisce: 45 minuti
duration("2h30m").getMinutes()                                      // restituisce: 150 (minuti totali)

getSeconds() Restituisce i secondi

Restituisce i secondi da un orario (0-59).

Ad esempio:

timestamp("2024-03-15T14:45:30Z").getSeconds()                      // restituisce: 30 secondi
timestamp("2024-03-15T14:45:30Z").getSeconds("America/New_York")   // restituisce: 30 secondi
duration("2h30m45s").getSeconds()                                   // restituisce: 9045 (secondi totali)

Lavorare con periodi di tempo

Le seguenti funzioni ti permettono di creare e lavorare con durate (intervalli di tempo).

➡️ Per ulteriori informazioni, consulta Durate di CEL.

duration() Crea un periodo di tempo

Crea una durata che rappresenta un intervallo di tempo (non una data specifica).

Ad esempio:

duration(3600)              // crea: 1 ora (3600 secondi)
duration("1h30m")           // crea: 1 ora e 30 minuti
duration("90s")             // crea: 90 secondi
duration("2h")              // crea: 2 ore

Formato del periodo di tempo: Puoi usare h per le ore, m per i minuti, s per i secondi. Combina i valori come “1h30m15s”.

Funzioni testuali

Le seguenti funzioni ti permettono di lavorare con il testo (stringhe).

➡️ Per ulteriori informazioni, consulta Funzioni delle stringhe di CEL.

contains() Controlla se il testo contiene elementi

Controlla se una porzione di testo si trova all'interno di un'altra porzione di testo.

Ad esempio:

"ciao mondo".contains("mondo")     // restituisce: vero (testo trovato!)
"ciao mondo".contains("xyz")       // restituisce: falso (non trovato)
stato.contains("attivo")           // controlla se lo stato contiene "attivo"
email.contatto.contiene("@")         // controlla se l'email contiene il simbolo @

startsWith() Controlla se il testo inizia con un dato elemento

Controlla se il testo inizia con caratteri specifici.

Ad esempio:

"ciao mondo".startsWith("ciao")           // restituisce: vero
"ciao mondo".startsWith("mondo")           // restituisce: falso (inizia con "hello" non con "mondo")
email.contatto.startsWith("admin")           // controlla se l'email inizia con "admin"
stato.startsWith("in sospeso")                // controlla se lo stato inizia con "in sospeso"

endsWith() Controlla se lo stato termina con un dato testo

Controlla se il testo termina con caratteri specifici.

Ad esempio:

"ciao mondo".endsWith("mondo")             // restituisce: vero
"ciao mondo".endsWith("ciao")             // restituisce: falso (termina con "mondo" non con "ciao")
email.contatto.endsWith("@esempio.com")      // controlla se il dominio dell'email è @esempio.com
stato.endsWith("_approvato")                // controlla se lo stato termina con "_approvato"

matches() Controlla se il testo corrisponde a uno schema

Controlla se il testo corrisponde a uno schema (usa espressioni regolari - funzionalità avanzata).

Ad esempio:

// Controlla se il testo si presenta come un'email
"test@esempio.com".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")    // restituisce: vero
"non email".matches("^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$")        // restituisce: falso

// Conferma il formato email
email.contatto.matches("^[a-z]+@[a-z]+\\.[a-z]+$")                   // controlla il formato email

trim() Rimuove i caratteri da entrambe le estremità

Rimuove caratteri specifici dall'inizio e dalla fine del testo (come rimuovere gli spazi).

Ad esempio:

trim("  ciao  ", " ")      // restituisce: "ciao" (spazi rimossi)
trim("###test###", "#")     // restituisce: "testo" (simboli # rimossi)
trim("___name___", "_")     // restituisce: "nome" (trattini bassi rimossi)
trim("000123000", "0")      // restituisce: "123" (zeri rimossi)

ltrim() Rimuove i caratteri da sinistra (inizio)

Rimuove caratteri specifici solo dall'inizio del testo.

Ad esempio:

ltrim("  ciao  ", " ")     // restituisce: "ciao  " (spazi rimossi da sinistra)
ltrim("###test###", "#")    // restituisce: "testo###" (# rimossi da destra)
ltrim("000123", "0")        // restituisce: "123" (zeri rimossi da sinistra)

rtrim() Rimuove i caratteri da destra (fine)

Rimuove caratteri specifici solo dalla fine del testo.

Ad esempio:

rtrim("  ciao  ", " ")     // restituisce: "  ciao" (spazi rimossi da destra)
rtrim("###test###", "#")    // restituisce: "###test" (# rimossi da destra)
rtrim("123000", "0")        // restituisce: "123" (zeri rimossi da destra)

Funzioni matematiche

Le seguenti funzioni sono destinate ai calcoli matematici.

➡️ Per ulteriori informazioni, consulta Funzioni numeriche di CEL.

abs() Restituisce il valore assoluto

Rimuove il segno negativo da un numero (lo rende positivo).

Ad esempio:

abs(-5)                     // restituisce: 5
abs(10)                     // restituisce: 10 (già positivo)
abs(-100)                   // restituisce: 100
abs(0)                      // restituisce: 0

round() Arrotonda al numero intero più vicino

Arrotonda un numero decimale al numero intero più vicino.

Ad esempio:

round(3,7)                  // restituisce: 4 (arrotonda per eccesso)
round(3,2)                  // restituisce: 3 (arrotonda per difetto)
round(3,5)                  // restituisce: 4 (metà esatta, arrotonda per eccesso)
round(-2,5)                 // restituisce: -2
round(valore)               // arrotonda per valore della variabile

roundUp() Arrotonda sempre per eccesso

Arrotonda sempre al numero intero successivo (tetto).

Ad esempio:

roundUp(3,2)                // restituisce: 4 (arrotonda per eccesso anche se il numero è vicino a 3)
roundUp(3,9)                // restituisce: 4
roundUp(3,0)                // restituisce: 3 (numero già intero)
roundUp(-2,5)               // restituisce: -2

roundDown() Arrotonda sempre per difetto

Arrotonda sempre al numero intero precedente (base).

Ad esempio:

roundDown(3,8)              // restituisce: 3 (arrotonda per difetto anche se il numero è vicino a 4)
roundDown(3,2)              // restituisce: 3
roundDown(3,0)              // restituisce: 3 (numero già intero)
roundDown(-2,5)             // restituisce: -3

min() Trova il numero più piccolo

Restituisce il numero più piccolo tra due numeri.

Ad esempio:

min(5, 10)                  // restituisce: 5 (numero più piccolo)
min(-3, 2)                  // restituisce: -3 (i numeri negativi sono più piccoli)
min(età, 100)               // restituisce: il valore più piccolo, età o 100
min(3,5, 5)                 // restituisce: 3

Caso d'uso: min(età, 65) garantisce che l'età non superi i 65 anni.

max() Trova il numero più grande

Restituisce il numero più grande tra due numeri.

Ad esempio:

max(5, 10)                  // restituisce: 10 (numero più grande)
max(-3, 2)                  // restituisce: 2
max(età, 18)                // restituisce: il valore più grande, età o 18
max(3,5, 5)                 // restituisce: 5

Caso d'uso: max(età, 18) garantisce che l'età sia almeno di 18 anni.

Funzioni per mappe e liste

Le seguenti funzioni permettono di lavorare con liste (raccolte ordinate) e mappe (coppie di chiave-valore).

➡️ Per ulteriori informazioni, consulta la documentazione Liste di CEL e Mappe di CEL.

size() Conta gli elementi

Conta quanti elementi ci sono in una lista, in una mappa o quanti caratteri ci sono nel testo.

Ad esempio:

size([1, 2, 3])             // restituisce: 3 (tre elementi in una lista)
[1, 2, 3].size()            // restituisce: 3
partner.size()             // restituisce: il numero di partner
size({"a": 1, "b": 2})      // restituisce: 2 (due coppie chiave-valore)
indirizzi.size()            // restituisce: il numero di indirizzi
size("ciao")               // restituisce: 5 (cinque lettere)
"ciao".size()              // restituisce: 5
email.contatto.size() > 5    // verifica se l'email ha più di 5 caratteri

in() Controlla se esiste un oggetto

Controlla se un valore esiste in una lista o se una chiave è presente in una mappa.

Ad esempio:

5 in [1, 2, 3, 4, 5]                            // restituisce: vero (5 è nella lista)
10 in [1, 2, 3]                                 // restituisce: falso (10 non è nella lista)
"attivo" in ["attivo", "in sospeso", "completato"]  // restituisce: vero
"nome" in {"name": "John", "age": 30}           // restituisce: vero (il "nome" della chiave esiste)
"email" in {"name": "John", "age": 30}          // restituisce: falso (nessuna chiave "email")
"home" negli indirizzi                             // verifica se l'indirizzo "home" esiste

Le nostre raccomandazioni per i principianti

Per ulteriori informazioni, consulta: 

• Definizione del linguaggio CEL - Guida completa al linguaggio
• Tutorial introduttivo a CEL - Iniziare a usare CEL
• Migliori pratiche di CEL - Consigli e schemi

Comprensione dei tipi di dati

Per ulteriori informazioni, consulta Sistema di tipi di CEL.

• Testo (stringa): Parole e frasi, sempre tra virgolette: "ciao"
• Numeri (int): Numeri interi senza virgolette: 42
• Decimali (doppi): Numeri con virgole decimali: 3,14
• Vero/Falso (bool): Solo vero o falso, senza virgolette
• Liste: Più elementi tra parentesi: [1, 2, 3] oppure ["a", "b", "c"]
• Mappe: Coppie chiave-valore tra parentesi graffe: {"name": "John", "age": 30}

Uso delle funzioni membro (notazione a punto)

Alcune funzioni sono chiamate utilizzando un punto (.) dopo il valore:

"ciao".contains("e")           // Controlla se "ciao" contiene "e"
[1, 2, 3].size()                // Conta gli elementi in una lista
timestamp("2024-01-01T00:00:00Z").getFullYear()  // Restituisce l'anno dalla data

Uso delle funzioni regolari

Altre funzioni circondano il valore:

int("123")                      // Converte il testo in numero
round(3,7)                      // Arrotonda il decimale a un numero intero
min(5, 10)                      // Trova il numero più piccolo

Combinazione di funzioni

Puoi annidare funzioni una dentro l'altra:

string(round(3,7))              // Prima arrotonda 3,7 a 4, quindi converte a "4"
int(duration("1h"))             // Converte 1 ora in 3600 secondi

Fusi orari

Alcune funzioni di data accettano un fuso orario (come "America/New_York" o "Europa/Parigi"):

createdAt.getHours()                    // Restituisce l'ora in UTC (ora universale)
createdAt.getHours("America/New_York") // Restituisce l'ora nell'orario di New York

Ricorda

• I mesi partono da 0: gennaio è 0, dicembre è 11
• I giorni della settimana partono da 0: domenica è 0, sabato è 6
• Gli orari sono espressi in formato di 24 ore: 0 è mezzanotte, 13 è 13:00, 23 è 23:00 è 23:00
• Usa le virgolette per il testo: "ciao" non ciao
• Niente virgolette per i numeri: 42 non "42"

⏭️ E adesso?

• Documentazione ufficiale CEL
• Riferimento linguistico
• Area di pratica CEL

🤔 Domande?

In caso di domande, non esitare a contattare il team dell’assistenza creando un ticket dal tuo account. Se ancora non hai un account, puoi contattarci qui.

Se stai cercando aiuto per un progetto che prevede l'utilizzo di Brevo, possiamo metterti in contatto con l'agenzia partner di Brevo giusta per te.