La creazione di una query nel Developer Hub di Zoho CRM consente di definire operazioni di recupero dati riutilizzabili e filtrabili su moduli CRM, database esterni o API REST di terze parti — il tutto da un'unica interfaccia di configurazione.
Perché è importante
Quando è necessario estrarre programmaticamente sottoinsiemi specifici di dati CRM — ad esempio, tutte le trattative aperte collegate a un determinato contatto — inserire chiamate API hardcoded in ogni integrazione diventa rapidamente ingestibile. La funzionalità Queries di Zoho CRM offre una query con nome e versione che puoi referenziare in funzioni, widget e script client senza duplicare la logica. [1] Come team di esperti indipendenti (Beam Help — non il supporto ufficiale Zoho), troviamo questa funzionalità particolarmente utile nella creazione di dashboard o automazioni che dipendono da set di record filtrati e coerenti.
---
Procedura passo dopo passo
Passaggio 1. Vai su Setup → Developer Hub → Queries. Si aprirà la finestra Queries, che elenca tutte le query già definite nella tua organizzazione. [1]
Passaggio 2. Fai clic su Add Query per aprire la finestra di dialogo di creazione. [1]
Passaggio 3. Nel pop-up Create Query, inserisci un Query Name leggibile e un API Name (utilizzato per referenziare la query a livello programmatico), quindi fai clic su Next. [1]
Passaggio 4. Nella sezione Configuration, il tipo di sorgente predefinito è Zoho CRM Module. Se hai bisogno di una sorgente diversa — come un endpoint REST API, un database relazionale self-hosted (MySQL, Microsoft SQL, PostgreSQL) o un database cloud (Amazon RDS, Google Cloud Platform, Microsoft Azure) — fai clic su Change per cambiare il tipo di sorgente. [1][7]
Passaggio 5. Seleziona il modulo CRM che desideri interrogare. Tieni presente che anche i sottomoduli sono supportati come destinazioni interrogabili, offrendoti un accesso granulare ai dati delle voci all'interno dei record. [1]
Passaggio 6. Se il modulo scelto contiene campi di lookup, puoi includere dati correlati selezionando fino a due moduli correlati dal menu a discesa Related Module. [1]
Passaggio 7. Scegli i campi specifici che desideri restituire dal menu a discesa Fields. Puoi selezionare un massimo di 50 campi per query. [1]
Passaggio 8. Configura la sezione Criteria. Hai tre opzioni: [1]
- None — restituisce tutti i record senza alcun filtro applicato.
- Record ID — filtra la risposta a un singolo record tramite il suo identificatore univoco.
- Criteria — applica una logica condizionale su uno o più campi. Puoi combinare le condizioni usando gli operatori AND / OR e utilizzare comparatori appropriati a ciascun tipo di campo.
Passaggio 9. Per ogni criterio, decidi se fornire un valore statico (fisso al momento della creazione della query) o un valore dinamico. Scegliere dinamico significa che il valore effettivo viene passato in fase di esecuzione — ad esempio, quando la query viene richiamata da una funzione o da un widget — rendendo la query riutilizzabile su record o contesti diversi. [1]
Passaggio 10. Salva la query. Apparirà ora nell'elenco Queries e potrà essere referenziata tramite il suo API name da Zoho CRM Functions, Client Scripts, Widget o chiamate SDK lato server. [1][8]
---
Errori comuni
- Limite dei moduli correlati: Puoi includere dati da un massimo di due moduli correlati tramite lookup in una singola query. Il tentativo di aggiungerne altri non sarà consentito nell'interfaccia di configurazione. [1]
- Limite del numero di campi: Non è consentito selezionare più di 50 campi in una singola query. Se hai bisogno di più campi, considera di suddividere la logica in due query separate. [1]
- Sorgenti database esterne — whitelist degli IP: Quando si utilizza un database MySQL, PostgreSQL o Microsoft SQL self-hosted come sorgente di query, è necessario inserire nella whitelist gli indirizzi IP di Zoho CRM sul server relay e aggiungere l'host ai Trusted Domains se non è espresso come indirizzo IP grezzo. Saltare questo passaggio causerà errori di connessione. [7]
- SSL e configurazione avanzata: Sia per i database standard che per quelli cloud, opzioni come il timeout della connessione, il fuso orario e l'applicazione SSL si trovano in Advanced Configuration all'interno della configurazione della sorgente — facile da trascurare se si procede rapidamente nella procedura guidata. [7]
- Valori dinamici vs. statici: Un errore comune è impostare un valore come statico durante i test e dimenticare di cambiarlo in dinamico prima del deployment. Un criterio statico filtrerà sempre sullo stesso valore hardcoded, il che raramente corrisponde al comportamento desiderato nei flussi di lavoro in produzione. [1]
---
Cosa verificare
- La query restituisce i record attesi: Dopo il salvataggio, utilizza l'opzione di test/anteprima integrata per confermare che la logica dei criteri produca il set di risultati filtrato corretto prima di collegare la query a qualsiasi automazione.
- L'API Name è univoco e referenziato correttamente: Verifica che l'API name assegnato corrisponda esattamente a quanto referenziato in eventuali Functions, Client Scripts o chiamate SDK che utilizzano questa query. [1][8]
- Connettività della sorgente (per sorgenti esterne): Se la query punta a un'API REST esterna o a un database, conferma che la connessione sia attiva e che gli IP di Zoho CRM siano nella whitelist dell'host remoto prima di andare in produzione. [7]