Azure Cognitive Services setup

To enable the connector leverage Azure Cognitive Services, you'll need a Text Analytics API setup. The following will walk you through this brief setup and how you can test the service outside of the connector to make sure all is working.

1. Sign into https://portal.azure.com with the credentials/account you'll use to create the service.
2. Create a New Resource, searching for "Text Analytics API" and choosing Create.

3. Next we'll need to provide some information about the Cognitive Services we're creating. We'll need to give our service a name (e.g. Text-SCSMExchangeConnector), the subscription we'll be placing it in, the Azure data center/location we want this hosted in, the pricing tier of your choosing, and finally the Resource Group. If you're new to the idea of Resource Groups, they are fairly analogous to the concept of System Center Management Packs in that you keep "like" things together. For example, you could create a Resource Group called SCSMCognitiveServices and it in throw other Cognitive Services engines.

4. Finally, let's grab the API keys we'll need to use the service along with the Azure Region the service is hosted in (this was the location you selected in step 3 above). As indicated by the Quick Start menu we're dropped into or clicking "keys" on the right will get you your API keys required to make the authenticated call to Azure and ensure your (and not anyone elses) Cognitive Service is called. You're given two keys, but you only need one to set the value for the $azureCogSvcAPIKey variable. Next, we'll need the Azure Region/data center/location you chose. In the following screenshot I've replaced the text we're interested in. You'll use this value in the script as your $azureRegion variable.

With your new Azure Cognitive Service setup, you can use the following PowerShell to prove connectivity and that you have the right variables in order. These two functions are the identical ones used in the connector and can be invoked as seen at the bottom.

#azure settings
#azureRegion = based on where Cognitive Services app is deployed as seen in its respective settings pane, i.e. ukwest, eastus2, westus, northcentralus
#apiKey = Text Analytics API key as seen in the Azure Portal for the deployed cognitive service
$azureRegion = ""
$azureCogSvcAPIKey = ""

function Get-AzureEmailSentiment ($messageToEvaluate)
{
    #define cognitive services URLs
    $sentimentURI = "https://$azureRegion.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"

    #create the JSON request
    $documents = @()
    $requestHashtable = @{"language" = "en"; "id" = "1"; "text" = "$messageToEvaluate" };
    $documents += $requestHashtable
    $final = @{documents = $documents}
    $messagePayload = ConvertTo-Json $final

    #invoke the Cognitive Services Sentiment API
    $sentimentResult = Invoke-RestMethod -Method Post -Uri $sentimentURI -Header @{ "Ocp-Apim-Subscription-Key" = $azureCogSvcAPIKey } -Body $messagePayload -ContentType "application/json"
    
    #return the percent score
    return ($sentimentResult.documents.score * 100)
}
function Get-AzureEmailKeywords ($messageToEvaluate)
{
    #define cognitive services URLs
    $keyPhraseURI = "https://$azureRegion.api.cognitive.microsoft.com/text/analytics/v2.0/keyPhrases"

    #create the JSON request
    $documents = @()
    $requestHashtable = @{"language" = "en"; "id" = "1"; "text" = "$messageToEvaluate" };
    $documents += $requestHashtable
    $final = @{documents = $documents}
    $messagePayload = ConvertTo-Json $final

    #invoke the Text Analytics Keyword API
    $keywordResult = Invoke-RestMethod -Method Post -Uri $keyPhraseURI -Header @{ "Ocp-Apim-Subscription-Key" = $azureCogSvcAPIKey } -Body $messagePayload -ContentType "application/json" 

    #return the keywords
    return $keywordResult.documents.keyPhrases
}

Get-AzureEmailKeywords -messageToEvaluate "Can someone reset my password for the website?"
Get-AzureEmailSentiment -messageToEvaluate "Can someone reset my password for the website?"