Use this article to enable integration between K2 and Microsoft Cognitive Services for use in your solutions. You will understand the authentication requirements and the necessary configuration to enable this integration. Once you have enabled the integration between K2 and Cognitive Services, you can create SmartObjects that will allow you to call Cognitive Services methods in your K2 applications.

This article in intended for K2 and Azure administrators that need to enable Microsoft Cognitive Services integration in K2, and assumes that you are familiar with Microsoft's Cognitive Services offering. You can learn more about Cognitive Services at https://azure.microsoft.com/en-us/services/cognitive-services/.

The screenshots and instructions for third-party software are accurate at the time of publication. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.

Prerequisites

You should be familiar with the following technologies:

  • OpenAPI (previously known as Swagger) forms the basis of how you configure the REST service broker instance, which serves as the connection between K2 and Microsoft Cognitive Services.
  • Microsoft Azure, including access with a permanent or trial account.
  • The K2 REST Service Type.

Getting Started

The following items are required or recommended, especially if you create and troubleshoot your own Swagger definitions.

Required

  • A K2 Administrative account for accessing the K2 Management site
  • An Azure subscription and administrative account for accessing the Azure portal

Recommended

  • A Rest United account. This site allows you to create OpenAPI files from example service responses.
  • Postman, a tool for testing and troubleshooting REST services.
  • Fiddler, a tool for tracing network traffic.

Table of Contents

There are three main steps to configuring the integration between K2 and Microsoft Cognitive Services.

  1. Authenticating with Cognitive Services using an API key
  2. Getting an OpenAPI (Swagger) definition
  3. Configuring the REST service instance or instances

Authenticating with Cognitive Services

To use Cognitive Services with K2, you need a way to authenticate your requests with Azure services. The most common way this is accomplished is by using an API key. You can, as an Azure administrator, get a key using the Azure portal. For more information see Authenticate requests to Azure Cognitive Services. You use this key in the HTTP header request value when configuring your REST service instance, which is detailed in the Configuring the REST Service Broker for Cognitive Services section below.

Getting an API Key

For the purposes of this article, the scenario is limited to a single region and API key.

  1. Log into your Azure portal at https://portal.azure.com
  2. Select Create a resource in the left navigation panel. On the New panel, search for “Cognitive Services” and press Enter.
    Image
  3. Once found, click the Create button at the bottom of the Cognitive Services panel and fill out the required information. When the resource has completed deployment, go to the new resource and click Keys from the navigation panel to get a subscription key required for the API calls.

Getting an OpenAPI (Swagger) definition

Before you can configure a REST service instance, you need a Swagger definition file for the endpoints with which you want to integrate. There are two options for doing getting this file: using the provided Swagger definition, or creating your own Swagger definition.

Option 1: Use the provided Swagger definition

Each API endpoint for Cognitive Services has its own Swagger definition which you can download from each API documentation page. Click API Definition in the upper right corner of the page.

Image

Updating the Swagger for usability

Some of the Microsoft Cognitive Services APIs use unique identifiers in the Swagger definition to name the actions in the API. These IDs are difficult to read in the REST service broker as illustrated here:

Image

An ID in the Swagger definition called operationId represents these unique actions across the service.

Image

In order to make the API more readable in the REST service broker, copy the Swagger definition to edit your own copy in a tool such as Notepad++. Copy the value in the summary field value and replace the value of the operationId field, as illustrated here for the Analyze Image action.

Image

Save your updated Swagger file to a location accessible by your instance of K2. This can be a local file location if you’re running K2 Five or a cloud storage service (such as Azure Blob Storage or Google Firebase) that allows anonymous access for K2 Cloud customers. Use this location when you register a new instance of the REST service broker and your methods show up in a more readable way.

Image

Option 2: Create your own Swagger definition

Another option is to create your own Swagger definition for the Cognitive Service with which you are integrating. This has some benefits over using the downloadable Swagger file as you have the flexibility to address some of the usability issues in that definition.

For some endpoints, this approach is necessary as the provided Swagger does not expose all necessary information required by the REST service broker due to the dynamic nature of the endpoint. For example, some of the operations of the Computer Vision endpoint do not have a defined return value in the definition because the type of data returned is dependent on the query string parameters you use when making the call. In these cases, you must determine what information is needed from the endpoint and create your Swagger definition that meets your use cases.

Additionally, custom Swagger definitions allow you to focus the endpoint's methods and objects to only what you need for your solutions.

You can use tools like REST United to generate Swagger files. For detailed information on using this online resource, see Generating a Swagger Descriptor for REST-based Services using RESTUnited.com.

Use Postman and Fiddler to test, troubleshoot, and trace communications between K2 and Microsoft Cognitive Services.

Hosting the Swagger definition

If you decide to customize the provided Swagger or generate your own, you must place to definition file in a location that can be accessed anonymously from your K2 Cloud tenant, such as Azure Blob Storage or Google Firebase. Use these URLs of the definition files when creating instances of the REST service broker for each endpoint. For K2 Five customers, you can either host them anonymously or use a local path on your K2 server.

Configuring the REST Service Broker for Cognitive Services

Once you have a URL (or the Swagger file locally if you’re running K2 Five), configure the REST service broker instance and generate SmartObjects that you can use in your K2 solutions. For detailed information about the REST service broker, see REST in the K2 Cloud User Guide or REST in the K2 Five User Guide.

Configuring Authentication

The calls to Cognitive Services endpoints are authorized by including your subscription key in the request header of calls made to the API. To include this key, you must provide a value in the Default HTTP Request Headers field in the configuration of your REST service instance. This adds the API key to every request of the service instance.

Image

An example value of a request header is shown here. Replace the placeholder value your API Key Here with your key from the Azure portal. You can serialize a new header using the HttpHeader object’s Serialize method as well.

{"$type":"SourceCode.SmartObjects.Services.Endpoints.Common.HttpHeader[], SourceCode.SmartObjects.Services.Endpoints.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"SourceCode.SmartObjects.Services.Endpoints.Common.HttpHeader, SourceCode.SmartObjects.Services.Endpoints.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=null","Name":"Ocp-Apim-Subscription-Key","Value":"your API Key Here"}]}

Providing the Descriptor Location

You must also provide the URL of the Swagger descriptor location (or local path if you’re running K2 Five) when creating the service instance. In this example, the Swagger definition is called ModerationSwagger.json and is saved in a Firebase storage location.

Image

Once you provide values for the Default HTTP Request Headers and Descriptor Location, click OK. Create a service instance for each Swagger file you have.

Once you have your service instances created, you can design or generate SmartObjects for each instance. Calling methods of these SmartObjects is how you enable the integration between K2 and Microsoft Cognitive Services in your solutions. For more information about SmartObjects, see About SmartObjects.