Documentazione · Opengency

Guida rapida

Registrati e accedi all'app Web.
Crea un nuovo flusso di lavoro: nell’area di lavoro è già presente un nodo «Trigger», che è il punto di partenza.
Trascina fuori un nodo "Azione", scegli un connettore (ad esempio Email) e completa le impostazioni.
Collega il nodo trigger al nodo azione e salva.
Fai clic su Esegui, inserisci alcuni dati di prova e controlla il risultato di ogni nodo nel log di esecuzione.

Guida alla modifica dei flussi di lavoro

Un flusso di lavoro è composto da tre tipi di nodi:

Trigger: il punto di partenza; ogni flusso di lavoro ne ha esattamente uno. I dati ricevuti in fase di esecuzione diventano il suo output.
Condizione: esegue una verifica, con uscite "Sì" e "No": viene eseguito solo il ramo corrispondente.
Azione: richiama un connettore, ad esempio per inviare un'email, chiamare un'API o scrivere in un database.

Al salvataggio vengono verificati: esattamente un nodo trigger, ogni collegamento con entrambe le estremità presenti, nessun ciclo, uscite delle condizioni etichettate Sì/No, e tutti i campi obbligatori di ogni azione compilati. Eventuali problemi vengono elencati uno per uno.

In fase di esecuzione, il flusso segue i collegamenti a partire dal nodo trigger; se un nodo qualsiasi fallisce, l'intera esecuzione si interrompe immediatamente e viene segnata come non riuscita.

Condizioni

Una condizione è composta da un valore sinistro, un operatore e un valore destro; entrambi i lati possono essere un valore fisso oppure un riferimento (vedi la sezione successiva).

Operatore	Significato	Esempio
eq / ne	uguale a / diverso da	$.input.status eq "paid"
gt / gte	maggiore di / maggiore o uguale a	$.input.amount gt 1000
lt / lte	minore di / minore o uguale a	$.input.stock lt 10
in	il valore sinistro è nell'elenco a destra	$.input.city in ["北京", "上海"]
contains	il valore sinistro contiene il valore destro	$.input.tags contains "VIP"
exists	il campo esiste e non è vuoto	$.input.coupon exists

Se il campo referenziato non esiste, exists restituisce "No", e anche tutti gli altri operatori restituiscono "No".

Passaggio di valori tra nodi

Nelle impostazioni di una condizione o di un'azione, qualsiasi valore che inizia con $. viene sostituito con i dati di esecuzione:

$.input.amount          运行时传入数据的 amount 字段
$.query.data.0.name     节点 query 输出中 data 列表第 1 项的 name
$.notify.status         节点 notify 输出的 status

Quando il valore di un campo è esattamente un riferimento, la sostituzione mantiene il tipo originale (numeri, elenchi e oggetti funzionano tutti). Per inserire un dato nel mezzo di un testo, usa {{$.path}}:

大额订单 {{$.input.order_id}}：金额 {{$.input.amount}}，请风控复核

Le stringhe vengono inserite così come sono; numeri, elenchi e oggetti vengono convertiti in JSON; i valori vuoti vengono inseriti come vuoti.
Se il percorso non esiste, viene sostituito con nulla (un riferimento sull'intero valore diventa vuoto): non fa fallire il nodo, ma viene segnalato nel passaggio corrispondente del log di esecuzione.
Solo i valori che iniziano con $. sono considerati riferimenti: "$100 di sconto", ad esempio, è semplice testo.
Oggetto e corpo dell'email supportano inoltre i modelli {{variable}}, con variabili prese dall'output di un nodo precedente.

Guida ai connettori

Da dove vengono l'indirizzo e le credenziali di ciascun connettore, dove si trova la documentazione ufficiale e cosa fare in caso di errori comuni. Il pannello «Come ottengo queste informazioni?» sopra ogni modulo del connettore nell'app è una versione sintetica di questa guida.

HTTP

Passaggi di configurazione

Prepara l'URL dell'endpoint (url) e il metodo della richiesta (GET, POST, …).
Se l'API richiede autenticazione, scegli basic o bearer in auth_type e inserisci nome utente e password oppure il token. Non inserire le credenziali direttamente in headers: verrebbero salvate in chiaro.

Documentazione ufficiale ↗

Obbligatorio: url
Opzionale: method (predefinito GET), headers, body, query_params, auth_type (none / basic / bearer), timeout, retries

Quando body è vuoto, viene inviato l'output del nodo precedente. Può raggiungere solo indirizzi pubblici.

Errori comuni

«not a public address»: la destinazione è un indirizzo interno o locale (anche se un reindirizzamento porta lì) ed è bloccata per sicurezza.
Sono supportati solo URL http e https.
Quando body è vuoto, viene inviato l'output del nodo precedente.
Il timeout predefinito è di 30 secondi e può arrivare al massimo a 60.

DingTalk

Passaggi di configurazione

Apri il gruppo DingTalk → Impostazioni gruppo → Assistente gruppo → Aggiungi robot → Personalizzato (tramite Webhook).
Come impostazione di sicurezza scegli Firma o Parole chiave personalizzate (puoi attivarle entrambe). Con Firma, copia in secret la chiave che inizia con SEC. Con le parole chiave, inserisci una parola che compare sempre nei tuoi messaggi e aggiungi anche Opengency come parola chiave, perché «Testa connessione» invia il testo «Opengency 连接测试».
Copia l'URL webhook generato in webhook_url.

Documentazione ufficiale ↗

Obbligatorio: webhook_url
Opzionale: secret (chiave di firma), msg_type (text / markdown / link / card), message, at_mobiles, at_all

Ottieni webhook_url dalle impostazioni del gruppo DingTalk → Assistente del gruppo → Aggiungi bot. "Testa connessione" invia realmente un messaggio di prova al gruppo. Il testo del messaggio di prova è fisso: «Opengency 连接测试». Se il robot usa parole chiave personalizzate, una di esse deve essere «Opengency», altrimenti il test viene rifiutato per parola chiave non corrispondente (non succede se è attiva solo la firma).

Errori comuni

Firma non corrispondente (sign not match): il robot usa Firma, ma secret è vuoto o errato. Inserisci la chiave di firma che inizia con SEC, non l'access_token dell'URL del webhook.
Parola chiave non corrispondente: il messaggio non contiene nessuna delle parole chiave del robot. Inserisci una parola chiave nel messaggio, oppure aggiungi al robot una parola chiave che i tuoi messaggi conterranno.
Timestamp non valido: l'orologio del server su cui gira Opengency differisce da quello di DingTalk di oltre un'ora. Correggi l'ora del server.
«Testa connessione» non è una simulazione: invia davvero «Opengency 连接测试» al gruppo.

WeCom

Passaggi di configurazione

Apri il gruppo WeCom → «…» in alto a destra → Robot del gruppo → Aggiungi robot.
L'URL webhook viene mostrato non appena il robot viene creato.
Copia quell'URL in webhook_url.

Documentazione ufficiale ↗

Obbligatorio: webhook_url
Opzionale: msg_type (text / markdown / card), message, at_mobiles, at_all, url e title (per card)

Ottieni webhook_url dal gruppo WeCom → Bot del gruppo; la key nell'URL è la credenziale. Le menzioni @ funzionano solo con text. "Testa connessione" invia realmente un messaggio di prova al gruppo.

Errori comuni

La key nell'URL webhook è la credenziale: chiunque abbia l'URL può pubblicare nel gruppo. In caso di fuga, rimuovi il robot dal gruppo e aggiungine uno nuovo.
Le menzioni @ funzionano solo con il tipo text. Il tipo card richiede anche url (dove porta il link della card); senza, il salvataggio fallisce.
WeCom limita la frequenza dei robot che pubblicano troppo spesso, e i messaggi smettono di arrivare. Non pianificare le esecuzioni troppo ravvicinate.
«Testa connessione» pubblica davvero un messaggio di prova nel gruppo.

Feishu

Passaggi di configurazione

Apri il gruppo Feishu → Impostazioni → Robot del gruppo → Aggiungi robot → Robot personalizzato.
Per sicurezza puoi attivare la Verifica della firma e inserire in secret la chiave mostrata in quella pagina. Funzionano anche le Parole chiave personalizzate; aggiungi anche lì «Opengency» come parola chiave.
Copia l'URL webhook generato in webhook_url.

Documentazione ufficiale ↗

Obbligatorio: webhook_url
Opzionale: secret (se il bot ha la verifica della firma attiva), msg_type (text / post / markdown / card), message, title, at_open_ids, at_all

Ottieni webhook_url dalle impostazioni del gruppo Feishu → Bot del gruppo → Bot personalizzato. "Testa connessione" invia realmente un messaggio di prova al gruppo.

Errori comuni

La verifica della firma è attiva ma secret è vuoto o errato: Feishu rifiuta il messaggio (verifica della firma fallita). La chiave può essere rivista nelle impostazioni del robot.
Sono impostate parole chiave personalizzate ma il messaggio non ne contiene nessuna: il messaggio viene rifiutato.
at_open_ids richiede open_id che iniziano con ou_, non numeri di telefono o nomi.
«Testa connessione» pubblica davvero un messaggio di prova nel gruppo.

Slack

Passaggi di configurazione

Apri https://api.slack.com/apps, crea un'app (o scegline una esistente) e attiva Incoming Webhooks in Features.
Fai clic su Add New Webhook to Workspace, scegli il canale in cui pubblicare e autorizza.
Copia l'URL del webhook generato (inizia con https://hooks.slack.com/services/) in webhook_url.

Documentazione ufficiale ↗

Obbligatorio: webhook_url
Opzionale: message, username, icon_emoji, channel

webhook_url è essa stessa la credenziale (chiunque la possieda può pubblicare in quel canale); Opengency la memorizza cifrata e la maschera nell'interfaccia e nei log. Un webhook di un'app Slack attuale pubblica sempre nel canale scelto alla creazione, quindi username, icon_emoji e channel vengono ignorati; per pubblicare altrove, crea un altro webhook. «Testa connessione» pubblica davvero un messaggio di prova nel canale.

Errori comuni

no_service: il webhook è stato eliminato, disattivato, o l'indirizzo è sbagliato. Controlla la pagina Incoming Webhooks dell'app, e ricrealo e aggiorna la connessione se necessario.
channel_not_found: il canale non esiste, oppure questo webhook non vi ha accesso. Controlla il nome del canale, oppure ricrea il webhook per il canale giusto.
channel_is_archived: il canale è archiviato. Rimuovi l'archiviazione, oppure usa il webhook di un altro canale.
action_prohibited: un amministratore dello spazio di lavoro limita ciò che questo webhook può fare. Contatta il tuo amministratore Slack.
invalid_payload o no_text: il messaggio è vuoto o malformato. Assicurati che message non sia vuoto.
HTTP 429: stai pubblicando troppo spesso e Slack sta limitando la frequenza. Riprova più tardi, e non pianificare esecuzioni troppo ravvicinate.
«Testa connessione» non è una simulazione: pubblica davvero «Opengency connection test» nel canale.

Teams

Passaggi di configurazione

In Teams apri il canale in cui pubblicare → il «…» accanto al nome del canale → Workflows.
Scegli il modello «Send webhook alerts to a channel», seleziona team e canale come richiesto, e salva.
Dopo la creazione, copia l'URL del webhook dalla pagina dei dettagli del flusso in webhook_url.

Documentazione ufficiale ↗

Obbligatorio: webhook_url
Opzionale: message, title

webhook_url è essa stessa la credenziale (il sig nell'indirizzo è la firma del flusso); Opengency la memorizza cifrata e la maschera nell'interfaccia e nei log. Sono supportati solo i webhook di Workflows (Power Automate); i vecchi webhook dell'Office 365 connector (outlook.office.com/webhook/…) sono in via di dismissione da parte di Microsoft e non sono supportati. I messaggi vengono inviati come Adaptive Card: title è il titolo in grassetto in cima alla scheda, message è il corpo (il Markdown di base funziona). Un messaggio non può superare i 28 KB; un corpo troppo lungo viene troncato. «Testa connessione» pubblica davvero un messaggio di prova nel canale.

Errori comuni

HTTP 401 / 403 (indirizzo non valido o revocato): la firma nell'URL del webhook è sbagliata o è stata rigenerata. Apri il flusso in Teams, copia l'indirizzo più recente e aggiorna la connessione.
HTTP 404 (flusso non trovato): il flusso potrebbe essere stato eliminato. Ricrealo dal modello e aggiorna l'indirizzo nella connessione.
Un messaggio che indica che il flusso è disattivato: riattivalo nell'app Teams Workflows o in Power Automate. Un flusso appartiene a chi lo ha creato, e può essere disattivato se questa persona lascia l'azienda o il suo account viene disabilitato; chiedi a un amministratore di trasferirlo a qualcun altro.
HTTP 400 (il trigger non ha accettato il messaggio): assicurati che il flusso sia stato creato dal modello «Send webhook alerts to a channel», che il suo trigger sia When a Teams webhook request is received, e di non aver modificato il formato di messaggio che accetta.
HTTP 429: Teams limita la frequenza dei webhook (circa quattro richieste al secondo), e pubblicare troppo spesso viene rifiutato. Riprova più tardi, e non pianificare esecuzioni troppo ravvicinate.
«Testa connessione» non è una simulazione: pubblica davvero «Opengency connection test» nel canale.

Email

Passaggi di configurazione

Attiva l'SMTP nelle impostazioni del tuo provider di posta.
Genera una password per app (alcuni provider la chiamano codice di autorizzazione). La maggior parte dei provider, tra cui Gmail, Outlook e Yahoo, non permette alle app di terze parti di inviare posta con la password di accesso.
Annota il server SMTP e la porta, ad esempio smtp.gmail.com:587 o smtp.qq.com:465.
Inserisci il tuo indirizzo in sender_email e la password per app del passaggio 2 in sender_password.

Documentazione ufficiale ↗

Obbligatorio: smtp_server, sender_email, sender_password, to
Opzionale: smtp_port (predefinita 587), smtp_ssl (auto / implicit / starttls / none), use_tls, cc, bcc, subject, body, format (text / html / markdown)

subject e body supportano {{variables}}, prese dall'output di un nodo precedente. La maggior parte dei provider richiede una password per app invece della password di accesso.

Errori comuni

Autenticazione fallita: sender_password è la tua password di accesso. Usa invece una password per app o un codice di autorizzazione.
Timeout di connessione o errore di handshake: la porta e la crittografia non corrispondono. La porta 465 usa TLS implicito, la porta 587 usa STARTTLS; con smtp_ssl impostato su auto viene scelto automaticamente quello giusto in base alla porta, quindi raramente serve modificarlo.
«not a public address»: il server SMTP punta a un indirizzo interno o locale (comune nei server di posta interni) ed è bloccato per sicurezza. Usa un server SMTP raggiungibile da internet pubblico.
to richiede almeno un destinatario; separane più con virgole.

SQLite

Passaggi di configurazione

Non serve account o password: il file del database si trova nella tua directory dati.
Inserisci solo un nome file in database_path, ad esempio orders.db; il file viene creato se non esiste.

Documentazione ufficiale ↗

Obbligatorio: database_path, sql
Opzionale: params, operation (select / insert / update / delete / execute), return_type (predefinito dict), timeout

database_path richiede solo un nome file (ad esempio orders.db): il file viene salvato automaticamente nella tua directory dati personale. Usa segnaposto ? nell'SQL, con i valori in params.

Errori comuni

«no such table»: un nome file scritto male non genera un errore di file non trovato. Viene invece creato un nuovo database vuoto, quindi la tabella non c'è. Controlla prima il nome del file.
database_path è solo un nome file. Il database resta nella tua directory dati e non può accedere a file altrove.
Usa ? come segnaposto, con i valori in params.

MySQL

Passaggi di configurazione

Prepara host, porta (predefinita 3306), utente, password e nome del database.
Crea un account database dedicato per questa connessione; se esegue solo query, concedi solo SELECT.
Assicurati che il database sia raggiungibile da internet pubblico: il firewall o il gruppo di sicurezza del cloud provider devono consentire la porta.

Documentazione ufficiale ↗

Obbligatorio: host, user, password, database, sql
Opzionale: port (predefinito 3306), ssl (disabled / required / verify), params, read_only (attivo per impostazione predefinita), max_rows (predefinito 1000), timeout

Usa segnaposto %s nell'SQL, con i valori in params (un % letterale va scritto %% quando si usano i params). Di default è di sola lettura: disattiva read_only per scrivere; per i nodi di sola lettura, usa un account con permessi solo SELECT. Viene eseguita una sola istruzione alla volta, e si possono raggiungere solo indirizzi pubblici.

Errori comuni

«not a public address»: host è un indirizzo interno (10.x, 172.16–31.x, 192.168.x, 127.0.0.1). Il connettore può raggiungere solo indirizzi pubblici, quindi il database ha bisogno di un endpoint pubblico.
Le scritture vengono rifiutate: read_only è attivo per default e l'SQL viene eseguito in una transazione di sola lettura. Disattiva read_only quando devi davvero scrivere, e verifica che l'account abbia i permessi di scrittura.
I risultati sono incompleti: per default vengono restituite al massimo 1000 righe (max_rows, fino a 10000); tutto ciò che eccede viene troncato e contrassegnato come truncated.
Viene eseguita una sola istruzione SQL alla volta. Usa %s come segnaposto con i valori in params; non costruire i valori direttamente nella stringa SQL.
Timeout di connessione: di solito il firewall o il gruppo di sicurezza non lascia passare la porta.

Webhook

Passaggi di configurazione

Prepara un URL pubblico che accetti richieste POST e inseriscilo in webhook_url.
Se il destinatario deve poter confermare che una richiesta proviene dal tuo flusso di lavoro, concorda una chiave e inseriscila in secret_key.
Lato ricevente: ogni richiesta include X-Webhook-Timestamp; se è impostato secret_key, include anche X-Webhook-Signature, l'HMAC-SHA256 esadecimale di (timestamp + "." + raw_body) calcolato con quella chiave.

Obbligatorio: webhook_url
Opzionale: secret_key, verify_signature, event_types, retry_count, timeout

Quando secret_key è impostata, le richieste includono un header X-Webhook-Signature (HMAC-SHA256) che il destinatario può usare per verificarle.

Errori comuni

«Testa connessione» invia davvero un evento con event_type ping al destinatario.
Una risposta 4xx o 500, oppure un timeout, non viene ritentata (il destinatario potrebbe averla già elaborata). Vengono ritentati solo i codici 429, 502, 503, 504 e le connessioni mai stabilite.
«not a public address»: l'URL di ricezione è un indirizzo interno o locale.
Un event_types vuoto inoltra tutto; se ha delle voci, i dati il cui event_type non è nell'elenco vengono ignorati.

Limite di sicurezza: HTTP, DingTalk, WeCom, Feishu, Slack, Teams, Email, MySQL e Webhook possono raggiungere solo indirizzi pubblici (indirizzi di rete interna come 127.0.0.1, 10.x e 192.168.x vengono rifiutati); SQLite può accedere solo alla tua directory dati personale.

Chiavi API

Per consentire a script e altri sistemi di chiamare l’API, ad esempio per avviare un flusso di lavoro con uno script pianificato. Crea una chiave in «Account → Chiavi API» nell’app; la chiave completa viene mostrata una sola volta, quindi salvala subito. In seguito, nell’elenco saranno visibili solo i primi caratteri per identificarla. Limiti: 1 nel piano Free, 5 nel Pro, illimitate nei piani Business ed Enterprise (contando solo le chiavi non revocate).

curl -X POST https://app.opengency.ai/api/executions/workflows/<工作流 ID>/execute \
  -H "Authorization: Bearer ofk_…" \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"order_id": 7}}'

Ha gli stessi permessi dell’account che l’ha creata; le esecuzioni avviate con questa chiave sono etichettate «API» nel registro delle esecuzioni e mostrano i primi caratteri della chiave.
Per gestire le chiavi API, cambiare la password o eliminare l’account devi accedere con la password dell’account: una chiave API non può eseguire queste operazioni.
La revoca di una chiave ha effetto immediato (restituisce 401). Cambiare la password non invalida le chiavi esistenti: se sospetti che una sia stata esposta, revocala.
Conserva le chiavi solo sul server: non inserirle nel codice del sito e non condividerle nelle chat.

Domande frequenti

Perché il mio nodo HTTP restituisce "not a public address"?: La destinazione è un indirizzo di rete interna o locale ed è stata bloccata per sicurezza. Usa invece un indirizzo raggiungibile pubblicamente.
Posso essere avvisato quando l'esecuzione di un flusso di lavoro fallisce?: Sì, su tutti i piani. In Account → Notifiche di errore, scegli di ricevere l'avviso sull'email dell'account, oppure su una connessione DingTalk, WeCom, Feishu o email già salvata. Più errori entro circa 10 minuti vengono uniti in un unico messaggio, con il numero di errori per ogni flusso di lavoro, il nodo che ha causato l'errore e un link ai dettagli; le esecuzioni annullate manualmente non generano notifiche.
I flussi di lavoro possono avere cicli?: Non ancora: i flussi di lavoro non possono formare un ciclo, e il salvataggio lo segnalerà se ci provi.
I flussi di lavoro possono essere eseguiti secondo una pianificazione?: Sì. Nell’editor, cambia il tipo di trigger in «Pianificazione», scegli una frequenza (ogni N minuti, ogni ora, ogni giorno, ogni settimana) oppure scrivi un’espressione cron e seleziona il fuso orario; salva il flusso di lavoro, poi attiva l’interruttore nella pagina dei dettagli del flusso di lavoro. Il piano Free consente un flusso di lavoro pianificato attivo alla volta; il piano Pro ne consente 10.