Provide functionality for Azure Application Insights

[paul-warwick-cdt]

**This PR feature will be submitted to supply a generic Helper provider for tests that access Azure query or run instructions through an API. The example will be Application Insights

Describe the solution you'd like
This solution will be an enhancement to the Invictus Testing Framework
This solution will provide base access to tests through https://management.azure.com
This solution will provide base access to tests through https://api.loganalytics.io
This solution will provide base access to tests through https://api.applicationinsights.io

Describe alternatives you've considered
This solution provides the reliable API experience for testing with c# providers where c# base classes are missing or complex.

Additional context
This feature will provide example narrative for tests on Application Insights on https://api.applicationinsights.io
the contexts to be covered will be:
Authentication, Controlling a single Run, Retrieving runs by Polling

[paul-warwick-cdt]

Edit Tom: Replaced doc with Markdown

Authenticating to Azure resource API

Before you can start using the Azure resource API testing features, you need to authenticate with Microsoft Azure.
As of today, we provide the following authentication scenarios:
• Using Service Principal

Using a Service Principal

Before we can authenticate, you'll need to create an Azure AD application which will be used as your service principle.
The service principal will need to have one of the following permissions:
[A] Contributor access on the Resource Group [https://management.azure.com]
[B] Log Analytics API read access [https://api.loganalytics.io]
Or
[C] A specific security header key and an authentication context [example below]

depending on the API context, on your Azure instances that you want to test.

When using a service principal, you need to provide the following information:
• Tenant Id - Identifier of the Azure AD directory
• Subscription Id - Identifier of the Azure subscription that contains your Azure Logic App
• Client Id - Identifier of the service principal in Azure AD. In this case, it is the application id of the Azure AD app.
• Client Secret - Secret of the service principal in Azure AD to authenticate with.

Some API contexts also benefit from specifically supplying
• authorisationResource – The root context of the service (example below)
• authorisationUri – The specific context of your login (example below)

Here is an example for scenario [A]: (e.g. standard resource manager API)

string tenantId = "my-tenant-id";
string subscriptionId = "my-subscription-id";
string clientId = "my-client-id";
string clientSecret = "my-client-secret";

var authentication = ResourceApiAuthentication.UsingServicePrincipal(tenantId, subscriptionId, clientId, clientSecret);

// For the Resource API provider
var provider = ResourceApiProvider.LocatedAt("AzureDataFactory", authentication);

Here is an example for scenario [B]: (e.g. Operational Insights)

string tenantId = "my-tenant-id";
string subscriptionId = "my-subscription-id";
string clientId = "my-client-id";
string clientSecret = "my-client-secret";
string resourceGroup = "my-resource-group";
string authorisationResource = "https://api.loganalytics.io";
string authorisationUri = " https://login.microsoftonline.com/<my-tenant-id>";

var authentication = ResourceApiAuthentication.UsingServicePrincipal(tenantId, subscriptionId, clientId, clientSecret, authorisationResource, authorisationUri);

// For the Resource API provider
var provider = ResourceApiProvider.LocatedAt("OperationalInsights", authentication);

Here is an example for scenario [C]: (where token is collected but where a direct header authentication replaces the bearer token in the header of the request e.g. Application Insights)

string tenantId = "my-tenant-id";
string subscriptionId = "my-subscription-id";
string clientId = "my-client-id";
string clientSecret = "my-client-secret";
string resourceGroup = "my-resource-group";
string appInsightsKey = "my-application-insights-key";


var authentication = ResourceApiAuthentication.UsingServicePrincipal(tenantId, subscriptionId, clientId, clientSecret);

// For the Resource API provider
var provider = ResourceApiProvider.LocatedAt("ApplicationInsights", authentication);

var headers = new Dictionary<string, string>();
headers.Add("x-api-key", appInsightsKey);

provider.WithHeaderValues(headers);
provider.WithNoBearerTokenAuthentication(true);

Control a single API run

The Invictus.Testing.ResourceApi library provides a way to control API run and query execution during integration testing.

Installation

The features described here requires the following package:

Install-Package Invictus.Testing.ResourceApi

Features

All the following features uses the ResourceApiProvider which can be created using an ResourceApiAuthentication authentication.

Run API command

This library allows you to execute a request and receive a string based response...

var provider = ResourceApiProvider.LocatedAt("RunnableAPIRequest", authentication);

provider.WithBaseUrlPattern(apiBaseUrl);
provider.WithBaseUrlValues(apiBaseValues);
provider.WithUrlAction(apiRunAction);

var postTask = provider.RunAsync();

await Task.WhenAll(postTask);

Retrieving runs by Polling

Poll for API Query response

This library allows you to Poll For Responses and will receive a collection of objects

This example will take the first response

var provider = ResourceApiProvider.LocatedAt("ApplicationInsights", authentication);

provider.WithBaseUrlPattern(aiApiBaseUrl);
provider.WithBaseUrlValues(aiBaseValues);
provider.WithUrlAction(aiActionQuery);
provider.WithUrlActionValues(aiActionValues);
provider.WithUrlActionQueryValues(aiParameterValues);
provider.WithHeaderValues(aiHeaders);
provider.WithTimeout(aiTimeOut);
provider.WithNoBearerTokenAuthentication(true);

var requestTask = provider.PollForResponsesAsync();

await Task.WhenAll(requestTask);

var queryObject = requestTask.Result.FirstOrDefault();

This example will poll for a specific minimum number of responses

var provider = ResourceApiProvider.LocatedAt("ApplicationInsights", authentication);

provider.WithBaseUrlPattern(aiApiBaseUrl);
…

var requestTask = provider.PollForResponsesAsync(aiReturnCount);

await Task.WhenAll(requestTask);

var queryObject = requestTask.Result.FirstOrDefault();

Structured API support

All the Azure APIs supported by this library have common attributes supported in the library in the following ways

Root URL

The root pattern for the API is defined as a “replacement string”, example:

https://api.applicationinsights.io/{0}/apps/{1}
against which a user configurable number of “replacement values” can be supplied, example:

provider.WithBaseUrlPattern(apiBaseUrl);

var apiBaseValues = new Dictionary<string, string>();
apiBaseValues.Add("{0}", settingVersion);
apiBaseValues.Add("{1}", settingAppInsightsId);


provider.WithBaseUrlValues(apiBaseValues);

URL Action

The action pattern can also support string replacement, example: "/{0}-{1}"

WithUrlAction => WithUrlActionValues

URL Action Filters

The Url Action pattern can also support string replacement, example: "{0}={1}"

WithUrlFilter => WithUrlFilterValues

Header Values

Key Value Pairs are also used to manage any combination of values that would typically be handled by httpClient.DefaultRequestHeaders.

var headers = new Dictionary<string, string>();
headers.Add(_aiInsightsHeaderKey, settingAppInsightsKey);

provider.WithHeaderValues(headers);

Body Filters

Many Azure APIs use the content body of the request to either deliver the query or apply additional filtering. This test Library again uses the replacement model to support dynamic testing as per example:

oBodyQuery ="{{\"lastUpdatedAfter\": \"{0}\", \"lastUpdatedBefore\": \"{1}\", \"filters\": [{{\"operand\": \"PipelineName\", \"operator\": \"Equals\", \"values\": [\"{2}\"]}},{{\"operand\": \"RunStart\", \"operator\": \"GreaterThan\", \"values\": [\"{3}\"]}}]}}"
var oBodyValues = new Dictionary<string, string>();
oBodyValues.Add("{0}", ("{0}", settingRunStart);
oBodyValues.Add("{1}", settingLastUpdatedBefore);
oBodyValues.Add("{2}", settingPipelineName);
oBodyValues.Add("{3}", settingRunStart);

provider.WithBodyFilter(oBodyQuery);
provider.WithBodyFilterValues(oBodyValues);

[tomkerkhove]

I think we should hold off the PR until we come to an agreement on the specs here because the current approach is not really inline with our current approach.

Things that I would encourage to change:

• Remove the new authentication and refactor to the current one which we'll rename to AzureAuthentication(?)
• ResourceApiProvider is not really clear and instead we try to provide providers per service, for example ApplicationInsightsProvider

So putting it together, it would look similar to this:

var authentication = AzureAuthentication.UsingServicePrincipal(tenantId, subscriptionId, clientId, clientSecret);

// Create provider
var provider = ApplicationInsightsProvider.LocatedAt(resourceGroupName, applicationInsightsName, authentication);

// For the client
using (var applicationInsights = await ApplicationInsightsClient.CreateAsync(resourceGroup, applicationInsightsName, authentication))    
{    
     applicationInsights.Something()
}

However, the things I see in the samples above are more related to Log Analtyics maybe? Or what is the goal there? It's not really clear what the use cases would be.

[paul-warwick-cdt]

Agreed this is very much a base class (bottom of 3 tiers) that sits below the "Step Definitions" mid-layer, and which in a SpecFlow solution gives the kinds of scenario/encapsulation for the suggested samples.

[tomkerkhove]

I'd suggest that we do this gradually then and implement an additional provider without the additional abstraction with a follow-up PR to refactor LA + new provider into that model, or combine it in the same one but not just a PR with the foundation as it's not easy to grasp if the approach is correct for us

[paul-warwick-cdt]

Invictus_Refactor_proposal.pptx
AppInsightsInvictusGuide_60_2.docx

Following review attached are:
[1] Powerpoint of a 1 hour refactor proposed to separate common code for Authentication and allow this to be leveraged both by Logic Apps & a new Invictus Authentication class re-usable across all API related future features
[2] A simplified word doc version of the starter Application Insights provider overview for future review/implementation