Questo tutorial mostra come creare un flusso di lavoro di traduzione che attende il tuo input (l'human-in-the-loop) e che collega un database Firestore, due funzioni Cloud Run, l'API Cloud Translation e una pagina web che utilizza l'SDK Firebase per aggiornarsi in tempo reale.
Con i workflow, puoi supportare un endpoint di callback (o webhook) che attende l'arrivo di richieste HTTP a quell'endpoint, riprendendo l'esecuzione del workflow in un secondo momento. In questo caso, il flusso di lavoro attende il tuo input per rifiutare o convalidare la traduzione di un testo, ma potrebbe anche attendere un processo esterno. Per saperne di più, consulta Attesa tramite callback.
Architettura
Questo tutorial crea un'app web che ti consente di:
- Nella pagina web di traduzione, inserisci il testo che vuoi tradurre dall'inglese al francese. Fai clic su Traduci.
- Dalla pagina web viene chiamata una funzione Cloud Run che avvia l'esecuzione del flusso di lavoro. Il testo da tradurre viene passato come parametro sia alla funzione sia al flusso di lavoro.
- Il testo viene salvato in un database Cloud Firestore. Viene chiamata l'API Cloud Translation. La traduzione restituita viene memorizzata nel database. L'app web viene implementata utilizzando Firebase Hosting e si aggiorna in tempo reale per mostrare il testo tradotto.
- Il passaggio
create_callbackdel flusso di lavoro crea un URL endpoint di callback che viene salvato anche nel database Firestore. La pagina web ora mostra sia un pulsante Convalida che un pulsante Rifiuta. - Il flusso di lavoro è ora in pausa e attende una richiesta HTTP POST esplicita all'URL dell'endpoint di callback.
- Puoi decidere se convalidare o rifiutare la traduzione. Se fai clic su un pulsante, viene chiamata una seconda funzione Cloud Run che a sua volta chiama l'endpoint di callback creato dal flusso di lavoro, trasmettendo lo stato di approvazione.
Il flusso di lavoro riprende l'esecuzione e salva uno stato di approvazione
trueofalsenel database Firestore.
Questo diagramma fornisce una panoramica della procedura:
Esegui il deployment della prima funzione Cloud Run
Questa funzione Cloud Run avvia l'esecuzione del flusso di lavoro. Il testo da tradurre viene passato come parametro sia alla funzione sia al workflow.
Crea una directory denominata
callback-translationcon sottodirectory denominateinvokeTranslationWorkflow,translationCallbackCallepublic:mkdir -p ~/callback-translation/{invokeTranslationWorkflow,translationCallbackCall,public}
Passa alla directory
invokeTranslationWorkflow:cd ~/callback-translation/invokeTranslationWorkflow
Crea un file di testo con il nome file
index.jsche contenga il seguente codice Node.js:Crea un file di testo con il nome file
package.jsonche contenga i seguenti metadatinpm:Esegui il deployment della funzione con un trigger HTTP e consenti l'accesso non autenticato:
gcloud functions deploy invokeTranslationWorkflow \ --region=${REGION} \ --runtime nodejs14 \ --entry-point=invokeTranslationWorkflow \ --set-env-vars PROJECT_ID=${GOOGLE_CLOUD_PROJECT},CLOUD_REGION=${REGION},WORKFLOW_NAME=translation_validation \ --trigger-http \ --allow-unauthenticated
Il deployment della funzione potrebbe richiedere alcuni minuti. In alternativa, puoi utilizzare l'interfaccia Cloud Run Functions nella console Google Cloud per eseguire il deployment della funzione.
Una volta eseguito il deployment della funzione, puoi confermare la proprietà
httpsTrigger.url:gcloud functions describe invokeTranslationWorkflow
Prendi nota dell'URL restituito per poterlo utilizzare in un passaggio successivo.
Esegui il deployment della seconda funzione Cloud Run
Questa funzione Cloud Run invia una richiesta HTTP POST all'endpoint di callback creato dal flusso di lavoro, passando uno stato di approvazione che indica se la traduzione è convalidata o rifiutata.
Passa alla directory
translationCallbackCall:cd ../translationCallbackCall
Crea un file di testo con il nome file
index.jsche contenga il seguente codice Node.js:Crea un file di testo con il nome file
package.jsonche contenga i seguenti metadatinpm:Esegui il deployment della funzione con un trigger HTTP e consenti l'accesso non autenticato:
gcloud functions deploy translationCallbackCall \ --region=${REGION} \ --runtime nodejs14 \ --entry-point=translationCallbackCall \ --trigger-http \ --allow-unauthenticated
Il deployment della funzione potrebbe richiedere alcuni minuti. In alternativa, puoi utilizzare l'interfaccia Cloud Run Functions nella console Google Cloud per eseguire il deployment della funzione.
Una volta eseguito il deployment della funzione, puoi confermare la proprietà
httpsTrigger.url:gcloud functions describe translationCallbackCall
Prendi nota dell'URL restituito per poterlo utilizzare in un passaggio successivo.
Esegui il deployment del workflow
Un flusso di lavoro è costituito da una serie di passaggi descritti utilizzando la sintassi di Workflows, che può essere scritta in formato YAML o JSON. Questa è la definizione del flusso di lavoro. Dopo aver creato un flusso di lavoro, lo esegui per renderlo disponibile per l'esecuzione.
Passa alla directory
callback-translation:cd ..
Crea un file di testo con il nome file
translation-validation.yamle con il seguente contenuto:Dopo aver creato il flusso di lavoro, puoi eseguirne il deployment, ma non eseguirlo:
gcloud workflows deploy translation_validation --source=translation-validation.yaml
Crea la tua app web
Crea un'app web che chiama una Cloud Function che avvia l'esecuzione del flusso di lavoro. La pagina web si aggiorna in tempo reale per mostrare il risultato della richiesta di traduzione.
Passa alla directory
public:cd public
Crea un file di testo con il nome file
index.htmlche contenga il seguente markup HTML. In un passaggio successivo, modificherai il fileindex.htmle aggiungerai gli script dell'SDK Firebase.Crea un file di testo con il nome file
script.jscontenente il seguente codice JavaScript:Modifica il file
script.js, sostituendo i segnapostoUPDATE_MEcon gli URL delle funzioni Cloud Run che hai annotato in precedenza.Nel metodo
translateBtn.addEventListener, sostituisciconst fnUrl = UPDATE_ME;con:
const fnUrl = "https://REGION-PROJECT_ID.cloudfunctions.net/invokeTranslationWorkflow";
Nella funzione
callCallbackUrl, sostituisciconst fnUrl = UPDATE_ME;con:
const fnUrl = "https://REGION-PROJECT_ID.cloudfunctions.net/translationCallbackCall";
Crea un file di testo con il nome file
style.csscontenente i seguenti stili in cascata:
Aggiungi Firebase all'applicazione web
In questo tutorial, la pagina HTML, lo script JavaScript e il foglio di stile CSS vengono implementati come asset statici utilizzando Firebase Hosting, ma possono essere ospitati ovunque e pubblicati localmente sul tuo computer a scopo di test.
Crea un progetto Firebase
Prima di poter aggiungere Firebase alla tua app, devi creare un progetto Firebase a cui connetterti.
-
Nella console Firebase, fai clic su Crea un progetto, quindi seleziona il progetto Google Cloud esistente dal menu a discesa per aggiungere risorse Firebase.
-
Fai clic su Continua finché non vedi l'opzione per aggiungere Firebase.
-
Salta la configurazione di Google Analytics per il tuo progetto.
-
Fai clic su Aggiungi Firebase.
Firebase esegue automaticamente il provisioning delle risorse per il tuo progetto Firebase. Al termine della procedura, verrà visualizzata la pagina Panoramica del progetto nella Console Firebase.
Registrare l'app con Firebase
Una volta creato un progetto Firebase, puoi aggiungervi la tua app web.
Al centro della pagina di riepilogo del progetto, fai clic sull'icona Web (</>) per avviare il flusso di lavoro della configurazione.
Inserisci un nickname per l'app.
Questi dati sono visibili solo a te nella console Firebase.
Salta la configurazione di Firebase Hosting per ora.
Fai clic su Registra app e continua nella console.
Attiva Cloud Firestore
L'app web utilizza Cloud Firestore per ricevere e salvare i dati. Devi abilitare Cloud Firestore.
Nella sezione Build della console Firebase, fai clic su Firestore Database.
Potrebbe essere necessario espandere il riquadro di navigazione a sinistra per visualizzare la sezione Crea.
Nel riquadro Cloud Firestore, fai clic su Crea database.
Seleziona Avvia in modalità test utilizzando una regola di sicurezza come la seguente:
rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /{document=**} { allow read, write; } } }
Fai clic su Avanti dopo aver letto l'esclusione di responsabilità relativa alle regole di sicurezza.
Imposta la località in cui vengono archiviati i tuoi dati di Cloud Firestore. Puoi accettare il valore predefinito o scegliere una regione vicina a te.
Fai clic su Attiva per eseguire il provisioning di Firestore.
Aggiungi l'SDK Firebase e inizializza Firebase
Firebase fornisce librerie JavaScript per la maggior parte dei prodotti Firebase. Prima di utilizzare Firebase Hosting, devi aggiungere gli SDK Firebase alla tua app web.
- Per inizializzare Firebase nella tua app, devi fornire la configurazione del progetto Firebase
della tua app.
- Nella console Firebase, vai alle Impostazioni progetto .
- Nel riquadro Le tue app, seleziona la tua app.
- Nel riquadro Configurazione e configurazione dell'SDK, per caricare le librerie dell'SDK Firebase dalla CDN, seleziona CDN.
- Copia lo snippet nel file
index.htmlin fondo al tag<body>, sostituendo i valori segnapostoXXXX.
Installa l'SDK Firebase JavaScript.
Se non hai già un file
package.json, creane uno eseguendo il seguente comando dalla directorycallback-translation:npm initInstalla il pacchetto npm
firebasee salvalo nel filepackage.jsoneseguendo:npm install firebase
Inizializza ed esegui il deployment del progetto
Per collegare i file di progetto locali al progetto Firebase, devi inizializzare il progetto. A questo punto, puoi eseguire il deployment della tua app web.
Dalla directory
callback-translation, esegui questo comando:firebase initSeleziona l'opzione
Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys.Scegli di utilizzare un progetto esistente e inserisci il relativo ID.
Accetta
publiccome directory principale pubblica predefinita.Scegli di configurare un'app a una sola pagina.
Salta la configurazione di build e deployment automatici con GitHub.
Al prompt
File public/index.html already exists. Overwrite?, digita No.Passa alla directory
public:cd public
Dalla directory
public, esegui questo comando per eseguire il deployment del progetto sul tuo sito:firebase deploy --only hosting
Testa l'app web in locale
Firebase Hosting ti consente di visualizzare e testare le modifiche localmente
e interagire con le risorse del progetto di backend emulate. Quando utilizzi firebase serve,
la tua app interagisce con un backend emulato per i contenuti e la configurazione dell'hosting,
ma con il backend reale per tutte le altre risorse del progetto. Per questo tutorial, puoi utilizzare firebase serve, ma non è consigliato per test più estesi.
Dalla directory
public, esegui questo comando:firebase serveApri l'app web all'URL locale restituito (di solito
http://localhost:5000).Inserisci un testo in inglese e fai clic su Traduci.
Dovrebbe essere visualizzata una traduzione del testo in francese.
Ora puoi fare clic su Convalida o Rifiuta.
Nel database Firestore, puoi verificare i contenuti. Dovrebbe essere simile a questo:
approved: true callback: "https://workflowexecutions.googleapis.com/v1/projects/26811016474/locations/us-central1/workflows/translation_validation/executions/68bfce75-5f62-445f-9cd5-eda23e6fa693/callbacks/72851c97-6bb2-45e3-9816-1e3dcc610662_1a16697f-6d90-478d-9736-33190bbe222b" text: "The quick brown fox jumps over the lazy dog." translation: "Le renard brun rapide saute par-dessus le chien paresseux."Lo stato di
approvedètrueofalsea seconda che tu convalida o rifiuti la traduzione.
Complimenti! Hai creato un workflow di traduzione human-in-the-loop che utilizza i callback di Workflows.