GSP126

Informações gerais

A API Natural Language é um modelo de aprendizado de máquina pré-treinado que analisa sintaxe, extrai entidades e avalia a ideia expressa em um texto. Chame essa API pelo app Documentos Google para executar todas essas funções.

Neste laboratório, você vai chamar a API Natural Language pelo app Documentos Google. Você vai usar a API Natural Language para identificar o sentimento de um texto selecionado no app Documentos Google e destacar esse texto de acordo com o sentimento que ele expressa.

Depois de concluir este laboratório, você vai poder selecionar um texto em um documento e identificar o sentimento expressado, usando uma opção de menu, conforme mostrado abaixo.

Textos com sentimentos negativos são destacados em vermelho, com sentimentos positivos em verde e com sentimentos neutros em amarelo.

Conteúdo

Neste laboratório, você vai aprender a fazer o seguinte:

• Chamar a API Natural Language com o app Documentos Google
• Adicionar menus ao app Documentos Google
• Identificar e trabalhar com textos selecionados no app Documentos Google

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: ative a API Natural Language

Antes de começar, verifique se a API Natural Language está ativada.

1. No Console do Google Cloud, selecione Menu de navegação > APIs e serviços > Biblioteca.

2. Procure a API Cloud Natural Language e clique para ativá-la ou confirmar que ela está ativada.

Tarefa 2: consiga uma chave de API

Gere uma chave de usuário de API para transmitir o URL da solicitação.

1. Para criar uma chave de API, selecione Menu de navegação > APIs e serviços > Credenciais.

2. Clique em Criar credenciais na parte de cima e selecione Chave de API:

3. Copie a chave de API em um arquivo de texto ou do Documentos Google para usar depois. Clique em Fechar.

Agora que você já tem a chave de API, saiba como ela pode ser usada com o app Documentos Google.

Clique em Verificar meu progresso para conferir o objetivo. Gere uma chave de API

Tarefa 3: configure o arquivo dos Documentos Google

Antes de chamar a API Natural Language, escreva um programa Apps Script para criar o menu, vinculá-lo a uma função que permita marcar o texto e extraí-lo da seleção do usuário.

1. Crie um arquivo do app Documentos Google.
2. No novo documento, selecione o item de menu Extensões > Apps Script.
3. Apague o código no editor de script (se houver algum) e cole o código abaixo. Esse código vai criar um item de menu, extrair o texto da seleção atual e destacar o texto conforme o sentimento que ele expressa. Ele ainda não chama a API Natural Language.

/** * @OnlyCurrentDoc * * The above comment directs Apps Script to limit the scope of file * access for this add-on. It specifies that this add-on will only * attempt to read or modify the files in which the add-on is used, * and not all of the user's files. The authorization request message * presented to users will reflect this limited scope. */ /** * Creates a menu entry in the Google Docs UI when the document is * opened. * */ function onOpen() { var ui = DocumentApp.getUi(); ui.createMenu('Natural Language Tools') .addItem('Mark Sentiment', 'markSentiment') .addToUi(); } /** * Gets the user-selected text and highlights it based on sentiment * with green for positive sentiment, red for negative, and yellow * for neutral. * */ function markSentiment() { var POSITIVE_COLOR = '#00ff00'; // Colors for sentiments var NEGATIVE_COLOR = '#ff0000'; var NEUTRAL_COLOR = '#ffff00'; var NEGATIVE_CUTOFF = -0.2; // Thresholds for sentiments var POSITIVE_CUTOFF = 0.2; var selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { var string = getSelectedText(); var sentiment = retrieveSentiment(string); // Select the appropriate color var color = NEUTRAL_COLOR; if (sentiment <= NEGATIVE_CUTOFF) { color = NEGATIVE_COLOR; } if (sentiment >= POSITIVE_CUTOFF) { color = POSITIVE_COLOR; } // Highlight the text var elements = selection.getSelectedElements(); for (var i = 0; i < elements.length; i++) { if (elements[i].isPartial()) { var element = elements[i].getElement().editAsText(); var startIndex = elements[i].getStartOffset(); var endIndex = elements[i].getEndOffsetInclusive(); element.setBackgroundColor(startIndex, endIndex, color); } else { var element = elements[i].getElement().editAsText(); foundText = elements[i].getElement().editAsText(); foundText.setBackgroundColor(color); } } } } /** * Returns a string with the contents of the selected text. * If no text is selected, returns an empty string. */ function getSelectedText() { var selection = DocumentApp.getActiveDocument().getSelection(); var string = ""; if (selection) { var elements = selection.getSelectedElements(); for (var i = 0; i < elements.length; i++) { if (elements[i].isPartial()) { var element = elements[i].getElement().asText(); var startIndex = elements[i].getStartOffset(); var endIndex = elements[i].getEndOffsetInclusive() + 1; var text = element.getText().substring(startIndex, endIndex); string = string + text; } else { var element = elements[i].getElement(); // Only translate elements that can be edited as text; skip // images and other non-text elements. if (element.editAsText) { string = string + element.asText().getText(); } } } } return string; } /** Given a string, will call the Natural Language API and retrieve * the sentiment of the string. The sentiment will be a real * number in the range -1 to 1, where -1 is highly negative * sentiment and 1 is highly positive. */ function retrieveSentiment (line) { // TODO: Call the Natural Language API with the line given // and return the sentiment value. return 0.0; } Observação: para mais informações sobre a plataforma Apps Script consulte esta página.

4. Na barra de menus, clique em Salvar projeto no Drive (). O nome do script é mostrado aos usuários finais em vários lugares, incluindo a caixa de diálogo de autorização.
5. Volte ao documento. Adicione texto a ele. Você pode usar o exemplo do livro Alice no País das Maravilhas no Project Gutenberg (copie e cole a versão em Plain Text UTF-8 no documento) ou usar qualquer texto que quiser.
6. Recarregue o documento. O menu Natural Language Tools que você criou aparecerá na barra de ferramentas dos Documentos Google.
7. Selecione o texto e depois a opção Marcar sentimento no menu Natural Language Tools. Quando você selecionar essa opção pela primeira vez, será necessário autorizar a execução do script. Clique em OK e confirme sua conta.
8. Autorize o Natural Language Tools a ler e gerenciar documentos em que esse aplicativo foi instalado.
9. Depois que você autorizar o script, o texto selecionado será destacado em amarelo, porque o stub da análise de sentimento sempre retorna 0.0, que é neutro.

Clique em Verificar meu progresso para conferir o objetivo. Configure o arquivo do Documentos Google

Tarefa 4: chame a API Natural Language

Agora que seu programa pode extrair o texto da seleção e destacá-lo, é hora de chamar a API Natural Language. Tudo isso é feito no corpo da função retrieveSentiment.

Observação: para mais informações sobre a API Natural Language consulte esta página.

1. Volte para Extensões > Apps Script no app Documentos Google.
2. Na função retrieveSentiment, substitua "your key here" pela sua chave de API real do console do Google Cloud.

var apiKey = "your key here"; // Substitua pela sua chave de API

3. Crie uma variável para armazenar o URL da API Natural Language com sua chave de API anexada a ela (não modifique esta linha):

var apiEndpoint = "https://language.googleapis.com/v1/documents:analyzeSentiment?key=" + apiKey;

4. Crie uma estrutura pela linha transmitida para a função que contém o texto da linha, junto com o tipo e idioma. Atualmente, é possível usar apenas o idioma inglês.

var docDetails = { language: 'en-us', type: 'PLAIN_TEXT', content: line };

5. Compile todo o payload de dados dos detalhes do documento, adicionando o seguinte tipo de codificação:

var nlData = { document: docDetails, encodingType: 'UTF8' };

6. Crie uma estrutura com o payload e as informações de cabeçalho necessárias.

var nlOptions = { method : 'post', contentType: 'application/json', payload : JSON.stringify(nlData) };

7. Faça a chamada e salve a resposta:

var response = UrlFetchApp.fetch(apiEndpoint, nlOptions);

8. A resposta é retornada no formato JSON. Analise a resposta e extraia o campo de pontuação (se houver um). Retorne esse campo ou 0.0.

var data = JSON.parse(response); var sentiment = 0.0; // Garanta que todos os elementos estejam no valor retornado if (data && data.documentSentiment && data.documentSentiment.score){ sentiment = data.documentSentiment.score; } return sentiment;

Este é o código completo para extrair o sentimento do texto:

function retrieveSentiment (line) { var apiKey = "your key here"; // Substitua pela sua chave de API var apiEndpoint = "https://language.googleapis.com/v1/documents:analyzeSentiment?key=" + apiKey; // Crie uma estrutura com o texto, a linguagem, o tipo, // e o código var docDetails = { language: 'en-us', type: 'PLAIN_TEXT', content: line }; var nlData = { document: docDetails, encodingType: 'UTF8' }; // Junte todas as opções e dados para a chamada var nlOptions = { method : 'post', contentType: 'application/json', payload : JSON.stringify(nlData) }; // E faça a chamada var response = UrlFetchApp.fetch(apiEndpoint, nlOptions); var data = JSON.parse(response); var sentiment = 0.0; // É importante que todas as peças estejam no valor retornado if (data && data.documentSentiment && data.documentSentiment.score){ sentiment = data.documentSentiment.score; } return sentiment; }

9. Salve o script, recarregue o documento e tente executar o programa inteiro. Talvez você precise inserir suas credenciais para autorizá-lo novamente e ativar a nova funcionalidade. Selecione várias seções do documento para conferir como o sentimento pode mudar ao longo do texto.

10. (Opcional) Digite e analise suas próprias palavras. Por exemplo, digite e analise "I'm sad" (Estou triste) e depois digite e analise "I'm happy" (Estou feliz). Faça testes para verificar como a API Natural Language interpreta grupos diferentes. Por exemplo, se você analisar "I'm happy. I'm happy. I'm sad", o que acontece se você adicionar a frase "I'm sad" mais uma vez?

Parabéns!

Parabéns! Você criou um documento Google e chamou a API Natural Language para analisar o sentimento expresso em partes do texto.

Próximas etapas / Saiba mais

Continue aprendendo sobre o Google Cloud com estas sugestões:

• Faça outros laboratórios. Saiba mais sobre a API Natural Language com laboratórios como: Análise de entidade e sentimento com a API Natural Language. Ou confira outros assuntos como: Alugar uma VM para processar dados de terremotos.
• Comece uma Quest. Uma Quest é uma série de laboratórios relacionados que formam um programa de aprendizado. Ao concluir uma Quest, você ganha um selo digital como reconhecimento da sua conquista. Você pode publicar os selos e incluir um link para eles no seu currículo on-line ou nas redes sociais. Consulte o catálogo do Google Cloud Skills Boost para conferir todas as Quests disponíveis.

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 21 de março de 2025

Laboratório testado em 21 de março 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.