google-cloud-language 0.32.0 → 0.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4aafb9034eaba005613dd083da7f3af843366d98c7f049eb67e2c17731dc0938
4
- data.tar.gz: 21332829389d31c94b8560f3018defc8a5656720c18ea273025173e0794bac7b
3
+ metadata.gz: af7cef5fd721d2503d2253a9d389ce9d832446fc93f41ee12a11f1d48bda14e4
4
+ data.tar.gz: dd3a4121e367404e2d4e3442b9629ac3e4fa9d05ea17fc468fa5ae976a0be203
5
5
  SHA512:
6
- metadata.gz: 2c4c803d81e7a924724afd8ff6a5a8d2b24a6fe4cc9d8c1fbc9f13c1fff9f3727da475602e7f7d1ec3a40fa6f9bd26e16f96388c91f0df598cf785f50b260372
7
- data.tar.gz: 1f2afb0b2fb5cf2fcbd14223022e3ebc2b5faaa324cdbdf8bbda30f2a7d30187e7508ea791a2a088acb088ed442d72868e3ea93ac199da8293115458df4a338e
6
+ metadata.gz: 93256fbb9b5b8c81534534fe305d6b191138e6c2e65c1a733e55578f924a5513373ed356a62be602c1df5463e1ca1ccc1ef2399a7ea34ee973a4681ef91601cb
7
+ data.tar.gz: 9aad6c53ec2aebaa2e3a72b6c63c66436007aa107e76ed83fe306ea053c6a4db1211bf4d1415edb6f24eeafca64a27706faf7d84ee425904d6a702e603a5a0c3
data/.yardopts CHANGED
@@ -7,3 +7,5 @@
7
7
  ./lib/**/*.rb
8
8
  -
9
9
  README.md
10
+ AUTHENTICATION.md
11
+ LICENSE
@@ -0,0 +1,199 @@
1
+ # Authentication
2
+
3
+ In general, the google-cloud-language library uses [Service
4
+ Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
5
+ credentials to connect to Google Cloud services. When running within [Google
6
+ Cloud Platform environments](#google-cloud-platform-environments)
7
+ the credentials will be discovered automatically. When running on other
8
+ environments, the Service Account credentials can be specified by providing the
9
+ path to the [JSON
10
+ keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
11
+ the account (or the JSON itself) in [environment
12
+ variables](#environment-variables). Additionally, Cloud SDK credentials can also
13
+ be discovered automatically, but this is only recommended during development.
14
+
15
+ ## Quickstart
16
+
17
+ 1. [Create a service account and credentials](#creating-a-service-account).
18
+ 2. Set the [environment variable](#environment-variables).
19
+
20
+ ```sh
21
+ export LANGUAGE_CREDENTIALS=/path/to/json`
22
+ ```
23
+
24
+ 3. Initialize the client.
25
+
26
+ ```ruby
27
+ require "google/cloud/language"
28
+
29
+ client = Google::Cloud::Language.new
30
+ ```
31
+
32
+ ## Project and Credential Lookup
33
+
34
+ The google-cloud-language library aims to make authentication
35
+ as simple as possible, and provides several mechanisms to configure your system
36
+ without providing **Project ID** and **Service Account Credentials** directly in
37
+ code.
38
+
39
+ **Project ID** is discovered in the following order:
40
+
41
+ 1. Specify project ID in method arguments
42
+ 2. Specify project ID in configuration
43
+ 3. Discover project ID in environment variables
44
+ 4. Discover GCE project ID
45
+ 5. Discover project ID in credentials JSON
46
+
47
+ **Credentials** are discovered in the following order:
48
+
49
+ 1. Specify credentials in method arguments
50
+ 2. Specify credentials in configuration
51
+ 3. Discover credentials path in environment variables
52
+ 4. Discover credentials JSON in environment variables
53
+ 5. Discover credentials file in the Cloud SDK's path
54
+ 6. Discover GCE credentials
55
+
56
+ ### Google Cloud Platform environments
57
+
58
+ While running on Google Cloud Platform environments such as Google Compute
59
+ Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
60
+ The **Project ID** and **Credentials** and are discovered automatically. Code
61
+ should be written as if already authenticated. Just be sure when you [set up the
62
+ GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
63
+ access. For example:
64
+
65
+ * **All APIs**
66
+ * `https://www.googleapis.com/auth/cloud-platform`
67
+ * `https://www.googleapis.com/auth/cloud-platform.read-only`
68
+ * **BigQuery**
69
+ * `https://www.googleapis.com/auth/bigquery`
70
+ * `https://www.googleapis.com/auth/bigquery.insertdata`
71
+ * **Compute Engine**
72
+ * `https://www.googleapis.com/auth/compute`
73
+ * **Datastore**
74
+ * `https://www.googleapis.com/auth/datastore`
75
+ * `https://www.googleapis.com/auth/userinfo.email`
76
+ * **DNS**
77
+ * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
78
+ * **Pub/Sub**
79
+ * `https://www.googleapis.com/auth/pubsub`
80
+ * **Storage**
81
+ * `https://www.googleapis.com/auth/devstorage.full_control`
82
+ * `https://www.googleapis.com/auth/devstorage.read_only`
83
+ * `https://www.googleapis.com/auth/devstorage.read_write`
84
+
85
+ ### Environment Variables
86
+
87
+ The **Project ID** and **Credentials JSON** can be placed in environment
88
+ variables instead of declaring them directly in code. Each service has its own
89
+ environment variable, allowing for different service accounts to be used for
90
+ different services. (See the READMEs for the individual service gems for
91
+ details.) The path to the **Credentials JSON** file can be stored in the
92
+ environment variable, or the **Credentials JSON** itself can be stored for
93
+ environments such as Docker containers where writing files is difficult or not
94
+ encouraged.
95
+
96
+ The environment variables that google-cloud-language checks for project ID are:
97
+
98
+ 1. `LANGUAGE_PROJECT`
99
+ 2. `GOOGLE_CLOUD_PROJECT`
100
+
101
+ The environment variables that google-cloud-language checks for credentials are configured on {Google::Cloud::Language::V1::Credentials}:
102
+
103
+ 1. `LANGUAGE_CREDENTIALS` - Path to JSON file, or JSON contents
104
+ 2. `LANGUAGE_KEYFILE` - Path to JSON file, or JSON contents
105
+ 3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
106
+ 4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
107
+ 5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
108
+
109
+ ```ruby
110
+ require "google/cloud/language"
111
+
112
+ ENV["LANGUAGE_PROJECT"] = "my-project-id"
113
+ ENV["LANGUAGE_CREDENTIALS"] = "path/to/keyfile.json"
114
+
115
+ client = Google::Cloud::Language.new
116
+ ```
117
+
118
+ ### Configuration
119
+
120
+ The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
121
+
122
+ ```ruby
123
+ require "google/cloud/language"
124
+
125
+ Google::Cloud::Language.configure do |config|
126
+ config.project_id = "my-project-id"
127
+ config.credentials = "path/to/keyfile.json"
128
+ end
129
+
130
+ client = Google::Cloud::Language.new
131
+ ```
132
+
133
+ ### Cloud SDK
134
+
135
+ This option allows for an easy way to authenticate during development. If
136
+ credentials are not provided in code or in environment variables, then Cloud SDK
137
+ credentials are discovered.
138
+
139
+ To configure your system for this, simply:
140
+
141
+ 1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
142
+ 2. Authenticate using OAuth 2.0 `$ gcloud auth login`
143
+ 3. Write code as if already authenticated.
144
+
145
+ **NOTE:** This is _not_ recommended for running in production. The Cloud SDK
146
+ *should* only be used during development.
147
+
148
+ [gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
149
+ [dev-console]: https://console.cloud.google.com/project
150
+
151
+ [enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
152
+
153
+ [create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
154
+ [create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
155
+ [reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
156
+
157
+ ## Creating a Service Account
158
+
159
+ Google Cloud requires a **Project ID** and **Service Account Credentials** to
160
+ connect to the APIs. You will use the **Project ID** and **JSON key file** to
161
+ connect to most services with google-cloud-language.
162
+
163
+ If you are not running this client within [Google Cloud Platform
164
+ environments](#google-cloud-platform-environments), you need a Google
165
+ Developers service account.
166
+
167
+ 1. Visit the [Google Developers Console][dev-console].
168
+ 1. Create a new project or click on an existing project.
169
+ 1. Activate the slide-out navigation tray and select **API Manager**. From
170
+ here, you will enable the APIs that your application requires.
171
+
172
+ ![Enable the APIs that your application requires][enable-apis]
173
+
174
+ *Note: You may need to enable billing in order to use these services.*
175
+
176
+ 1. Select **Credentials** from the side navigation.
177
+
178
+ You should see a screen like one of the following.
179
+
180
+ ![Create a new service account][create-new-service-account]
181
+
182
+ ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
183
+
184
+ Find the "Add credentials" drop down and select "Service account" to be
185
+ guided through downloading a new JSON key file.
186
+
187
+ If you want to re-use an existing service account, you can easily generate a
188
+ new key file. Just select the account you wish to re-use, and click "Generate
189
+ new JSON key":
190
+
191
+ ![Re-use an existing service account][reuse-service-account]
192
+
193
+ The key file you download will be used by this library to authenticate API
194
+ requests and should be stored in a secure location.
195
+
196
+ ## Troubleshooting
197
+
198
+ If you're having trouble authenticating you can ask for help by following the
199
+ {file:TROUBLESHOOTING.md Troubleshooting Guide}.
@@ -27,6 +27,7 @@ module Google
27
27
  # @!attribute [rw] content
28
28
  # @return [String]
29
29
  # The content of the input in string format.
30
+ # Cloud audit logging exempt since it is based on user data.
30
31
  # @!attribute [rw] gcs_content_uri
31
32
  # @return [String]
32
33
  # The Google Cloud Storage URI where the file content is located.
@@ -64,8 +65,8 @@ module Google
64
65
  # @!attribute [rw] sentiment
65
66
  # @return [Google::Cloud::Language::V1::Sentiment]
66
67
  # For calls to {AnalyzeSentiment} or if
67
- # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment}
68
- # is set to true, this field will contain the sentiment for the sentence.
68
+ # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment} is set to
69
+ # true, this field will contain the sentiment for the sentence.
69
70
  class Sentence; end
70
71
 
71
72
  # Represents a phrase in the text that is a known entity, such as
@@ -81,8 +82,9 @@ module Google
81
82
  # @return [Hash{String => String}]
82
83
  # Metadata associated with the entity.
83
84
  #
84
- # Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if
85
- # available. The associated keys are "wikipedia_url" and "mid", respectively.
85
+ # For most entity types, the metadata is a Wikipedia URL (`wikipedia_url`)
86
+ # and Knowledge Graph MID (`mid`), if they are available. For the metadata
87
+ # associated with other entity types, see the Type table below.
86
88
  # @!attribute [rw] salience
87
89
  # @return [Float]
88
90
  # The salience score associated with the entity in the [0, 1.0] range.
@@ -98,11 +100,14 @@ module Google
98
100
  # @!attribute [rw] sentiment
99
101
  # @return [Google::Cloud::Language::V1::Sentiment]
100
102
  # For calls to {AnalyzeEntitySentiment} or if
101
- # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment}
102
- # is set to true, this field will contain the aggregate sentiment expressed
103
- # for this entity in the provided document.
103
+ # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
104
+ # true, this field will contain the aggregate sentiment expressed for this
105
+ # entity in the provided document.
104
106
  class Entity
105
- # The type of the entity.
107
+ # The type of the entity. For most entity types, the associated metadata is a
108
+ # Wikipedia URL (`wikipedia_url`) and Knowledge Graph MID (`mid`). The table
109
+ # below lists the associated fields for entities that have different
110
+ # metadata.
106
111
  module Type
107
112
  # Unknown
108
113
  UNKNOWN = 0
@@ -119,28 +124,53 @@ module Google
119
124
  # Event
120
125
  EVENT = 4
121
126
 
122
- # Work of art
127
+ # Artwork
123
128
  WORK_OF_ART = 5
124
129
 
125
- # Consumer goods
130
+ # Consumer product
126
131
  CONSUMER_GOOD = 6
127
132
 
128
- # Other types
133
+ # Other types of entities
129
134
  OTHER = 7
130
135
 
131
- # Phone number
136
+ # Phone number<br><br>
137
+ # The metadata lists the phone number, formatted according to local
138
+ # convention, plus whichever additional elements appear in the text:<ul>
139
+ # <li><code>number</code> &ndash; the actual number, broken down into
140
+ # sections as per local convention</li> <li><code>national_prefix</code>
141
+ # &ndash; country code, if detected</li> <li><code>area_code</code> &ndash;
142
+ # region or area code, if detected</li> <li><code>extension</code> &ndash;
143
+ # phone extension (to be dialed after connection), if detected</li></ul>
132
144
  PHONE_NUMBER = 9
133
145
 
134
- # Address
146
+ # Address<br><br>
147
+ # The metadata identifies the street number and locality plus whichever
148
+ # additional elements appear in the text:<ul>
149
+ # <li><code>street_number</code> &ndash; street number</li>
150
+ # <li><code>locality</code> &ndash; city or town</li>
151
+ # <li><code>street_name</code> &ndash; street/route name, if detected</li>
152
+ # <li><code>postal_code</code> &ndash; postal code, if detected</li>
153
+ # <li><code>country</code> &ndash; country, if detected</li>
154
+ # <li><code>broad_region</code> &ndash; administrative area, such as the
155
+ # state, if detected</li> <li><code>narrow_region</code> &ndash; smaller
156
+ # administrative area, such as county, if detected</li>
157
+ # <li><code>sublocality</code> &ndash; used in Asian addresses to demark a
158
+ # district within a city, if detected</li></ul>
135
159
  ADDRESS = 10
136
160
 
137
- # Date
161
+ # Date<br><br>
162
+ # The metadata identifies the components of the date:<ul>
163
+ # <li><code>year</code> &ndash; four digit year, if detected</li>
164
+ # <li><code>month</code> &ndash; two digit month number, if detected</li>
165
+ # <li><code>day</code> &ndash; two digit day number, if detected</li></ul>
138
166
  DATE = 11
139
167
 
140
- # Number
168
+ # Number<br><br>
169
+ # The metadata is the number itself.
141
170
  NUMBER = 12
142
171
 
143
- # Price
172
+ # Price<br><br>
173
+ # The metadata identifies the <code>value</code> and <code>currency</code>.
144
174
  PRICE = 13
145
175
  end
146
176
  end
@@ -781,9 +811,9 @@ module Google
781
811
  # @!attribute [rw] sentiment
782
812
  # @return [Google::Cloud::Language::V1::Sentiment]
783
813
  # For calls to {AnalyzeEntitySentiment} or if
784
- # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment}
785
- # is set to true, this field will contain the sentiment expressed for this
786
- # mention of the entity in the provided document.
814
+ # {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
815
+ # true, this field will contain the sentiment expressed for this mention of
816
+ # the entity in the provided document.
787
817
  class EntityMention
788
818
  # The supported types of mentions.
789
819
  module Type
@@ -805,9 +835,7 @@ module Google
805
835
  # @!attribute [rw] begin_offset
806
836
  # @return [Integer]
807
837
  # The API calculates the beginning offset of the content in the original
808
- # document according to the
809
- # {Google::Cloud::Language::V1::EncodingType EncodingType} specified in the API
810
- # request.
838
+ # document according to the {Google::Cloud::Language::V1::EncodingType EncodingType} specified in the API request.
811
839
  class TextSpan; end
812
840
 
813
841
  # Represents a category returned from the text classifier.
@@ -838,8 +866,7 @@ module Google
838
866
  # @return [String]
839
867
  # The language of the text, which will be the same as the language specified
840
868
  # in the request or, if not specified, the automatically-detected language.
841
- # See {Google::Cloud::Language::V1::Document#language Document#language} field
842
- # for more details.
869
+ # See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
843
870
  # @!attribute [rw] sentences
844
871
  # @return [Array<Google::Cloud::Language::V1::Sentence>]
845
872
  # The sentiment for all the sentences in the document.
@@ -862,8 +889,7 @@ module Google
862
889
  # @return [String]
863
890
  # The language of the text, which will be the same as the language specified
864
891
  # in the request or, if not specified, the automatically-detected language.
865
- # See {Google::Cloud::Language::V1::Document#language Document#language} field
866
- # for more details.
892
+ # See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
867
893
  class AnalyzeEntitySentimentResponse; end
868
894
 
869
895
  # The entity analysis request message.
@@ -883,8 +909,7 @@ module Google
883
909
  # @return [String]
884
910
  # The language of the text, which will be the same as the language specified
885
911
  # in the request or, if not specified, the automatically-detected language.
886
- # See {Google::Cloud::Language::V1::Document#language Document#language} field
887
- # for more details.
912
+ # See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
888
913
  class AnalyzeEntitiesResponse; end
889
914
 
890
915
  # The syntax analysis request message.
@@ -907,8 +932,7 @@ module Google
907
932
  # @return [String]
908
933
  # The language of the text, which will be the same as the language specified
909
934
  # in the request or, if not specified, the automatically-detected language.
910
- # See {Google::Cloud::Language::V1::Document#language Document#language} field
911
- # for more details.
935
+ # See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
912
936
  class AnalyzeSyntaxResponse; end
913
937
 
914
938
  # The document classification request message.
@@ -978,8 +1002,7 @@ module Google
978
1002
  # @return [String]
979
1003
  # The language of the text, which will be the same as the language specified
980
1004
  # in the request or, if not specified, the automatically-detected language.
981
- # See {Google::Cloud::Language::V1::Document#language Document#language} field
982
- # for more details.
1005
+ # See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
983
1006
  # @!attribute [rw] categories
984
1007
  # @return [Array<Google::Cloud::Language::V1::ClassificationCategory>]
985
1008
  # Categories identified in the input document.
@@ -274,10 +274,8 @@ module Google
274
274
  @analyze_entities.call(req, options, &block)
275
275
  end
276
276
 
277
- # Finds entities, similar to
278
- # {Google::Cloud::Language::V1::LanguageService::AnalyzeEntities AnalyzeEntities}
279
- # in the text and analyzes sentiment associated with each entity and its
280
- # mentions.
277
+ # Finds entities, similar to {Google::Cloud::Language::V1::LanguageService::AnalyzeEntities AnalyzeEntities} in the text and analyzes
278
+ # sentiment associated with each entity and its mentions.
281
279
  #
282
280
  # @param document [Google::Cloud::Language::V1::Document | Hash]
283
281
  # Input document.
@@ -5,6 +5,8 @@
5
5
  require 'google/protobuf'
6
6
 
7
7
  require 'google/api/annotations_pb'
8
+ require 'google/api/client_pb'
9
+ require 'google/api/field_behavior_pb'
8
10
  Google::Protobuf::DescriptorPool.generated_pool.build do
9
11
  add_message "google.cloud.language.v1.Document" do
10
12
  optional :type, :enum, 1, "google.cloud.language.v1.Document.Type"
@@ -42,10 +42,8 @@ module Google
42
42
  # along with entity types, salience, mentions for each entity, and
43
43
  # other properties.
44
44
  rpc :AnalyzeEntities, AnalyzeEntitiesRequest, AnalyzeEntitiesResponse
45
- # Finds entities, similar to
46
- # [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities]
47
- # in the text and analyzes sentiment associated with each entity and its
48
- # mentions.
45
+ # Finds entities, similar to [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities] in the text and analyzes
46
+ # sentiment associated with each entity and its mentions.
49
47
  rpc :AnalyzeEntitySentiment, AnalyzeEntitySentimentRequest, AnalyzeEntitySentimentResponse
50
48
  # Analyzes the syntax of the text and provides sentence boundaries and
51
49
  # tokenization along with part of speech tags, dependency trees, and other
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: google-cloud-language
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.32.0
4
+ version: 0.32.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Google LLC
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2019-03-28 00:00:00.000000000 Z
11
+ date: 2019-04-30 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: google-gax
@@ -24,6 +24,26 @@ dependencies:
24
24
  - - "~>"
25
25
  - !ruby/object:Gem::Version
26
26
  version: '1.3'
27
+ - !ruby/object:Gem::Dependency
28
+ name: googleapis-common-protos
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: 1.3.9
34
+ - - "<"
35
+ - !ruby/object:Gem::Version
36
+ version: '2.0'
37
+ type: :runtime
38
+ prerelease: false
39
+ version_requirements: !ruby/object:Gem::Requirement
40
+ requirements:
41
+ - - ">="
42
+ - !ruby/object:Gem::Version
43
+ version: 1.3.9
44
+ - - "<"
45
+ - !ruby/object:Gem::Version
46
+ version: '2.0'
27
47
  - !ruby/object:Gem::Dependency
28
48
  name: minitest
29
49
  requirement: !ruby/object:Gem::Requirement
@@ -102,6 +122,7 @@ extensions: []
102
122
  extra_rdoc_files: []
103
123
  files:
104
124
  - ".yardopts"
125
+ - AUTHENTICATION.md
105
126
  - LICENSE
106
127
  - README.md
107
128
  - lib/google/cloud/language.rb