Integrating K2 with Google Cloud Natural Language and Translation
KB003357
PRODUCT
Introduction
You can use Google Cloud AI services in conjunction with the K2 REST Service Type to integrate K2 with Google Cloud Natural Language and Translation Services. Once you have integrated K2 with these Google services, you can perform actions such translating content between languages, or detecting the language content is written in. This article describes how to enable Google Cloud AI Building Blocks Natural Language and Translation APIs for use in your K2 solutions, covering authentication to configuration, and is intended for use by K2 and Google Cloud Platform (GCP) administrators that need to enable Google Cloud AI Building Blocks for use in the K2 platform.
For more information on working with Google Cloud AI Building Blocks, please refer to the Cloud AI building blocks documentation.
It is highly recommended that you are familiar with the OpenAPI specification, as it is the basis of K2’s REST integration. For more information on working with the REST Service Broker and Swagger, please see the knowledge base article KB001786: Resources for Working with the REST Service Broker
Getting Started
Before you begin, you will need the following:
- K2 Administrative account for access to the K2 Management site
- Google Cloud Platform (GCP) Account
- Google account with administrative rights to a GCP Project
- Google Cloud Natural Language and Translation APIs enabled in the GCP project
Authentication
To use Cloud AI Building Blocks with K2, you will need a way to authenticate your requests with GCP. K2 supports two methods for authenticating with the Google Cloud Platform Natural Language and Translation APIs: API Key and OAuth.
Authenticating with an API Key
One method for authenticating with GCP is via an API key. This key can be obtained from the GCP console by an administrator. For more information on authenticating, please see Using API Keys in the Google Cloud Documentation.
Obtaining an API Key
For the purposes of this article, we will be focusing on a single region and a single service API key.
- Log into your Google Cloud Platform project https://console.cloud.google.com
- Navigate to the APIs & Services > Credentials panel in GCP Console.
- Select Create credentials, then select API key from the dropdown menu.
- Click the Create button. The API key created dialog box displays your newly-created key. Copy the API Key displayed in the API key created window and keep in a safe location, because you will need it later when using the APIs in your K2 solutions to authenticate your requests to GCP.
To make re-using the key easier, create a K2 environment field to store this key for reuse. Alternatively, create a SmartBox SmartObject to store configuration values such as these, and use SmartObject method chaining in an advanced SmartObject to retrieve the value from your SmartBox SmartObject that stores the configuration information.
If you use the API Key method for authentication, it is recommended that your select Restrict Key during the API key creation to restrict this key to specific APIs that you will be using. This will limit how much access the API key has to your GCP account. You can restrict API keys to specific APIs such as Vision, Video, Translation, etc
Authenticating with OAuth
For most use cases, authenticating with API key as described above should be sufficient. Also note that using the API key approach is currently the only method supported when SmartObject calls are made from a K2 workflow, when using a K2 Cloud environment. If you need to set up OAuth authentication, use the K2 Management site to configure the necessary OAuth resources as described in the tables below.
For more information on OAuth and Google APIs, please refer to the Google article Using OAuth 2.0 to Access Google APIs
OAuth Authentication Endpoints
- Authorization: https://accounts.google.com/o/oauth2/v2/auth
- Token: https://www.googleapis.com/oauth2/v4/token
- Refresh: https://www.googleapis.com/oauth2/v4/token
OAuth Resource Parameters Default Values
| Parameter Name | URL Encode | Auth Default Value | Token Default Value | Refresh Default Value |
| client_secret | Yes | |||
| redirect_uri | Yes | |||
| grant_type | Yes | authorization_code | refresh_token | |
| response_type | Yes | code | ||
| scope | Yes | For Cloud Natural Language: | ||
| client_id | Yes | (Obtain this value from the Google Cloud Console.) | ||
| access_type | Yes | offline |
OAuth Resource Parameters Usage
| Parameter Name | Auth Req | Auth Resp | Token Req | Token Resp | Refresh Req |
| client_secret | Yes | Yes | |||
| redirect_uri | Yes | Yes | Yes | ||
| grant_type | Yes | Yes | |||
| response_type | Yes | ||||
| scope | Yes | ||||
| client_id | Yes | Yes | Yes |
Configuring the REST Service Instance for Cloud AI Building Blocks
It is highly recommended that you are familiar with the OpenAPI specification, as it is the basis of K2’s REST integration. For more information on working with the REST Service Broker and Swagger, please see the knowledge base article Resources for Working with the REST Service Broker for additional information. For more detail on configuring the REST Broker, please see the REST Service Type topic in the K2 User Guide.
Once you have configured the OAuth settings, you can create a Service Instance of the REST Service Type and configure it with the provided descriptor files listed below. Once the Service Instance is registered, you can create SmartObjects to expose the appropriate service methods in your K2 applications.
When configuring the REST Service Broker instance, you must provide a URL to the location for a Swagger descriptor file for the service. K2 provides two swagger definitions for use with the Google Cloud service (Natural Language and Translation), and two versions of the descriptor file: one set to use if you are using the API Key authentication mechanism, and one set to use if you are using OAuth authentication. The only difference between the files is that the first set exposes an extra field to allow you to pass an API key with your request to the API.
- For API Key Authentication:
- For OAuth Authentication:
When configuring the Service Instance, copy the appropriate URL above and paste it into the Descriptor Location configuration field:
If you are using the OAuth method for authentication, you will need to select OAuth and the resource you configured in the previous section as your authentication mode. If using the API Key method of authentication, leave the security method set to the default (Impersonate).
Once the Authentication Mode and Descriptor Location fields are set, click OK and complete the registration process.
Next Steps
After registering your Service Instance(s) of the REST service type that point to the Cloud AI Building Blocks API endpoint(s) you want to expose, create advanced SmartObjects to allow your K2 applications to interact with the Google Cloud APIs.
