Come recuperare le azioni in Zoho

Recuperare le azioni in Zoho comporta l'iterazione sull'elenco delle azioni di un piano strutturato e l'esecuzione di ogni chiamata agli strumenti in sequenza, con il sistema che gestisce automaticamente i permessi di sola lettura rispetto a quelli di scrittura.

Perché è importante

Quando costruisci automazioni o flussi di lavoro assistiti dall'IA su Zoho, la tua integrazione deve recuperare ed eseguire in modo affidabile la sequenza corretta di azioni da un oggetto piano. Comprendere come funziona la pipeline di recupero ed esecuzione ti aiuta a fare il debug dei passaggi falliti, a gestire le domande di chiarimento in modo appropriato e a garantire che le credenziali di connessione siano valide prima che venga chiamato qualsiasi strumento.

Procedura passo dopo passo

Passaggio 1. Verifica che la tua connessione Zoho sia attiva prima di tentare di recuperare o eseguire qualsiasi azione. Il sistema chiama getzohoapi con il tuo userid e apptype per ottenere un handle API attivo e i metadati della connessione. Se non viene restituita alcuna connessione valida, la pipeline si interrompe immediatamente e restituisce un errore di riconnessione al chiamante. ^[2]

Passaggio 2. Analizza l'oggetto piano per accedere al suo elenco actions. Il piano è memorizzato come JSON (comunemente denominato plan_json) e puoi recuperare l'elenco con plan.get("actions"). Se il JSON è malformato o l'elenco è assente, il sistema registra il fallimento e restituisce un errore "Invalid plan" — quindi valida sempre il payload del piano prima di procedere. ^[4]

Passaggio 3. Itera su ogni azione nell'elenco. Ogni voce di azione contiene almeno una chiave tool (il nome dello strumento Zoho da invocare) e un dizionario params contenente gli argomenti per quello strumento. Scorri l'elenco ed estrai entrambi i valori per ogni passaggio. ^[1]

Passaggio 4. Valida ogni chiamata agli strumenti prima dell'esecuzione. Per ogni azione, chiama validatetoolcall con apptype, il nome dello strumento e i suoi params. Questo restituisce un livello di permesso — "read" o altro. Se ogni azione nel piano risolve al permesso "read", l'intero piano viene classificato come sola lettura e può essere eseguito immediatamente senza un passaggio di approvazione separato. Se un'azione non dispone del permesso "read", il flag allread_only viene impostato su False e il piano richiede una conferma esplicita dell'utente prima di essere applicato. ^[5]

Passaggio 5. Esegui ogni azione usando executetoolwithrepair. Passa l'handle api, apptype, il nome del tool e i params. Per gli strumenti di sola lettura, imposta allowrepair=True in modo che il sistema possa riprovare automaticamente con parametri corretti se il primo tentativo fallisce. La funzione restituisce un dizionario execout contenente il result e, facoltativamente, una clarifyingquestion se lo strumento necessita di ulteriori informazioni dall'utente. ^[3]

Passaggio 6. Controlla l'output di ogni esecuzione. Se execout.get("clarifyingquestion") è popolato, metti in pausa il ciclo delle azioni, mostra la domanda all'utente e registrala nel tuo archivio dei messaggi di chat prima di rilasciare eventuali blocchi di concorrenza. Se il risultato è un dizionario contenente una chiave "error", acquisisci quel messaggio di errore per la visualizzazione. In caso contrario, considera l'azione come completata con successo. ^[2]

Passaggio 7. Dopo un'esecuzione riuscita, costruisci i link contestuali ai record interessati usando buildzoholinks. Fornisci il result, il nome dello strumento risolto (execout.get("tool") or tool), i params risolti, apptype, il codice del data center (dc) e gli identificatori org/portale dai metadati della connessione (crmorgid, deskorgid, desk_portal). Questi link consentono agli utenti di navigare direttamente verso i record che sono stati letti o modificati. ^[8]

Passaggio 8. Per gli strumenti basati su browser (come browsernavigateandscreenshot per ispezionare le pagine di amministrazione di Zoho), il percorso di esecuzione è leggermente diverso. Il BROWSERTOOLREGISTRY viene controllato per primo per confermare che lo strumento esista, poi vengono validati i params obbligatori e infine viene verificato lo stato di autenticazione della sessione del browser. Se la sessione è scaduta, il sistema restituisce un campo actionrequired che ti indica di ri-autenticarti tramite l'endpoint di login del browser. ^[7]

Errori comuni

• Connessione Zoho mancante: Se getzohoapi non restituisce nulla, nessuna azione verrà eseguita. Verifica sempre che la connessione sia stabilita e che il corretto app_type sia specificato prima di avviare un piano. ^[4]
• JSON del piano non valido: Una stringa plan_json malformata causa l'interruzione dell'intera operazione di applicazione. Il sistema registra un campione del payload errato (fino a 200 caratteri) per facilitare il debug. ^[4]
• Superamento del limite del numero di azioni: Il sistema controlla planactioncount rispetto a Config.MAXPLANACTIONS quando il flag di applicazione del motore del flusso di lavoro è attivo. I piani con troppe azioni possono essere rifiutati prima che venga chiamato qualsiasi strumento. ^[4]
• Scadenza della sessione del browser: Per le chiamate agli strumenti basati su browser, una sessione scaduta o non autenticata restituisce un errore anziché fallire silenziosamente — presta attenzione alla chiave "action_required" nella risposta. ^[7]
• Azioni non di sola lettura in modalità streaming: Nell'endpoint del piano in streaming, i piani di sola lettura vengono eseguiti inline con un feed di stato in tempo reale. I piani contenenti azioni di scrittura vengono invece restituiti al client come payload di piano in sospeso, richiedendo un passaggio di applicazione separato. ^[5]

Cosa verificare

• Conferma che getzohoapi restituisca un handle API valido e che il valore dc (data center) nei metadati della connessione corrisponda alla regione del tuo account Zoho.
• Verifica che la chiave tool di ogni azione corrisponda a un nome di strumento registrato e che tutti i params REQUIRED siano presenti prima di inviare il piano.
• Dopo l'esecuzione, ispeziona il campo status su ogni risultato — cerca "success" rispetto a "error" — e conferma che buildzoholinks restituisca URL di record navigabili per tutti i dati interessati. ^[3][8]

---

*Beam Help fornisce supporto esperto indipendente per Zoho e non è il supporto ufficiale di Zoho. Testa sempre l'esecuzione del piano in un ambiente sandbox prima di applicare modifiche ai dati di produzione.*