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 negativos em verde e com sentimentos negativos 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 Start Lab

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é iniciado quando você clica em Começar o 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, 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 ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e a conta de estudante, o que poderia causar cobranças extras na sua conta pessoal.

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

Observação: não use seu projeto ou conta do Google Cloud neste laboratório para evitar cobranças extras na sua conta.

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, você verá um pop-up para selecionar a forma de pagamento. No painel Detalhes do laboratório à esquerda, você verá o seguinte:

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

2. Clique em Abrir Console do Google. O laboratório ativa recursos e depois abre outra guia com a página Fazer login.

   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. Caso seja preciso, copie o Nome de usuário no painel Detalhes do laboratório e cole esse nome na caixa de diálogo Fazer login. Clique em Avançar.

4. Copie a Senha no painel Detalhes do laboratório e a cole na caixa de diálogo Olá. Clique em Avançar.

   Importante: você precisa usar as credenciais do painel à esquerda. Não use suas credenciais do Google Cloud Ensina. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

5. 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 GCP vai ser aberto nesta guia.

Observação: para ver uma lista dos produtos e serviços do Google Cloud, clique no Menu de navegação no canto superior esquerdo.

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 Natural Language e clique na API 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 da 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 do Documentos Google

Antes de chamar a API Natural Language API, escreva um programa usando a plataforma Apps Script para gerar o menu, vincular o menu à função de marcar o texto e extrair o texto 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 (). 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 do 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 Continuar e confirme sua conta.
8. Autorize o script Natural Language Tools a ler e gerenciar documentos onde esse aplicativo estiver 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. Remova as linhas atuais da função retrieveSentiment e adicione uma variável com sua chave de API, que você salvou na seção "Gerar uma chave de API".

var apiKey = "your key here";

3. Crie a variável para armazenar o URL da API Natural Language com sua chave de API anexada a ela:

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

4. Escreva uma estrutura a partir da 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; // Ensure all pieces were in the returned value 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"; var apiEndpoint = 'https://language.googleapis.com/v1/documents:analyzeSentiment?key=' + apiKey; // Create a structure with the text, its language, its type, // and its encoding var docDetails = { language: 'en-us', type: 'PLAIN_TEXT', content: line }; var nlData = { document: docDetails, encodingType: 'UTF8' }; // Package all of the options and the data together for the call var nlOptions = { method : 'post', contentType: 'application/json', payload : JSON.stringify(nlData) }; // And make the call var response = UrlFetchApp.fetch(apiEndpoint, nlOptions); var data = JSON.parse(response); var sentiment = 0.0; // Ensure all pieces were in the returned value 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 reautorizar 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!

Você criou um arquivo do app Documentos Google e chamou a API Natural Language para analisar o sentimento expresso em partes do texto.

Terminar a Quest

Este laboratório autoguiado faz parte da Quest Workspace Integrations. Uma Quest é uma série de laboratórios relacionados que formam um programa de aprendizado. Ao concluir uma Quest, você ganha um selo como reconhecimento da sua conquista. É possível publicar os selos e incluir um link para eles no seu currículo on-line ou nas redes sociais. Inscreva-se nesta Quest e receba o crédito de conclusão imediatamente. Consulte o catálogo do Google Cloud Ensina para conferir todas as Quests disponíveis.

Comece o próximo laboratório

Continue sua Quest com Build a Complete Database Web App with App Maker ou confira a The Apps Script CLI - clasp.

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 Ensina 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 14 de junho de 2023

Laboratório testado em 14 de junho de 2023

Copyright 2024 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.