AUTHENTICATION.md in google-cloud-language-0.36.0 vs AUTHENTICATION.md in google-cloud-language-1.0.0

- old
+ new

@@ -1,51 +1,43 @@ # 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 +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. +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` +export LANGUAGE_CREDENTIALS=path/to/keyfile.json ``` 3. Initialize the client. ```ruby require "google/cloud/language" -client = Google::Cloud::Language.new +client = Google::Cloud::Language.language_service ``` -## Project and Credential Lookup +## 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. +without requiring **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 GCP 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 @@ -53,61 +45,66 @@ 5. Discover credentials file in the Cloud SDK's path 6. Discover GCP credentials ### Google Cloud Platform environments -When running on Google Cloud Platform (GCP), including Google Compute Engine (GCE), -Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud Functions -(GCF) and Cloud Run, the **Project ID** and **Credentials** and are discovered -automatically. Code should be written as if already authenticated. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. +Code should be written as if already authenticated. ### 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 **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: +The environment variables that google-cloud-language +checks for credentials are configured on the service Credentials class (such as +`Google::Cloud::Language::V1::LanguageService::Credentials`): -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 +client = Google::Cloud::Language.language_service ``` ### Configuration -The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments. +The **Credentials JSON** can be configured instead of placing them in +environment variables. Either on an individual client initialization: ```ruby require "google/cloud/language" +client = Google::Cloud::Language.language_service do |config| + config.credentials = "path/to/keyfile.json" +end +``` + +Or configured globally for all clients: + +```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 +client = Google::Cloud::Language.language_service ``` ### Cloud SDK This option allows for an easy way to authenticate during development. If @@ -132,28 +129,28 @@ [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 +Google Cloud requires **Service Account Credentials** to +connect to the APIs. You will use the **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. +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 +2. Create a new project or click on an existing project. +3. 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. +4. 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] @@ -168,10 +165,5 @@ ![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}.