Module: Google::Cloud::Language

Defined in:: lib/google/cloud/language.rb,
lib/google/cloud/language/convert.rb,
lib/google/cloud/language/project.rb,
lib/google/cloud/language/service.rb,
lib/google/cloud/language/version.rb,
lib/google/cloud/language/document.rb,
lib/google/cloud/language/annotation.rb,
lib/google/cloud/language/credentials.rb,
lib/google/cloud/language/v1/language_service_pb.rb,
lib/google/cloud/language/v1/language_service_client.rb,
lib/google/cloud/language/v1/language_service_services_pb.rb,
lib/google/cloud/language/v1/doc/google/cloud/language/v1/language_service.rb

Overview

Google Cloud Natural Language API

Google Cloud Natural Language API reveals the structure and meaning of text by offering powerful machine learning models in an easy to use REST API. You can use it to extract information about people, places, events and much more, mentioned in text documents, news articles or blog posts. You can use it to understand sentiment about your product on social media or parse intent from customer conversations happening in a call center or a messaging app. You can analyze text uploaded in your request or integrate with your document storage on Google Cloud Storage. Combine the API with the Google Cloud Speech API and extract insights from audio conversations. Use with Vision API OCR to understand scanned documents. Extract entities and understand sentiments in multiple languages by translating text first with Cloud Translation API.

The Google Cloud Natural Language API is currently a beta release, and might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy and is not intended for real-time usage in critical applications.

For more information about Cloud Natural Language API, read the Google Cloud Natural Language API Documentation.

The goal of google-cloud is to provide an API that is comfortable to Rubyists. Authentication is handled by #language. You can provide the project and credential information to connect to the Cloud Natural Language API, or if you are running on Google Compute Engine this configuration is taken care of for you. You can read more about the options for connecting in the Authentication Guide.

Creating documents

Cloud Natural Language API supports UTF-8, UTF-16, and UTF-32 encodings. (Ruby uses UTF-8 natively, which is the default sent to the API, so unless you're working with text processed in different platform, you should not need to set the encoding type.) Be aware that only English, Spanish, and Japanese language content are supported.

Use Project#document to create documents for the Cloud Natural Language service. You can provide text or HTML content as a string:

require "google/cloud/language"

language = Google::Cloud::Language.new

document = language.document "It was the best of times, it was..."

Or, you can pass a Google Cloud Storage URI for a text or HTML file:

require "google/cloud/language"

language = Google::Cloud::Language.new

document = language.document "gs://bucket-name/path/to/document"

Or, you can initialize it with a Google Cloud Storage File object:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "bucket-name"
file = bucket.file "path/to/document"

require "google/cloud/language"

language = Google::Cloud::Language.new

document = language.document file

You can specify the format and language of the content:

require "google/cloud/language"

language = Google::Cloud::Language.new

document = language.document "<p>El viejo y el mar</p>",
                             format: :html, language: "es"

Creating a Document instance does not perform an API request.

Annotating documents

The instance methods on Document invoke Cloud Natural Language's detection features individually. Each method call makes an API request. If you want to run multiple features in a single request, see the examples for Document#annotate, below. Calling annotate with no arguments will perform all analysis features. Each feature is priced separately. See Pricing for details.

Sentiment analysis inspects the given text and identifies the prevailing emotional opinion within the text, especially to determine a writer's attitude as positive, negative, or neutral. Sentiment analysis can be performed with the Document#sentiment method. Currently, only English is supported for sentiment analysis.

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
sentiment = document.sentiment # API call

sentiment.score #=> 0.10000000149011612
sentiment.magnitude #=> 1.100000023841858

Entity analysis inspects the given text for known entities (proper nouns such as public figures, landmarks, etc.) and returns information about those entities. Entity analysis can be performed with the Document#entities method.

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
entities = document.entities # API call

entities.count #=> 3
entities.first.name #=> "Star Wars"
entities.first.type #=> :WORK_OF_ART
entities.first.mid #=> "/m/06mmr"
entities.first.wikipedia_url #=> "http://en.wikipedia.org/wiki/Star_Wars"

Syntactic analysis extracts linguistic information, breaking up the given text into a series of sentences and tokens (generally, word boundaries), providing further analysis on those tokens. Syntactic analysis can be performed with the Document#syntax method.

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
syntax = document.syntax # API call

syntax.sentences.count #=> 2
syntax.tokens.count #=> 13

To run multiple features on a document in a single request, pass the flag for each desired feature to Document#annotate:

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
annotation = document.annotate entities: true, text: true

annotation.sentiment #=> nil
annotation.entities.count #=> 3
annotation.sentences.count #=> 2
annotation.tokens.count #=> 13

Or, simply call Document#annotate with no arguments to process the document with all features:

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
annotation = document.annotate

annotation.sentiment.score #=> 0.10000000149011612
annotation.sentiment.magnitude #=> 1.100000023841858
annotation.entities.count #=> 3
annotation.sentences.count #=> 2
annotation.tokens.count #=> 13

Defined Under Namespace

Modules: V1 Classes: Annotation, Document, Project

Constant Summary collapse

VERSION =

"0.24.0"

Class Method Summary collapse

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ Google::Cloud::Language::Project
Creates a new object for connecting to the Language service.

Class Method Details

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ `Google::Cloud::Language::Project`

Creates a new object for connecting to the Language service. Each call creates a new connection.

For more information on connecting to Google Cloud see the Authentication Guide.

Examples:

require "google/cloud/language"

language = Google::Cloud::Language.new

content = "Star Wars is a great movie. The Death Star is fearsome."
document = language.document content
annotation = document.annotate

Parameters:

project (String) (defaults to: nil) —
Project identifier for the Language service you are connecting to.
keyfile (String, Hash) (defaults to: nil) —
Keyfile downloaded from Google Cloud. If file path the file must be readable.
scope (String, Array<String>) (defaults to: nil) —
The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

The default scope is:
- "https://www.googleapis.com/auth/cloud-platform"
timeout (Integer) (defaults to: nil) —
Default timeout to use in requests. Optional.
client_config (Hash) (defaults to: nil) —
A hash of values to override the default behavior of the API client. Optional.

Returns:

(Google::Cloud::Language::Project)

# File 'lib/google/cloud/language.rb', line 255

def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
             client_config: nil
  project ||= Google::Cloud::Language::Project.default_project
  if keyfile.nil?
    credentials = Google::Cloud::Language::Credentials.default(
      scope: scope)
  else
    credentials = Google::Cloud::Language::Credentials.new(
      keyfile, scope: scope)
  end
  Google::Cloud::Language::Project.new(
    Google::Cloud::Language::Service.new(
      project, credentials, timeout: timeout,
                            client_config: client_config))
end