Gestisci progetti con Google Chat, Vertex AI e Firestore

Questo tutorial mostra come creare un'app Google Chat che un team può utilizzare per gestire i progetti in tempo reale. L'app Chat utilizza Vertex AI per aiutare i team a scrivere storie utente (che rappresentano le funzionalità di un sistema software dal punto di vista di un utente da sviluppare dal team) e le memorizza in un database Firestore.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.

• Accedi ai servizi Google Cloud per:

  • Crea un progetto Google Cloud.
  • Collega un account di fatturazione Google Cloud al progetto Cloud. Per sapere se disponi dell'accesso, consulta Autorizzazioni necessarie per attivare la fatturazione.

  • Utilizza chiamate non autenticate alla funzione Google Cloud Functions, che puoi verificare determinando se la tua organizzazione Google Cloud utilizza la condivisione limitata per i domini.

  Se necessario, chiedi all'amministratore di Google Cloud l'accesso o l'autorizzazione.

• Se utilizzi Google Cloud CLI, un ambiente di sviluppo Node.js configurato per funzionare con gcloud CLI. Consulta Configurazione di un ambiente di sviluppo Node.js.

Obiettivi

• Crea un'app di chat che gestisce progetti di software agile.
• Aiuta gli utenti a scrivere storie utente con l'aiuto dell'IA generativa di Vertex AI.
  • Generare e rigenerare le descrizioni delle storie.
  • Espandi le descrizioni delle storie dalle note per completare i requisiti.
  • Correggi la grammatica per correggere gli errori di battitura.
• Mantieni aggiornato il lavoro scrivendo e leggendo in un database Firestore.
• Facilita la collaborazione in uno spazio di Chat consentendo agli utenti di creare, modificare, assegnare e avviare storie direttamente dalla conversazione.

Prodotti utilizzati

L'app per la gestione dei progetti utilizza i seguenti prodotti Google Workspace e Google Cloud:

• API Chat: un'API per lo sviluppo di app Google Chat che ricevono e rispondono agli eventi di interazione con Chat, come i messaggi. L'app Google Chat per la gestione dei progetti utilizza l'API Chat per ricevere e rispondere agli eventi di interazione inviati da Chat e per configurare gli attributi che determinano la sua visualizzazione in Chat, come il nome e l'immagine dell'avatar.
• API Vertex AI: una piattaforma di IA generativa. L'app Google Chat per la gestione dei progetti utilizza l'API Vertex AI per scrivere titoli e descrizioni delle storie utente.
• Firestore: un database di documenti serverless. L'app Google Chat per la gestione dei progetti utilizza Firebase per archiviare i dati sulle storie utente.

• Cloud Functions: un servizio di calcolo serverless leggero che ti consente di creare funzioni autonome a uso specifico in grado di rispondere agli eventi di interazione con Chat senza la necessità di gestire un ambiente server o di runtime. L'app Google Chat per la gestione dei progetti utilizza Cloud Functions per ospitare l'endpoint HTTP a cui Chat invia gli eventi di interazione e come piattaforma di calcolo per eseguire la logica che elabora e risponde a questi eventi.

  Cloud Functions utilizza i seguenti prodotti Google Cloud per creare, elaborare eventi di interazione e ospitare risorse di calcolo:

  • Cloud Build: una piattaforma di integrazione continua, distribuzione e deployment completamente gestita che esegue build automatizzate.
  • Pub/Sub: un servizio di messaggistica asincrono e scalabile che disaccoppia i servizi che producono messaggi da servizi che li elaborano.
  • API Cloud Run Admin: un ambiente completamente gestito per l'esecuzione di app containerizzate.

Architettura

L'architettura dell'app Google Chat per la gestione dei progetti riceve ed elabora gli eventi di interazione con Chat su un endpoint HTTP, utilizza Vertex AI per aiutare a scrivere le storie utente e archivia i dettagli delle storie utente in un database Firestore. Il seguente diagramma mostra l'architettura delle risorse Google Workspace e Google Cloud utilizzate.

L'app Google Chat per la gestione dei progetti funziona nel seguente modo:

1. Un utente invia un messaggio in Chat e richiama l'app Google Chat per la gestione dei progetti inviando un messaggio direttamente, menzionandola in uno spazio o inserendo un comando barra.

2. Chat invia una richiesta HTTP sincrona all'endpoint HTTP della funzione Cloud.

3. L'app Google Chat per la gestione dei progetti elabora la richiesta HTTP:

   1. Vertex AI aiuta a scrivere o aggiornare una storia utente.

   2. Un database Firestore archivia, recupera, aggiorna o elimina i dati delle storie utente.

4. Cloud Functions restituisce una risposta HTTP a Chat, che viene visualizzata all'utente come messaggio o dialogo.

Prepara l'ambiente

Questa sezione mostra come creare e configurare un progetto Google Cloud per l'app Chat.

Creare un progetto Google Cloud

Console Google Cloud

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Crea un progetto.

   Vai a Crea un progetto

2. Nel campo Nome progetto, inserisci un nome descrittivo per il progetto.

   (Facoltativo) Per modificare l'ID progetto, fai clic su Modifica. L'ID progetto non può essere modificato dopo la creazione del progetto, quindi scegli un ID che soddisfi le tue esigenze per l'intera durata del progetto.

3. Nel campo Località, fai clic su Sfoglia per visualizzare le potenziali località per il tuo progetto. Poi, fai clic su Seleziona.
4. Fai clic su Crea. La console Google Cloud passa alla pagina Dashboard e il progetto viene creato entro pochi minuti.

Interfaccia a riga di comando gcloud

In uno dei seguenti ambienti di sviluppo, accedi a Google Cloud CLI (gcloud):

• Cloud Shell: per utilizzare un terminale online con gcloud CLI già configurato, attiva Cloud Shell.
  Attiva Cloud Shell
• Shell locale: per utilizzare un ambiente di sviluppo locale, installa e inizializza l'interfaccia a riga di comando gcloud.
  Per creare un progetto Cloud, utilizza il comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID impostando l'ID del progetto che vuoi creare.

Abilita la fatturazione per il progetto Cloud

Console Google Cloud

1. Nella console Google Cloud, vai a Fatturazione. Fai clic su Menu menu > Fatturazione > I miei progetti.

   Vai a Fatturazione per i miei progetti

2. In Seleziona un'organizzazione, scegli l'organizzazione associata al tuo progetto Google Cloud.
3. Nella riga del progetto, apri il menu Azioni (more_vert), fai clic su Modifica fatturazione e scegli l'account di fatturazione Cloud.
4. Fai clic su Imposta account.

Interfaccia a riga di comando gcloud

1. Per elencare gli account di fatturazione disponibili, esegui:

   gcloud billing accounts list

2. Collega un account di fatturazione a un progetto Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Sostituisci quanto segue:

   • PROJECT_ID è l'ID progetto per il progetto Cloud per il quale vuoi abilitare la fatturazione.
   • BILLING_ACCOUNT_ID è l'ID account di fatturazione da collegare al progetto Google Cloud.

Abilita le API

Autenticazione e autorizzazione

Per seguire questo tutorial non è necessaria alcuna configurazione di autenticazione e autorizzazione.

Per chiamare le API Firestore e Vertex AI, questo tutorial utilizza le credenziali predefinite dell'applicazione con l'account di servizio predefinito associato alla funzione Cloud, che non è necessario configurare. In un ambiente di produzione, solitamente crei e colleghi un account di servizio alla funzione Cloud.

Creare e implementare l'app Google Chat

Ora che il progetto Google Cloud è stato creato e configurato, puoi procedere con la compilazione e il deployment dell'app Google Chat. In questa sezione, svolgi i seguenti passaggi:

1. Crea un database Firestore in cui mantenere e recuperare le storie degli utenti.
2. Se vuoi, controlla il codice campione.
3. Crea una funzione Cloud per ospitare ed eseguire il codice dell'app Chat in risposta agli eventi ricevuti da Chat come richieste HTTP.
4. Crea ed esegui il deployment di un'app Google Chat nella pagina di configurazione dell'API Google Chat.

Crea il database Firestore

In questa sezione, crei un database Firestore per memorizzare e recuperare le storie degli utenti, ma non definisci il modello di dati. Il modello di dati viene impostato implicitamente nel codice di esempio dai file model/user-story.js e model/user.js.

Il database dell'app di Chat per la gestione dei progetti utilizza un modello dei dati NoSQL basato su class documenti organizzati in collections_bookmark raccolte. Per scoprire di più, consulta Modello dei dati di Firestore.

Il seguente diagramma è una panoramica del modello di dati dell'app Google Chat per la gestione dei progetti:

La raccolta principale è spaces, dove ogni documento rappresenta uno spazio in cui l'app Chat ha creato Storie. Ogni storia utente è rappresentata da un documento nella sottoraccolta userStories e ogni utente è rappresentato da un documento nella sottoraccolta users.

Ecco come creare il database Firestore:

Esamina il codice campione

Se vuoi, prima di creare la funzione Cloud, prenditi un momento per esaminare e familiarizzare con il codice di esempio ospitato su GitHub.

Visualizza su GitHub

Ecco una panoramica di ogni file:

env.js

Variabili di configurazione dell'ambiente per eseguire il deployment dell'app Chat in un progetto e una regione Google Cloud specificati. Devi aggiornare le variabili di configurazione in questo file.

package.json e package-lock.json

Impostazioni e dipendenze del progetto Node.js.

index.js

Punto di ingresso per la funzione Cloud dell'app Chat. Legge l'evento Chat dalla richiesta HTTP, chiama il gestore dell'app e pubblica la risposta HTTP come oggetto JSON.

controllers/app.js

La logica di applicazione principale. Elabora gli eventi di interazione gestendo le menzioni dell'app Chat e i comandi slash. Per rispondere ai clic sulla scheda, chiama il numero app-action-handler.js.

controllers/app-action-handler.js

Logica di applicazione per gestire i clic sulle schede Eventi di interazione di Chat.

services/space-service.js, services/user-service.js e services/user-story-service.js

Questi file contengono le parti della logica di applicazione specifiche per l'utilizzo di spazi di Chat, utenti e storie utente. Le funzioni in questi file vengono chiamate da app.js o app-action-handler.js. Per eseguire operazioni di database, le funzioni in questi file richiamano funzioni in firestore-service.js.

services/firestore-service.js

Gestisce le operazioni del database. Le funzioni in questo file sono chiamate da services/space-service.js, services/user-service.js e services/user-story-service.js.

services/aip-service.js

Chiama l'API Vertex AI per la previsione del testo con l'IA generativa.

model/*.js

Questi file contengono la definizione di classi ed enum utilizzati dai servizi di applicazione per archiviare e trasmettere dati tra le funzioni. Impostano il modello dati per il database Firestore.

views/*.js

Ogni file in questa directory esegue l'inizializzazione di un oggetto scheda che l'app Chat invia di nuovo a Chat come messaggio della scheda o come risposta all'azione di dialogo.

views/widgets/*.js

Ogni file crea un'istanza per un tipo di oggetto widget che l'app utilizza per creare le schede nella directory views/.

test/**/*.test.js

Ogni file in questa directory e nelle relative sottodirectory contiene i test di unità per la funzione, il controller, il servizio, la visualizzazione o il widget corrispondente. Puoi eseguire tutti i test delle unità eseguendo npm run test nella directory root del progetto.

crea ed esegui il deployment della funzione Cloud Functions

In questa sezione crei ed esegui il deployment di una funzione Cloud che comprende la logica di applicazione dell'app di chat per la gestione dei progetti.

La funzione Cloud viene eseguita in risposta a una richiesta HTTP da Chat contenente un evento di interazione con Chat. Quando viene eseguito, il codice della funzione Cloud Functions elabora l'evento e restituisce una risposta a Chat, che Chat esegue il rendering come messaggio, finestra di dialogo o altro tipo di interazione dell'utente. Se applicabile, la funzione Cloud legge o scrive anche nel database Firestore.

Ecco come creare la funzione Cloud:

1. Al termine del deployment della funzione, copia la proprietà url dalla risposta. Questo è l'URL trigger da utilizzare nella sezione seguente per configurare l'app Google Chat.

Configurare l'app Google Chat nella console Google Cloud

Questa sezione mostra come configurare l'API Chat nella console Google Cloud con informazioni sulla tua app di chat, tra cui il nome dell'app, i comandi barra supportati e l'URL di attivazione della funzione Cloud dell'app di chat a cui invia gli eventi di interazione di Chat.

1. Nella console Google Cloud, fai clic su Menu menu > Altri prodotti > Google Workspace > Raccolta di prodotti > API Google Chat > Gestisci > Configurazione.

   Vai alla configurazione dell'API Chat

2. In Nome app, digita Project Manager.

3. In URL avatar, digita https://developers.google.com/chat/images/quickstart-app-avatar.png.

4. In Descrizione, digita Manages projects with user stories.

5. Fai clic sull'opzione Attiva funzionalità interattive per attivarla.

6. In Funzionalità, seleziona Ricevi messaggi 1:1, Partecipa a spazi e conversazioni di gruppo.

7. In Impostazioni di connessione, seleziona URL endpoint HTTP.

8. In URL endpoint HTTP, incolla l'URL del trigger che hai copiato dal deployment di Cloud Functions, nel formato https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial. Se hai eseguito il deployment della funzione Cloud con l'interfaccia a riga di comando gcloud, questa è la proprietà url.

9. Registra i comandi slash dell'app Chat. Per registrare un comando slash:

   1. In Comandi slash, fai clic su Aggiungi un comando slash.

   2. Per ogni comando barra descritto nella tabella seguente, inserisci Nome, ID comando, Descrizione e seleziona se il comando barra Apre una finestra di dialogo, poi fai clic su Fine:

      Nome	ID comando	Descrizione	Consente di aprire una finestra di dialogo
      /createUserStory	1	Crea una storia con il titolo specificato.	Deselezionato
      /myUserStories	2	Elenca tutte le storie assegnate all'utente.	Deselezionato
      /userStory	3	Mostra lo stato attuale della storia specificata.	Deselezionato
      /manageUserStories	4	Viene visualizzata una finestra di dialogo in cui è possibile modificare le Storie.	Selezionato
      /cleanupUserStories	5	Consente di eliminare tutte le storie nello spazio.	Deselezionato

10. In Visibilità, seleziona Rendi disponibile l'app di chat a utenti e gruppi specifici nel tuo dominio Workspace e inserisci il tuo indirizzo email.

11. Se vuoi, in Log, seleziona Registra gli errori in Logging.

12. Fai clic su Salva. Viene visualizzato un messaggio che indica che la configurazione è stata salvata e che l'app Chat è pronta per il test.

Testare l'app Chat

Testa l'app Chat per la gestione dei progetti inviando un messaggio e usando i comandi slash per creare, modificare ed eliminare le storie utente.

1. Apri Google Chat con l'account Google Workspace che hai fornito quando ti sei aggiunto come trusted tester.

   Vai a Google Chat

2. Fai clic su add Nuova chat.
3. Nel campo Aggiungi una o più persone, digita il nome della tua app di Chat.

4. Seleziona la tua app Chat dai risultati. Viene visualizzato un messaggio diretto.

5. Nel nuovo messaggio diretto con l'app, digita Hello e preme enter. L'app Chat per la gestione dei progetti risponde con un menu di guida che descrive le sue funzionalità.
6. Per creare una storia, digita /createUserStory Test story nella barra dei messaggi e inviala. L'app Chat per la gestione dei progetti risponde con un messaggio della scheda che descrive in dettaglio la storia utente creata per te utilizzando l'IA generativa di Vertex AI.

7. Nella console, controlla il database Firestore per esaminare i record creati per lo spazio a cui hai aggiunto l'app Chat, gli utenti che hanno interagito con l'app e la storia utente che hai creato.

   Vai a Firestore

8. Torna a Google Chat.

   Vai a Google Chat

9. Se vuoi, fai clic su Modifica per modificare la storia. Quando la storia ti soddisfa, fai clic su Salva.
10. Testa ogni comando barra supportato dall'app. Per visualizzarli, digita / o menziona l'app Chat.
11. Elimina la storia utente di test emettendo il comando /cleanupUserStories slash. In alternativa, rimuovi o disinstalla l'app. Quando viene rimossa, l'app elimina tutte le storie utente create nello spazio.

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte nella UI di Chat non viene visualizzato alcun messaggio di errore, ma l'app o la scheda Chat produce un risultato imprevisto. Ad esempio, il messaggio di una scheda potrebbe non essere visualizzato.

Anche se un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando il logging degli errori per le app di Chat è attivato. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare e fai clic su Elimina delete.
3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.

Argomenti correlati

• Rispondere a domande basate su conversazioni di Chat con un'app Gemini AI Chat
• Rispondere agli incidenti con Google Chat, Vertex AI e Apps Script