google-cloud-language 0.32.0 → 0.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4aafb9034eaba005613dd083da7f3af843366d98c7f049eb67e2c17731dc0938
-  data.tar.gz: 21332829389d31c94b8560f3018defc8a5656720c18ea273025173e0794bac7b
+  metadata.gz: af7cef5fd721d2503d2253a9d389ce9d832446fc93f41ee12a11f1d48bda14e4
+  data.tar.gz: dd3a4121e367404e2d4e3442b9629ac3e4fa9d05ea17fc468fa5ae976a0be203
 SHA512:
-  metadata.gz: 2c4c803d81e7a924724afd8ff6a5a8d2b24a6fe4cc9d8c1fbc9f13c1fff9f3727da475602e7f7d1ec3a40fa6f9bd26e16f96388c91f0df598cf785f50b260372
-  data.tar.gz: 1f2afb0b2fb5cf2fcbd14223022e3ebc2b5faaa324cdbdf8bbda30f2a7d30187e7508ea791a2a088acb088ed442d72868e3ea93ac199da8293115458df4a338e
+  metadata.gz: 93256fbb9b5b8c81534534fe305d6b191138e6c2e65c1a733e55578f924a5513373ed356a62be602c1df5463e1ca1ccc1ef2399a7ea34ee973a4681ef91601cb
+  data.tar.gz: 9aad6c53ec2aebaa2e3a72b6c63c66436007aa107e76ed83fe306ea053c6a4db1211bf4d1415edb6f24eeafca64a27706faf7d84ee425904d6a702e603a5a0c3

data/.yardopts

@@ -7,3 +7,5 @@
 ./lib/**/*.rb
 -
 README.md
+AUTHENTICATION.md
+LICENSE

data/AUTHENTICATION.md

@@ -0,0 +1,199 @@
+# Authentication
+
+In general, the google-cloud-language library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running within [Google
+Cloud Platform environments](#google-cloud-platform-environments)
+the credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the [JSON
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in [environment
+variables](#environment-variables). Additionally, Cloud SDK credentials can also
+be discovered automatically, but this is only recommended during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export LANGUAGE_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/language"
+
+client = Google::Cloud::Language.new
+```
+
+## Project and Credential Lookup
+
+The google-cloud-language library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without providing **Project ID** and **Service Account Credentials** directly in
+code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+5. Discover project ID in credentials JSON
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that google-cloud-language checks for project ID are:
+
+1. `LANGUAGE_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that google-cloud-language checks for credentials are configured on {Google::Cloud::Language::V1::Credentials}:
+
+1. `LANGUAGE_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `LANGUAGE_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/language"
+
+ENV["LANGUAGE_PROJECT"]     = "my-project-id"
+ENV["LANGUAGE_CREDENTIALS"] = "path/to/keyfile.json"
+
+client = Google::Cloud::Language.new
+```
+
+### Configuration
+
+The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+
+```ruby
+require "google/cloud/language"
+
+Google::Cloud::Language.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+client = Google::Cloud::Language.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-language.
+
+If you are not running this client within [Google Cloud Platform
+environments](#google-cloud-platform-environments), you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/lib/google/cloud/language/v1/doc/google/cloud/language/v1/language_service.rb

@@ -27,6 +27,7 @@ module Google
         # @!attribute [rw] content
         #   @return [String]
         #     The content of the input in string format.
+        #     Cloud audit logging exempt since it is based on user data.
         # @!attribute [rw] gcs_content_uri
         #   @return [String]
         #     The Google Cloud Storage URI where the file content is located.
@@ -64,8 +65,8 @@ module Google
         # @!attribute [rw] sentiment
         #   @return [Google::Cloud::Language::V1::Sentiment]
         #     For calls to {AnalyzeSentiment} or if
-        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment}
-        #     is set to true, this field will contain the sentiment for the sentence.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment} is set to
+        #     true, this field will contain the sentiment for the sentence.
         class Sentence; end
 
         # Represents a phrase in the text that is a known entity, such as
@@ -81,8 +82,9 @@ module Google
         #   @return [Hash{String => String}]
         #     Metadata associated with the entity.
         #
-        #     Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if
-        #     available. The associated keys are "wikipedia_url" and "mid", respectively.
+        #     For most entity types, the metadata is a Wikipedia URL (`wikipedia_url`)
+        #     and Knowledge Graph MID (`mid`), if they are available. For the metadata
+        #     associated with other entity types, see the Type table below.
         # @!attribute [rw] salience
         #   @return [Float]
         #     The salience score associated with the entity in the [0, 1.0] range.
@@ -98,11 +100,14 @@ module Google
         # @!attribute [rw] sentiment
         #   @return [Google::Cloud::Language::V1::Sentiment]
         #     For calls to {AnalyzeEntitySentiment} or if
-        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment}
-        #     is set to true, this field will contain the aggregate sentiment expressed
-        #     for this entity in the provided document.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
+        #     true, this field will contain the aggregate sentiment expressed for this
+        #     entity in the provided document.
         class Entity
-          # The type of the entity.
+          # The type of the entity. For most entity types, the associated metadata is a
+          # Wikipedia URL (`wikipedia_url`) and Knowledge Graph MID (`mid`). The table
+          # below lists the associated fields for entities that have different
+          # metadata.
           module Type
             # Unknown
             UNKNOWN = 0
@@ -119,28 +124,53 @@ module Google
             # Event
             EVENT = 4
 
-            # Work of art
+            # Artwork
             WORK_OF_ART = 5
 
-            # Consumer goods
+            # Consumer product
             CONSUMER_GOOD = 6
 
-            # Other types
+            # Other types of entities
             OTHER = 7
 
-            # Phone number
+            # Phone number<br><br>
+            # The metadata lists the phone number, formatted according to local
+            # convention, plus whichever additional elements appear in the text:<ul>
+            # <li><code>number</code> &ndash; the actual number, broken down into
+            # sections as per local convention</li> <li><code>national_prefix</code>
+            # &ndash; country code, if detected</li> <li><code>area_code</code> &ndash;
+            # region or area code, if detected</li> <li><code>extension</code> &ndash;
+            # phone extension (to be dialed after connection), if detected</li></ul>
             PHONE_NUMBER = 9
 
-            # Address
+            # Address<br><br>
+            # The metadata identifies the street number and locality plus whichever
+            # additional elements appear in the text:<ul>
+            # <li><code>street_number</code> &ndash; street number</li>
+            # <li><code>locality</code> &ndash; city or town</li>
+            # <li><code>street_name</code> &ndash; street/route name, if detected</li>
+            # <li><code>postal_code</code> &ndash; postal code, if detected</li>
+            # <li><code>country</code> &ndash; country, if detected</li>
+            # <li><code>broad_region</code> &ndash; administrative area, such as the
+            # state, if detected</li> <li><code>narrow_region</code> &ndash; smaller
+            # administrative area, such as county, if detected</li>
+            # <li><code>sublocality</code> &ndash; used in Asian addresses to demark a
+            # district within a city, if detected</li></ul>
             ADDRESS = 10
 
-            # Date
+            # Date<br><br>
+            # The metadata identifies the components of the date:<ul>
+            # <li><code>year</code> &ndash; four digit year, if detected</li>
+            # <li><code>month</code> &ndash; two digit month number, if detected</li>
+            # <li><code>day</code> &ndash; two digit day number, if detected</li></ul>
             DATE = 11
 
-            # Number
+            # Number<br><br>
+            # The metadata is the number itself.
             NUMBER = 12
 
-            # Price
+            # Price<br><br>
+            # The metadata identifies the <code>value</code> and <code>currency</code>.
             PRICE = 13
           end
         end
@@ -781,9 +811,9 @@ module Google
         # @!attribute [rw] sentiment
         #   @return [Google::Cloud::Language::V1::Sentiment]
         #     For calls to {AnalyzeEntitySentiment} or if
-        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment}
-        #     is set to true, this field will contain the sentiment expressed for this
-        #     mention of the entity in the provided document.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
+        #     true, this field will contain the sentiment expressed for this mention of
+        #     the entity in the provided document.
         class EntityMention
           # The supported types of mentions.
           module Type
@@ -805,9 +835,7 @@ module Google
         # @!attribute [rw] begin_offset
         #   @return [Integer]
         #     The API calculates the beginning offset of the content in the original
-        #     document according to the
-        #     {Google::Cloud::Language::V1::EncodingType EncodingType} specified in the API
-        #     request.
+        #     document according to the {Google::Cloud::Language::V1::EncodingType EncodingType} specified in the API request.
         class TextSpan; end
 
         # Represents a category returned from the text classifier.
@@ -838,8 +866,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See {Google::Cloud::Language::V1::Document#language Document#language} field
-        #     for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         # @!attribute [rw] sentences
         #   @return [Array<Google::Cloud::Language::V1::Sentence>]
         #     The sentiment for all the sentences in the document.
@@ -862,8 +889,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See {Google::Cloud::Language::V1::Document#language Document#language} field
-        #     for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         class AnalyzeEntitySentimentResponse; end
 
         # The entity analysis request message.
@@ -883,8 +909,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See {Google::Cloud::Language::V1::Document#language Document#language} field
-        #     for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         class AnalyzeEntitiesResponse; end
 
         # The syntax analysis request message.
@@ -907,8 +932,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See {Google::Cloud::Language::V1::Document#language Document#language} field
-        #     for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         class AnalyzeSyntaxResponse; end
 
         # The document classification request message.
@@ -978,8 +1002,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See {Google::Cloud::Language::V1::Document#language Document#language} field
-        #     for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         # @!attribute [rw] categories
         #   @return [Array<Google::Cloud::Language::V1::ClassificationCategory>]
         #     Categories identified in the input document.

data/lib/google/cloud/language/v1/language_service_client.rb

@@ -274,10 +274,8 @@ module Google
             @analyze_entities.call(req, options, &block)
           end
 
-          # Finds entities, similar to
-          # {Google::Cloud::Language::V1::LanguageService::AnalyzeEntities AnalyzeEntities}
-          # in the text and analyzes sentiment associated with each entity and its
-          # mentions.
+          # Finds entities, similar to {Google::Cloud::Language::V1::LanguageService::AnalyzeEntities AnalyzeEntities} in the text and analyzes
+          # sentiment associated with each entity and its mentions.
           #
           # @param document [Google::Cloud::Language::V1::Document | Hash]
           #   Input document.

data/lib/google/cloud/language/v1/language_service_pb.rb

@@ -5,6 +5,8 @@
 require 'google/protobuf'
 
 require 'google/api/annotations_pb'
+require 'google/api/client_pb'
+require 'google/api/field_behavior_pb'
 Google::Protobuf::DescriptorPool.generated_pool.build do
   add_message "google.cloud.language.v1.Document" do
     optional :type, :enum, 1, "google.cloud.language.v1.Document.Type"

data/lib/google/cloud/language/v1/language_service_services_pb.rb

@@ -42,10 +42,8 @@ module Google
             # along with entity types, salience, mentions for each entity, and
             # other properties.
             rpc :AnalyzeEntities, AnalyzeEntitiesRequest, AnalyzeEntitiesResponse
-            # Finds entities, similar to
-            # [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities]
-            # in the text and analyzes sentiment associated with each entity and its
-            # mentions.
+            # Finds entities, similar to [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities] in the text and analyzes
+            # sentiment associated with each entity and its mentions.
             rpc :AnalyzeEntitySentiment, AnalyzeEntitySentimentRequest, AnalyzeEntitySentimentResponse
             # Analyzes the syntax of the text and provides sentence boundaries and
             # tokenization along with part of speech tags, dependency trees, and other

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-language
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.32.1
 platform: ruby
 authors:
 - Google LLC
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-28 00:00:00.000000000 Z
+date: 2019-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-gax
@@ -24,6 +24,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: googleapis-common-protos
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -102,6 +122,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
+- AUTHENTICATION.md
 - LICENSE
 - README.md
 - lib/google/cloud/language.rb