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/.
You should be familiar with the following technologies:
The following items are required or recommended, especially if you create and troubleshoot your own Swagger definitions.
There are three main steps to configuring the integration between K2 and Microsoft 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.
For the purposes of this article, the scenario is limited to a single region and API key.
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.
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.
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:
An ID in the Swagger definition called operationId represents these unique actions across the service.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.