GSP1301

Visão geral

Os complementos podem ampliar os recursos do Google Workspace, ajudando usuários a serem mais produtivos e melhorar o fluxo de trabalho. Neste laboratório, você vai criar um complemento do Google Workspace que usa o poder do Gemini e da Vertex AI para realizar análises de sentimento no Gmail. Você vai configurar os recursos de nuvem necessários (incluindo as APIs Vertex AI), configurar um projeto do Apps Script e implantar o complemento.

O complemento permite identificar e marcar automaticamente e-mails com tom negativo. Você pode usar esse recurso para priorizar respostas de atendimento ao cliente ou identificar e-mails potencialmente sensíveis com rapidez.

Ao final do laboratório, você terá uma ferramenta funcional que demonstra a aplicação prática da IA para melhorar a produtividade e a comunicação em um contexto empresarial.

O que você vai aprender

Veja abaixo as atividades que você vai fazer neste laboratório:

• Criar um complemento do Google Workspace que amplia a funcionalidade do Gmail.
• Integrar a Vertex AI ao Google Workspace para usar o Gemini e os recursos de processamento de linguagem natural da Vertex AI em um complemento do Gmail.
• Implementar a autenticação OAuth2 para autorizar o complemento a acessar os dados do usuário com segurança.
• Aplicar a análise de sentimento para avaliar programaticamente o conteúdo do e-mail e determinar o tom emocional.
• Usar o Apps Script para escrever códigos que interagem com o Gmail, gerenciam interfaces de usuário e se conectam a APIs externas.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Tarefa 1: acessar o ambiente do laboratório

Você fez login no console do Google Cloud. Agora faça login no Gmail.

1. Clique em Abrir o Gmail para abrir a página de login do Gmail.

Dica: coloque as guias em janelas separadas para facilitar a visualização.

2. Faça login no Gmail com o nome de usuário, e a senha.

Observação: essas credenciais também estão no painel Detalhes do laboratório e foram usadas para fazer login no console do Google Cloud.

3. Depois de acessar o Gmail, clique em Começar e feche todas as janelas informativas. Agora você vai ver sua caixa de entrada.

E já pode começar as atividades do laboratório.

Tarefa 2: configurar o ambiente do Google Cloud

Nesta tarefa, você vai ativar a API Vertex AI e configurar a tela de permissão OAuth para definir o que o Google Workspace vai mostrar aos usuários.

Ativar a API Vertex AI

1. No console do Google Cloud, no Menu de navegação, clique em APIs e serviços > Biblioteca.

2. Digite API Vertex AI na caixa Pesquisar APIs e serviços e clique em API Vertex AI nos resultados da pesquisa.

3. Clique em Ativar para ativar a API.

A página Detalhes da API/Serviço será aberta.

Configurar a tela de consentimento OAuth

1. No painel à esquerda, clique em Tela de permissão OAuth.

2. Clique em Primeiros passos.

3. Em Informações do app, defina o seguinte e clique em Avançar:

• Nome do app: análise de sentimento do Gmail com o Gemini e a Vertex AI
• E-mail para suporte do usuário:

4. Em Público-alvo, selecione Interno e clique em Avançar.
5. Em Informações de contato, defina Endereços de e-mail como e clique em Avançar.
6. Para Concluir, aceite a Política de dados do usuário dos serviços de API do Google e clique em Continuar.
7. Clique em Criar.

Clique em Verificar meu progresso para conferir o objetivo. Configure a tela de consentimento OAuth.

Tarefa 3: configurar o projeto do Apps Script

Nesta tarefa, você vai criar e configurar seu complemento como um projeto do Apps Script.

Confira o número do projeto do Google Cloud

Para obter o número do seu projeto do Google Cloud que será usado ao criar um projeto do Apps Script:

1. No menu de navegação () clique em Visão geral do Cloud > Painel.

2. Na seção Informações do projeto, anote o número do projeto que será usado mais tarde neste laboratório.

Criar um projeto do Apps Script

1. No painel Recursos do estudante, clique neste link, script.google.com/, para abrir a página do Apps Script.

2. Clique em Novo projeto para criar um projeto do Apps Script.

3. Escolha um nome para o projeto:

   • Clique em "Projeto sem título" no canto superior esquerdo.
   • Renomeie o projeto como Análise de sentimento do Gmail com o Gemini e a Vertex AI e clique em Renomear.

4. Deixe o arquivo de manifesto visível:

   • No painel à esquerda, clique em Configurações do projeto ().
   • Selecione Mostrar arquivo de manifesto "appsscript.json" no editor.

5. Altere seu projeto do Google Cloud Platform:

   • Role para baixo até a seção Projeto do Google Cloud Platform (GCP) e clique em Alterar projeto.
   • Defina o Número do projeto do GCP com o número do projeto que você anotou anteriormente.
   • Clique em Configurar projeto.

Clique em Verificar meu progresso para conferir o objetivo. Crie um projeto do Apps Script.

Tarefa 4: preencher arquivos de código

• No painel à esquerda, clique em Editor () para abrir a janela do editor.

Siga as instruções abaixo para atualizar seu projeto com o código de amostra.

appsscript.json

1. Abra appsscript.json e substitua o conteúdo do arquivo pelo seguinte:

{ "timeZone": "America/Toronto", "oauthScopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/gmail.addons.execute", "https://www.googleapis.com/auth/gmail.labels", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/userinfo.email" ], "addOns": { "common": { "name": "Sentiment Analysis", "logoUrl": "https://fonts.gstatic.com/s/i/googlematerialicons/sentiment_extremely_dissatisfied/v6/black-24dp/1x/gm_sentiment_extremely_dissatisfied_black_24dp.png" }, "gmail": { "homepageTrigger": { "runFunction": "onHomepageTrigger", "enabled": true } } }, "exceptionLogging": "STACKDRIVER", "runtimeVersion": "V8" }

2. Clique em Salvar para salvar o projeto.

Code.gs

1. Abra o arquivo Code.gs e substitua o conteúdo pelo seguinte:

/* Copyright 2024-2025 Google LLC Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */ // Replace with your project ID const PROJECT_ID = '{{{project_0.project_id | Project ID}}}'; // Location for your Vertex AI model const VERTEX_AI_LOCATION = 'us-east4'; // Model ID to use for sentiment analysis const MODEL_ID = 'gemini-2.0-flash'; /** * Triggered when the add-on is opened from the Gmail homepage. * * @param {Object} e - The event object. * @returns {Card} - The homepage card. */ function onHomepageTrigger(e) { return buildHomepageCard(); } /** * Builds the main card displayed on the Gmail homepage. * * @returns {Card} - The homepage card. */ function buildHomepageCard() { // Create a new card builder const cardBuilder = CardService.newCardBuilder(); // Create a card header const cardHeader = CardService.newCardHeader(); cardHeader.setImageUrl('https://fonts.gstatic.com/s/i/googlematerialicons/mail/v6/black-24dp/1x/gm_mail_black_24dp.png'); cardHeader.setImageStyle(CardService.ImageStyle.CIRCLE); cardHeader.setTitle("Analyze your Gmail"); // Add the header to the card cardBuilder.setHeader(cardHeader); // Create a card section const cardSection = CardService.newCardSection(); // Create buttons for generating sample emails and analyzing sentiment const buttonSet = CardService.newButtonSet(); // Create "Generate sample emails" button const generateButton = createFilledButton('Generate sample emails', 'generateSampleEmails', '#34A853'); buttonSet.addButton(generateButton); // Create "Analyze emails" button const analyzeButton = createFilledButton('Analyze emails', 'analyzeSentiment', '#FF0000'); buttonSet.addButton(analyzeButton); // Add the button set to the section cardSection.addWidget(buttonSet); // Add the section to the card cardBuilder.addSection(cardSection); // Build and return the card return cardBuilder.build(); } /** * Creates a filled text button with the specified text, function, and color. * * @param {string} text - The text to display on the button. * @param {string} functionName - The name of the function to call when the button is clicked. * @param {string} color - The background color of the button. * @returns {TextButton} - The created text button. */ function createFilledButton(text, functionName, color) { // Create a new text button const textButton = CardService.newTextButton(); // Set the button text textButton.setText(text); // Set the action to perform when the button is clicked const action = CardService.newAction(); action.setFunctionName(functionName); textButton.setOnClickAction(action); // Set the button style to filled textButton.setTextButtonStyle(CardService.TextButtonStyle.FILLED); // Set the background color textButton.setBackgroundColor(color); return textButton; } /** * Creates a notification response with the specified text. * * @param {string} notificationText - The text to display in the notification. * @returns {ActionResponse} - The created action response. */ function buildNotificationResponse(notificationText) { // Create a new notification const notification = CardService.newNotification(); notification.setText(notificationText); // Create a new action response builder const actionResponseBuilder = CardService.newActionResponseBuilder(); // Set the notification for the action response actionResponseBuilder.setNotification(notification); // Build and return the action response return actionResponseBuilder.build(); } /** * Generates sample emails for testing the sentiment analysis. * * @returns {ActionResponse} - A notification confirming email generation. */ function generateSampleEmails() { // Get the current user's email address const userEmail = Session.getActiveUser().getEmail(); // Define sample emails const sampleEmails = [ { subject: 'Thank you for amazing service!', body: 'Hi, I really enjoyed working with you. Thank you again!', name: 'Customer A' }, { subject: 'Request for information', body: 'Hello, I need more information on your recent product launch. Thank you.', name: 'Customer B' }, { subject: 'Complaint!', body: '', htmlBody: `

Olá, sua entrega está atrasada de novo.

Entre em contato comigo o mais rápido possível antes que eu cancele nossa assinatura.

`, name: 'Customer C' } ]; // Send each sample email for (const email of sampleEmails) { GmailApp.sendEmail(userEmail, email.subject, email.body, { name: email.name, htmlBody: email.htmlBody }); } // Return a notification return buildNotificationResponse("Successfully generated sample emails"); } /** * Analyzes the sentiment of the first 10 threads in the inbox * and labels them accordingly. * * @returns {ActionResponse} - A notification confirming completion. */ function analyzeSentiment() { // Analyze and label emails analyzeAndLabelEmailSentiment(); // Return a notification return buildNotificationResponse("Successfully completed sentiment analysis"); } /** * Analyzes the sentiment of emails and applies appropriate labels. */ function analyzeAndLabelEmailSentiment() { // Define label names const labelNames = ["HAPPY TONE 😊", "NEUTRAL TONE 😐", "UPSET TONE 😡"]; // Get or create labels for each sentiment const positiveLabel = GmailApp.getUserLabelByName(labelNames[0]) || GmailApp.createLabel(labelNames[0]); const neutralLabel = GmailApp.getUserLabelByName(labelNames[1]) || GmailApp.createLabel(labelNames[1]); const negativeLabel = GmailApp.getUserLabelByName(labelNames[2]) || GmailApp.createLabel(labelNames[2]); // Get the first 10 threads in the inbox const threads = GmailApp.getInboxThreads(0, 10); // Iterate through each thread for (const thread of threads) { // Iterate through each message in the thread const messages = thread.getMessages(); for (const message of messages) { // Get the plain text body of the message const emailBody = message.getPlainBody(); // Analyze the sentiment of the email body const sentiment = processSentiment(emailBody); // Apply the appropriate label based on the sentiment if (sentiment === 'positive') { thread.addLabel(positiveLabel); } else if (sentiment === 'neutral') { thread.addLabel(neutralLabel); } else if (sentiment === 'negative') { thread.addLabel(negativeLabel); } } } } /** * Sends the email text to Vertex AI for sentiment analysis. * * @param {string} emailText - The text of the email to analyze. * @returns {string} - The sentiment of the email ('positive', 'negative', or 'neutral'). */ function processSentiment(emailText) { // Construct the API endpoint URL const apiUrl = `https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/${MODEL_ID}:generateContent`; // Prepare the request payload const payload = { contents: [ { role: "user", parts: [ { text: `Analyze the sentiment of the following message: ${emailText}` } ] } ], generationConfig: { temperature: 0.9, maxOutputTokens: 1024, responseMimeType: "application/json", // Expected response format for simpler parsing. responseSchema: { type: "object", properties: { response: { type: "string", enum: ["positive", "negative", "neutral"] } } } } }; // Prepare the request options const options = { method: 'POST', headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` }, contentType: 'application/json', muteHttpExceptions: true, // Set to true to inspect the error response payload: JSON.stringify(payload) }; // Make the API request const response = UrlFetchApp.fetch(apiUrl, options); // Parse the response. Há dois níveis de respostas JSON para analisar. const parsedResponse = JSON.parse(response.getContentText()); const sentimentResponse = JSON.parse(parsedResponse.candidates[0].content.parts[0].text).response; // Return the sentiment return sentimentResponse; }

Clique em Salvar para salvar o projeto.

Tarefa 5: implantar o complemento

Nesta tarefa, você vai implantar o complemento e verificar a instalação.

Implante o complemento

1. Na barra de título, clique em Implantar > Testar implantações.

2. Confirme se o Gmail está listado em Aplicativo(s) e clique em Instalar.

3. Clique em Concluído.

Verifique a instalação

• Atualize a guia Gmail. Um ícone vai aparecer no painel à direita.

Resolver problemas

Se o complemento não aparecer na lista, atualize a janela do navegador.

Se isso não resolver o problema, volte ao projeto do Apps Script, desinstale o complemento na janela Testar implantações e reinstale.

Tarefa 6: executar o complemento

Tudo pronto para executar o complemento. Nesta tarefa, você vai abrir e autorizar o complemento e gerar e-mails para verificar se a análise funciona.

1. Ainda no Gmail, no painel à direita, clique em Análise de sentimento ().

2. Quando o painel lateral abrir, clique em Autorizar acesso para conceder permissão ao complemento que será executado.

Uma tela de consentimento é aberta. Selecione seu e-mail () e clique nas telas para permitir o acesso.

Depois de dar seu consentimento, o painel Análise de sentimento será aberto à direita.

3. No painel Análise de sentimento, clique em Gerar amostras de e-mails.

O complemento agora gera e-mails de amostra para testar a análise. Uma mensagem será exibida quando a geração for concluída, o que leva apenas alguns segundos.

4. Aguarde os e-mails de amostra aparecerem na sua caixa de entrada. Talvez seja necessário atualizar sua caixa de entrada para ver os novos e-mails.

5. Depois que os e-mails de amostra estiverem na sua caixa de entrada, no painel Análise de sentimento, clique em Analisar e-mails.

Uma mensagem informando que a análise foi concluída aparece na parte de baixo da tela do complemento.

Observação :a análise de e-mails pode levar algum tempo. Atualize a página para conferir o status dos rótulos aplicados.

O complemento analisa seus e-mails e aplica o rótulo apropriado ("TOM FELIZ 😊", "TOM CHATEADO 😡" ou "TOM NEUTRO 😐") às mensagens na sua caixa de entrada.

Talvez seja necessário atualizar o Gmail para ver os rótulos aplicados.

7. Continue a tecnologia experimental Você pode testar o complemento enviando e-mails com diferentes sentimentos (positivo, negativo, neutro) do seu Gmail do laboratório para outra conta do Gmail do laboratório. E-mails externos não são permitidos. Observe como o complemento analisa e rotula cada e-mail.

OBSERVAÇÃO: o código só extrai os últimos 10 e-mails da sua caixa de entrada, mas você pode mudar esse valor.

8. Feche o complemento:quando terminar de usar o complemento, clique no X no canto superior direito do painel lateral para fechar.

Clique em Verificar meu progresso para conferir o objetivo. Aplicar análise de sentimento.

Parabéns!

Você concluiu o laboratório Análise de sentimento do Gmail com o Gemini e a Vertex AI.

Neste laboratório, você aprendeu a executar as seguintes tarefas:

• Criar um complemento do Google Workspace: desenvolva uma ferramenta prática que amplie a funcionalidade do Gmail.
• Integrar a Vertex AI ao Google Workspace: use os recursos de processamento de linguagem natural do Gemini e da Vertex AI em um complemento do Gmail.
• Implementar a autenticação OAuth2: autorizar o complemento a acessar os dados do usuário com segurança.
• Aplicar análise de sentimento: analisar o conteúdo do e-mail de forma programática para determinar o tom emocional.
• Usar o Apps Script: escrever código para interagir com o Gmail, gerenciar interfaces de usuário e se conectar a APIs externas.

Agora você tem um complemento funcional do Gmail que pode ajudar a priorizar e-mails e melhorar seu fluxo de trabalho. Você pode experimentar mais com o complemento, personalizando a análise de sentimento ou adicionando novos recursos.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 25 de março de 2025

Laboratório testado em 25 de fevereiro de 2025

Copyright 2025 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.