google-cloud-vision 0.32.2 → 0.32.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52dd46891e2dd5c9808632ba5b9ac31a1365170bea2da85e742a6bcc7d93aa17
-  data.tar.gz: e1ef13baff8bb0c1d9f7b6fd501300906ef366c829fc213acdd8e735fb6b4751
+  metadata.gz: e3e9260f0687fddb06b98ef2fe53379c06b0a3698c0c9f822c058371a63883a0
+  data.tar.gz: 22eb45350bd0589357f5d60f6282733f6acd844b56d683da727d4b4d4fc138c0
 SHA512:
-  metadata.gz: 1130a631b6b852c00ae75cac33d59a713e122e6ebd14acbbb551a7039b4da5c50fe80bafdf30e39a28f93536a25729d0f0507d60bbe526b6063c8a51c0396e9f
-  data.tar.gz: 12164c275468ab3331493a60ce1fb65d3748c3c541035c4d0f0b63563caa1623f9e3d76fc93211e13341b3b3a6faf0a82ff89f09f19fcbf0d9c326cac762e9ca
+  metadata.gz: 62cd25a84e43db4b7fa3faa122400fd1d22f4e8782562cae2950c3e75dcaae73bd6f604259364cfe58d57a7f81ca317fe4434059fad89eaf384ee5777fcd1dd4
+  data.tar.gz: 8f8318a452e72f504726e4e7b1c9cf5fb41f98a2f582e89f32c65c5371117cd97b87a2de0e38d48c8ac214ea6e8a778ceba75415ac06598e6a8e0e471cc4197d

data/.yardopts

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

data/AUTHENTICATION.md

@@ -0,0 +1,199 @@
+# Authentication
+
+In general, the google-cloud-vision 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 VISION_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/vision"
+
+client = Google::Cloud::Vision.new
+```
+
+## Project and Credential Lookup
+
+The google-cloud-vision 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-vision checks for project ID are:
+
+1. `VISION_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that google-cloud-vision checks for credentials are configured on {Google::Cloud::Vision::V1::Credentials}:
+
+1. `VISION_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `VISION_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/vision"
+
+ENV["VISION_PROJECT"]     = "my-project-id"
+ENV["VISION_CREDENTIALS"] = "path/to/keyfile.json"
+
+client = Google::Cloud::Vision.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/vision"
+
+Google::Cloud::Vision.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+client = Google::Cloud::Vision.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-vision.
+
+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/vision.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -117,16 +117,18 @@ module Google
         # Manages Products and ProductSets of reference images for use in product
         # search. It uses the following resource model:
         #
-        # * The API has a collection of {Google::Cloud::Vision::V1::ProductSet ProductSet} resources, named
-        #   `projects/*/locations/*/productSets/*`, which acts as a way to put different
-        #   products into groups to limit identification.
+        # * The API has a collection of {Google::Cloud::Vision::V1::ProductSet ProductSet}
+        #   resources, named `projects/*/locations/*/productSets/*`, which acts as a way
+        #   to put different products into groups to limit identification.
         #
         # In parallel,
         #
-        # * The API has a collection of {Google::Cloud::Vision::V1::Product Product} resources, named
+        # * The API has a collection of {Google::Cloud::Vision::V1::Product Product}
+        #   resources, named
         #   `projects/*/locations/*/products/*`
         #
-        # * Each {Google::Cloud::Vision::V1::Product Product} has a collection of {Google::Cloud::Vision::V1::ReferenceImage ReferenceImage} resources, named
+        # * Each {Google::Cloud::Vision::V1::Product Product} has a collection of
+        #   {Google::Cloud::Vision::V1::ReferenceImage ReferenceImage} resources, named
         #   `projects/*/locations/*/products/*/referenceImages/*`
         #
         # @param version [Symbol, String]

data/lib/google/cloud/vision/v1.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -106,16 +106,18 @@ module Google
           # Manages Products and ProductSets of reference images for use in product
           # search. It uses the following resource model:
           #
-          # * The API has a collection of {Google::Cloud::Vision::V1::ProductSet ProductSet} resources, named
-          #   `projects/*/locations/*/productSets/*`, which acts as a way to put different
-          #   products into groups to limit identification.
+          # * The API has a collection of {Google::Cloud::Vision::V1::ProductSet ProductSet}
+          #   resources, named `projects/*/locations/*/productSets/*`, which acts as a way
+          #   to put different products into groups to limit identification.
           #
           # In parallel,
           #
-          # * The API has a collection of {Google::Cloud::Vision::V1::Product Product} resources, named
+          # * The API has a collection of {Google::Cloud::Vision::V1::Product Product}
+          #   resources, named
           #   `projects/*/locations/*/products/*`
           #
-          # * Each {Google::Cloud::Vision::V1::Product Product} has a collection of {Google::Cloud::Vision::V1::ReferenceImage ReferenceImage} resources, named
+          # * Each {Google::Cloud::Vision::V1::Product Product} has a collection of
+          #   {Google::Cloud::Vision::V1::ReferenceImage ReferenceImage} resources, named
           #   `projects/*/locations/*/products/*/referenceImages/*`
           #
           # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]

data/lib/google/cloud/vision/v1/credentials.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/geometry.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/image_annotator.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/product_search.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,7 +24,8 @@ module Google
         #     Optional. If it is not specified, system discretion will be applied.
         # @!attribute [rw] product_set
         #   @return [String]
-        #     The resource name of a {Google::Cloud::Vision::V1::ProductSet ProductSet} to be searched for similar images.
+        #     The resource name of a {Google::Cloud::Vision::V1::ProductSet ProductSet} to
+        #     be searched for similar images.
         #
         #     Format is:
         #     `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`.

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/product_search_service.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -423,15 +423,17 @@ module Google
         #     `product-display-name` column refers to
         #     {Google::Cloud::Vision::V1::Product#display_name display_name}, the
         #     `product-category` column refers to
-        #     {Google::Cloud::Vision::V1::Product#product_category product_category}, and the
-        #     `labels` column refers to {Google::Cloud::Vision::V1::Product#product_labels product_labels}.
+        #     {Google::Cloud::Vision::V1::Product#product_category product_category}, and
+        #     the `labels` column refers to
+        #     {Google::Cloud::Vision::V1::Product#product_labels product_labels}.
         #
         #     The `image-id` column is optional but must be unique if provided. If it is
         #     empty, the system will automatically assign a unique id to the image.
         #
         #     The `product-display-name` column is optional. If it is empty, the system
-        #     sets the {Google::Cloud::Vision::V1::Product#display_name display_name} field for the product to a
-        #     space (" "). You can update the `display_name` later by using the API.
+        #     sets the {Google::Cloud::Vision::V1::Product#display_name display_name} field
+        #     for the product to a space (" "). You can update the `display_name` later
+        #     by using the API.
         #
         #     If a `Product` with the specified `product-id` already exists, then the
         #     system ignores the `product-display-name`, `product-category`, and `labels`
@@ -482,8 +484,10 @@ module Google
         # Response message for the `ImportProductSets` method.
         #
         # This message is returned by the
-        # {Google::Longrunning::Operations::GetOperation} method in the returned
-        # {Google::Longrunning::Operation#response} field.
+        # {Google::Longrunning::Operations::GetOperation}
+        # method in the returned
+        # {Google::Longrunning::Operation#response}
+        # field.
         # @!attribute [rw] reference_images
         #   @return [Array<Google::Cloud::Vision::V1::ReferenceImage>]
         #     The list of reference_images that are imported successfully.
@@ -510,7 +514,8 @@ module Google
         # @!attribute [rw] end_time
         #   @return [Google::Protobuf::Timestamp]
         #     The time when the batch request is finished and
-        #     {Google::Longrunning::Operation#done} is set to true.
+        #     {Google::Longrunning::Operation#done} is
+        #     set to true.
         class BatchOperationMetadata
           # Enumerates the possible states that the batch request can be in.
           module State

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/text_annotation.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,8 +22,9 @@ module Google
         #     TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol
         # Each structural component, starting from Page, may further have their own
         # properties. Properties describe detected languages, breaks etc.. Please refer
-        # to the {Google::Cloud::Vision::V1::TextAnnotation::TextProperty TextAnnotation::TextProperty} message definition below for more
-        # detail.
+        # to the
+        # {Google::Cloud::Vision::V1::TextAnnotation::TextProperty TextAnnotation::TextProperty}
+        # message definition below for more detail.
         # @!attribute [rw] pages
         #   @return [Array<Google::Cloud::Vision::V1::Page>]
         #     List of pages detected by OCR.

data/lib/google/cloud/vision/v1/doc/google/cloud/vision/v1/web_detection.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/vision/v1/doc/google/longrunning/operations.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -31,7 +31,7 @@ module Google
     # @!attribute [rw] done
     #   @return [true, false]
     #     If the value is `false`, it means the operation is still in progress.
-    #     If true, the operation is completed, and either `error` or `response` is
+    #     If `true`, the operation is completed, and either `error` or `response` is
     #     available.
     # @!attribute [rw] error
     #   @return [Google::Rpc::Status]
@@ -47,47 +47,5 @@ module Google
     #     is `TakeSnapshot()`, the inferred response type is
     #     `TakeSnapshotResponse`.
     class Operation; end
-
-    # The request message for {Google::Longrunning::Operations::GetOperation Operations::GetOperation}.
-    # @!attribute [rw] name
-    #   @return [String]
-    #     The name of the operation resource.
-    class GetOperationRequest; end
-
-    # The request message for {Google::Longrunning::Operations::ListOperations Operations::ListOperations}.
-    # @!attribute [rw] name
-    #   @return [String]
-    #     The name of the operation collection.
-    # @!attribute [rw] filter
-    #   @return [String]
-    #     The standard list filter.
-    # @!attribute [rw] page_size
-    #   @return [Integer]
-    #     The standard list page size.
-    # @!attribute [rw] page_token
-    #   @return [String]
-    #     The standard list page token.
-    class ListOperationsRequest; end
-
-    # The response message for {Google::Longrunning::Operations::ListOperations Operations::ListOperations}.
-    # @!attribute [rw] operations
-    #   @return [Array<Google::Longrunning::Operation>]
-    #     A list of operations that matches the specified filter in the request.
-    # @!attribute [rw] next_page_token
-    #   @return [String]
-    #     The standard List next-page token.
-    class ListOperationsResponse; end
-
-    # The request message for {Google::Longrunning::Operations::CancelOperation Operations::CancelOperation}.
-    # @!attribute [rw] name
-    #   @return [String]
-    #     The name of the operation resource to be cancelled.
-    class CancelOperationRequest; end
-
-    # The request message for {Google::Longrunning::Operations::DeleteOperation Operations::DeleteOperation}.
-    # @!attribute [rw] name
-    #   @return [String]
-    #     The name of the operation resource to be deleted.
-    class DeleteOperationRequest; end
   end
 end