Como usar a API Natural Language com C#

1. Visão geral

Neste codelab, o foco será o uso da API Natural Language com C#. Você vai aprender a fazer análises de sentimento, entidades e sintaxe.

A API Natural Language do Google Cloud oferece tecnologias de processamento de linguagem natural para desenvolvedores, incluindo análise de sentimento, análise de entidades e análise sintática.

O que você vai aprender

• Como usar o Cloud Shell
• Como ativar a API Natural Language
• Como autenticar solicitações de API
• Como instalar a biblioteca de cliente do Google Cloud para C#
• Como fazer a análise de sentimento
• Como realizar a análise de entidades
• Como realizar a análise sintática

O que é necessário

• Um projeto do Google Cloud Platform
• Um navegador, como o Chrome ou o Firefox
• Familiaridade com C#

Pesquisa

Como você vai usar este tutorial?

Apenas leitura Leitura e exercícios

Como você classificaria sua experiência com C#?

Iniciante Intermediário Proficiente

Como você classificaria sua experiência com o uso dos serviços do Google Cloud Platform?

Iniciante Intermediário Proficiente

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

Ativar o Cloud Shell

1. No Console do Cloud, clique em Ativar o Cloud Shell.

Se você estiver iniciando o Cloud Shell pela primeira vez, verá uma tela intermediária com a descrição dele. Se aparecer uma tela intermediária, clique em Continuar.

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

Essa máquina virtual tem todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Grande parte do trabalho neste codelab, se não todo, pode ser feito em um navegador.

Depois de se conectar ao Cloud Shell, você verá sua autenticação e o projeto estará configurado com o ID do seu projeto.

2. Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:

gcloud auth list

Resposta ao comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Talvez seja necessário fazer a autenticação na primeira vez que você executar um comando. Para obter mais informações, consulte aos aspectos gerais da ferramenta de linha de comando gcloud.

3. Execute o seguinte comando no Cloud Shell para confirmar que o comando gcloud sabe sobre seu projeto:

gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se o projeto não estiver configurado, configure-o usando este comando:

gcloud config set project <PROJECT_ID>

Resposta ao comando

Updated property [core/project].

Observação:se você estiver concluindo este tutorial fora do Cloud Shell, siga as instruções em Configurar o Application Default Credentials.

3. ative a API Natural Language

Antes de começar a usar a API Natural Language, você precisa ativá-la. No Cloud Shell, é possível ativar a API com o seguinte comando:

gcloud services enable language.googleapis.com

Observação: se esse comando for exibido como erro, verifique se o ID do projeto atual corresponde ao ID do projeto do codelab.

Use o seguinte comando para encontrar o ID do projeto atual que está sendo usado pelo Cloud Shell:

gcloud info | grep "project"

Se o ID do projeto não estiver correto, use o seguinte comando para usá-lo:

gcloud config set project <PROJECT_ID>

Substitua <PROJECT_ID> pelo ID do projeto correto.

4. Instalar a biblioteca de cliente da Google Cloud Natural Language API para C#

Primeiro, crie um aplicativo simples de console em C# para executar exemplos da API Natural Language:

dotnet new console -n NaturalLanguageApiDemo

Você verá o aplicativo criado e as dependências resolvidas:

The template "Console Application" was created successfully.
Processing post-creation actions...
...
Restore succeeded.

Em seguida, navegue até a pasta NaturalLanguageApiDemo:

cd NaturalLanguageApiDemo/

Adicione o pacote NuGet Google.Cloud.Language.V1 ao projeto:

dotnet add package Google.Cloud.Language.V1

info : Adding PackageReference for package 'Google.Cloud.Language.V1' into project '/home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj'.
log  : Restoring packages for /home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj...
...
info : PackageReference for package 'Google.Cloud.Language.V1' version '1.1.0' added to file '/home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj'.

Agora você já pode usar a API Natural Language.

5. Análise de sentimento

Nesta seção, você vai fazer a análise de sentimento em uma string e descobrir a Score e a Magnitude usando a API Natural Language.

A pontuação de sentimento varia entre -1,0 (negativo) e 1,0 (positivo) e corresponde ao sentimento geral a partir das informações fornecidas.

A magnitude de sentimento varia de 0,0 a +infinito e indica a intensidade geral do sentimento com base nas informações fornecidas. Quanto mais informações forem fornecidas, maior será a magnitude.

Abra o editor de código no canto superior direito do Cloud Shell:

Navegue até o arquivo Program.cs dentro da pasta NaturalLanguageApiDemo e substitua o código pelo seguinte:

using System;
using Google.Cloud.Language.V1;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnalyzeSentiment(Document.FromPlainText(text));
            var sentiment = response.DocumentSentiment;
            Console.WriteLine($"Score: {sentiment.Score}");
            Console.WriteLine($"Magnitude: {sentiment.Magnitude}");
        }
    }
}

Reserve um ou dois minutos para estudar o código e conferir como o snippet de código é usado para realizar a análise de sentimento na string "Yukihiro Matsumoto é ótimo!".

No Cloud Shell, execute o app:

dotnet run

Você verá esta resposta:

Score: 0.9
Magnitude: 0.9

Observação: se esse código C# não funcionar para você, verifique as instruções executadas durante a etapa Autenticar solicitações de API.

Use o seguinte comando para verificar o valor da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

echo GOOGLE_APPLICATION_CREDENTIALS

A saída será o valor "~/key.json".

Em caso afirmativo, verifique se uma conta de serviço foi criada e está localizada em "~/key.json" usando:

cat "~/key.json"

Você verá algo como o seguinte:

{

"type": "service_account",

"project_id": "PROJECT_ID",

"private_key_id": "ff31939192529e07f42e4535fb20bb029def1276",

"Private_key":...

Caso contrário, volte à etapa Autenticar as solicitações de API.

Resumo

Nesta etapa, você realizou a análise de sentimento em uma string de texto e gerou a pontuação e a magnitude. Leia mais sobre a análise de sentimento.

6. Análise de entidades

A análise de entidade inspeciona as informações fornecidas em busca de entidades pesquisando substantivos próprios, como figuras públicas, pontos de referência etc., e retorna informações sobre essas entidades.

Para fazer a análise de entidades, navegue até o arquivo Program.cs dentro da pasta NaturalLanguageApiDemo e substitua o código pelo seguinte:

using System;
using Google.Cloud.Language.V1;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnalyzeEntitySentiment(Document.FromPlainText(text));

            foreach (var entity in response.Entities)
            {
                Console.WriteLine($"Entity: \"{entity.Name}\" ({entity.Type})");
                if (entity.Metadata.ContainsKey("wikipedia_url"))
                {
                    Console.WriteLine($"URL: {entity.Metadata["wikipedia_url"]}");
                }
            }
        }
    }
}

Reserve um ou dois minutos para estudar o código e conferir como o snippet de código é usado para realizar análise de entidades na string "Yukihiro Matsumoto is Great!".

No Cloud Shell, execute o app:

dotnet run

Você verá esta resposta:

Entity: "Yukihiro Matsumoto" (Person)
URL: https://en.wikipedia.org/wiki/Yukihiro_Matsumoto

Resumo

Nesta etapa, você realizou a análise de entidade em uma string de texto e imprimiu as entidades dela. Leia mais sobre a análise de entidades.

7. Análise sintática

A análise sintática extrai informações linguísticas, dividindo o texto fornecido em uma série de frases e tokens (geralmente, limites de palavra), oferecendo uma análise mais aprofundada desses tokens.

Este exemplo imprimirá o número de frases e tokens e fornecerá a classe gramatical de cada token.

Para fazer a análise sintática, navegue até o arquivo Program.cs na pasta NaturalLanguageApiDemo e substitua o código por este:

using System;
using Google.Cloud.Language.V1;
using static Google.Cloud.Language.V1.AnnotateTextRequest.Types;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnnotateText(Document.FromPlainText(text), 
                new Features { ExtractSyntax = true });

            var sentences = response.Sentences;
            var tokens = response.Tokens;

            Console.WriteLine($"Sentences: {sentences.Count}");
            Console.WriteLine($"Tokens: {tokens.Count}");

            foreach (var token in tokens)
            {
                Console.WriteLine($"{token.PartOfSpeech.Tag} {token.Text.Content}");
            }
        }
    }
}

Reserve um minuto ou dois para estudar o código e conferir como o snippet de código é usado para realizar a análise de sintaxe na string "Yukihiro Matsumoto is Great!".

No Cloud Shell, execute o app:

dotnet run

Você verá esta resposta:

Sentences: 1
Tokens: 5
Noun Yukihiro
Noun Matsumoto
Verb is
Adj great
Punct !

Confira abaixo uma interpretação visual.

Observação: é possível criar suas próprias árvores de análise com a demonstração da Natural Language disponível em https://cloud.google.com/natural-language/.

Resumo

Nesta etapa, você realizou a análise sintática em uma string de texto simples e imprimiu o número de frases, o número de tokens e as informações linguísticas de cada token. Leia mais sobre a Análise sintática.

8. Parabéns!

Você aprendeu a usar a API Natural Language com C# para realizar diferentes tipos de análise em informações.

Limpar

Para evitar a cobrança na sua conta do Google Cloud Platform pelo uso de recursos neste guia de início rápido, siga estas etapas:

• Acesse o console do Cloud Platform.
• Selecione o projeto que você quer encerrar e clique em "Excluir". Na parte superior: isso programa a exclusão do projeto.

Saiba mais

• API Google Cloud Natural Language: https://cloud.google.com/natural-language/docs/
• C#/.NET no Google Cloud Platform: https://cloud.google.com/dotnet/
• Cliente Google Cloud .NET: https://googlecloudplatform.github.io/google-cloud-dotnet/

Licença

Este conteúdo está sob a licença Atribuição 2.0 Genérica da Creative Commons.