Migrating to Ruby Natural Language Client Library v0.28.0

The Ruby Natural Language Client Library v0.28.0 has significant design differences from previous client libraries.

The following changes have been made to the Natural Language library:

  • The client library is more consistent with the RPC API.

  • Each analyze request is now represented by separate method call associated to the Google::Cloud::Language class as opposed to using the Google::Cloud::Language::Document class.

  • Content method parameters now distinguish between content in a String literal and content on Google Cloud Storage.

This topic provides details on the changes that you will need to make to your Ruby code for the Cloud Natural Language API client libraries in order to use the v0.28.0 Ruby client library.

Running previous versions of the client library

You are not required to upgrade your Ruby client library to v0.28.0. If you want to continue using a previous version of the Ruby client library and do not want to migrate your code, then you should specify the exact version of the Ruby client library used by your app. For example, to specify a specific library version, edit the project Gemfile file as shown following:

gem "google-cloud-language", "0.27.1"

Deprecated Classes

The following classes are deprecated in the Ruby Language Client Library v0.28.0 gem.

  • Google::Cloud::Language::Project

  • Google::Cloud::Language::Document

  • Google::Cloud::Language::Annotation

Required Code Changes

Gem dependency

There are no changes to the client library path for the Ruby Language Client Library v0.28.0 gem.

require "google/cloud/language"

Create a client

When you create a Natural Language API client using the Ruby Language Client Library v0.28.0, you must make the following changes:

  • Remove the project parameter. The project parameter has been removed because the Natural Language API doesn't include a project name in requests.
language = Google::Cloud::Language.new

Constructing requests

The following sections cover constructing requests using the Ruby Language Client Library v0.28.0. The examples make requests using both a string of text and a URI for a file from Google Cloud Storage.

Analyzing content from a text string

The following example shows an example of sending content from a text string to the Natural Language API.

Previous versions of the client libraries:

# project_id   = "Your Google Cloud project ID"
# text_content = "text content for NLP api"

require "google/cloud/language"

language = Google::Cloud::Language.new project project_id
document = language.document text_content

sentiment = document.sentiment

Ruby Client Library v0.28.0:

# text_content = "Text to run sentiment analysis on"

require "google/cloud/language"

language = Google::Cloud::Language.new

response = language.analyze_sentiment content: text_content, type: :PLAIN_TEXT

sentiment = response.document_sentiment

The content parameter is available in all analyze methods. You can also analyze HTML by setting the type parameter language.analyze_sentiment content: text_content, type: :HTML.

Analyzing content from a file

The following example shows the new way to represent text content from a Google Cloud Storage URI or a web URI when performing sentiment analysis using the new gcs_content_uri parameter.

Previous versions of the client libraries:

# project_id   = "Your Google Cloud project ID"
# storage_path = "gs://path/to/file"

require "google/cloud/language"

language = Google::Cloud::Language.new project project_id
document = language.document storage_path

sentiment = document.sentiment

Ruby Client Library v0.28.0:

# storage_path = "Path to file in Google Cloud Storage, eg. gs://bucket/file"

require "google/cloud/language"

language = Google::Cloud::Language.new

response = language.analyze_sentiment gcs_content_uri: storage_path, type: :PLAIN_TEXT

sentiment = response.document_sentiment

The gcs_content_uri parameter is available in all analyze methods. You can also analyze HTML by setting the type parameter language.analyze_sentiment content: text_content, type: :HTML.

Updated requests and responses

Analyze sentiment

Requests to the AnalyzeSentiment method are now made using Google::Cloud::Language#analyze_sentiment as shown below.

Previous versions of the client library:

# project_id   = "Your Google Cloud project ID"
# text_content = "text content for NLP api"

require "google/cloud/language"

language  = Google::Cloud::Language.new project: project_id
document  = language.document text_content
sentiment = document.sentiment

puts "Overall document sentiment: (#{sentiment.score})"
puts "Sentence level sentiment:"

sentiment.sentences.each do |sentence|
  sentiment = sentence.sentiment
  puts "#{sentence.text}: (#{sentiment.score})"
end

Ruby Client Library v0.28.0:

# text_content = "Text to run sentiment analysis on"

require "google/cloud/language"

language = Google::Cloud::Language.new

response = language.analyze_sentiment content: text_content, type: :PLAIN_TEXT

sentiment = response.document_sentiment

puts "Overall document sentiment: (#{sentiment.score})"
puts "Sentence level sentiment:"

sentences = response.sentences

sentences.each do |sentence|
  sentiment = sentence.sentiment
  puts "#{sentence.text.content}: (#{sentiment.score})"
end

Analyze entities

Requests to the AnalyzeEntities method are now made using Google::Cloud::Language#analyze_entities as shown below.

Previous versions of the client library:

# project_id   = "Your Google Cloud project ID"
# text_content = "text content for NLP api"

require "google/cloud/language"

language = Google::Cloud::Language.new project: project_id
document = language.document text_content
entities = document.entities

entities.each do |entity|
  puts "Entity #{entity.name} #{entity.type}"

  if entity.metadata["wikipedia_url"]
    puts "URL: #{entity.metadata['wikipedia_url']}"
  end
end

Ruby Client Library v0.28.0:

# text_content = "Text to extract entities from"

require "google/cloud/language"

language = Google::Cloud::Language.new

response = language.analyze_entities content: text_content, type: :PLAIN_TEXT

entities = response.entities

entities.each do |entity|
  puts "Entity #{entity.name} #{entity.type}"

  if entity.metadata["wikipedia_url"]
    puts "URL: #{entity.metadata['wikipedia_url']}"
  end
end

Analyze syntax

Requests to the AnalyzeSyntax method are now made using Google::Cloud::Language#analyze_syntax as shown below.

Sentences and parts of speech tags that were available in Google::Cloud::Language::Annotation::Syntax are also accessed in the response to a Google::Cloud::Language#analyze_syntax request as shown below.

Previous versions of the client library:

# project_id   = "Your Google Cloud project ID"
# text_content = "text content for NLP api"

require "google/cloud/language"

language = Google::Cloud::Language.new project: project_id
document = language.document text_content
syntax   = document.syntax

puts "Sentences: #{syntax.sentences.count}"
puts "Tokens: #{syntax.tokens.count}"

syntax.tokens.each do |token|
  puts "#{token.part_of_speech.tag} #{token.text_span.text}"
end

Ruby Client Library v0.28.0:

# text_content = "Text to analyze syntax of"

require "google/cloud/language"

language = Google::Cloud::Language.new
response = language.analyze_syntax content: text_content, type: :PLAIN_TEXT

sentences = response.sentences
tokens    = response.tokens

puts "Sentences: #{sentences.count}"
puts "Tokens: #{tokens.count}"

tokens.each do |token|
  puts "#{token.part_of_speech.tag} #{token.text.content}"
end

Send feedback about...

Cloud Natural Language API Documentation