Qodex.ai

Azure onboarding collection

Number of APIs: 16

Microsoft Azure provides a number of ways to interact with Azure resources

  • Azure SDKs in many languages, including .NET, Python, Java, JavaScript/TypeScript, Go, C++, C, Android, iOS, PHP, and Ruby
  • Azure CLI to execute commands
  • Azure REST APIs

In the following section, let's explore how to authenticate with the Azure REST APIs, and follow [these step-by-step instructions] to get started.

🏆 Special acknowledgements to Azure ambassadors, Mireille Tan and Muhammad Suzarilshah, for their contributions to this guide.

Set up Azure API on Qodex with Azure CLI

Requirements

  1. Azure Cloud with an active subscription.
  2. Download and install [Qodex Desktop App]
  3. Download and install Azure CLI
    1. For MacOS
    2. For Windows

Step 1 - Getting Started

Follow this tutorial for more detailed instructions: How to call Azure REST APIs with Qodex

  • From the terminal, use the Azure CLI to run the az login command. You will be redirected to log in to your Azure account in a web browser. Upon successful login, you will be presented with your account details, as shown below. Please take note of the id variable, as we need this information later. The id variable is our subscription ID on Azure.
  • Select an active Azure subscription using the az account set command. Use the -n parameter to specify the subscription name, i.e: az account set -n "MSDN Platforms Subscription". A list of your subscriptions can be found in the Azure portal.
  • Create a resource group using the command az group create --location [Azure Location, i.e: westus] --resource-group [Resource Group]
  • Azure REST API authentication is done via a Bearer token in the Authentication header. Let's use a service principal to get that token for us. A service principal is an Azure account that allows you to perform actions on Azure resources. Think about it like a system account that you can assign roles to and get tokens with. Create a service principal using the command az ad sp create-for-rbac -n [SP_Name] --role Owner --scope "/subscriptions/[Subscription_ID]/resourceGroups/[ Resource Group]". The Output should look like this:
  • This command will provide the credentials we need to work on Qodex to test Azure APIs:
    • AppID
    • displayname
    • Password
    • Tenant
  • Copy the credentials to somewhere safe. Please do not expose the credentials! You can also explore other roles when creating a service principal by using the --role flag and specify the scope of the SP credentials with the --scope flag. Documentations included here.
  • Some built-in roles in Azure RBAC include:
    • Owner - Total control of a Resource Group
    • Contributor - Has control on Actions on a Resource Group like modifying a Resource Group (i.e. Deleting a VM) but cannot assign permission to the RG.
    • Reader - only has the ability to view the resource group.
    • Learn More
  • The example of generating service principal details are as following:
az ad sp create-for-rbac -n Qodex --role Owner --scope "/subscriptions/[SubID]/resourceGroups/Qodex"


{
  "appId": "e8df7f8a-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "displayName": "azure-cli-2023-XX-XX-XX-XX-XX",
  "password": "XXXXX~XXXXXXXX.XXXXXXXXXXX",
  "tenant": "XXXXXX-XXXXX-XXXX-XXXX-XXXXXXXXXXX"
}

To get the ID for the service principal credentials, you can run the command get-AzADServicePrincipal -DisplayName $name". Replace the $name with the displayName found from the previous output.

Example:

get-AzADServicePrincipal -DisplayName [displayName]


DisplayName                   Id                                   AppId
-----------                   --                                   -----
azure-cli-2023-XX-XX-XX-XX-XX XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX

Get the subscription ID for your Azure Instance

From the terminal, use the Azure CLI command az account show --query id -o tsv or az account subscription list. The output should look like the following:

az account subscription list
The command requires the extension account. Do you want to install it now? The command will continue to run after the extension is installed. (Y/n): y
Run 'az config set extension.use_dynamic_install=yes_without_prompt' to allow installing extensions without prompt.
Command group 'account subscription' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[
  {
    "authorizationSource": "Legacy",
    "displayName": "MSDN Platforms Subscription",
    "id": "/subscriptions/[subscription ID]",
    "state": "Enabled",
    "subscriptionId": "[subscription ID]",
    "subscriptionPolicies": {
      "locationPlacementId": "Public_2014-XX-XX",
      "quotaId": "MSDN_2014-XX-XX",
      "spendingLimit": "On"
    }
  }
]

Step 2 - Rocking with Qodex!

  • Fork the example collection to your own workspace. Then select the Qodex collection that you forked to your workspace. Find the Variables tab, and paste your information into each variable value. Map the values from the Service Principal and Subscription ID output from earlier, and Save your changes.
ClientId = AppID
clientSecret = Password
tenantId = tenant
resource = https://management.azure.com/
resourceGroup = [Resource Group]
subscriptionId = [Subscription ID]
bearerToken = "leave it blank, we will programmatically fill the field later"
  • The configuration should look like this:
  • Select the Qodex collection that you forked to your workspace. Find the Pre-request Script tab containing JavaScript that will execute before every request in the collection. The code will retrieve an OAuth 2.0 bearer token, and then save the value as a collection variable to be re-used throughout the collection.
pm.test("Check for collectionVariables", function () {
    let vars = ['clientId', 'clientSecret', 'tenantId', 'subscriptionId'];
    vars.forEach(function (item, index, array) {
        console.log(item, index);
        pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.undefined;
        pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.empty; 
    });
    if (!pm.collectionVariables.get("bearerToken") || Date.now() > new Date(pm.collectionVariables.get("bearerTokenExpiresOn") * 1000)) {
        pm.sendRequest({
            url: 'https://login.microsoftonline.com/' + pm.collectionVariables.get("tenantId") + '/oauth2/token',
            method: 'POST',
            header: 'Content-Type: application/x-www-form-urlencoded',
            body: {
                mode: 'urlencoded',
                urlencoded: [
                    { key: "grant_type", value: "client_credentials", disabled: false },
                    { key: "client_id", value: pm.collectionVariables.get("clientId"), disabled: false },
                    { key: "client_secret", value: pm.collectionVariables.get("clientSecret"), disabled: false },
                    { key: "resource", value: pm.collectionVariables.get("resource") || "https://management.azure.com/", disabled: false }
                ]
            }
        }, function (err, res) {
            if (err) {
                console.log(err);
            } else {
                let resJson = res.json();
                pm.collectionVariables.set("bearerTokenExpiresOn", resJson.expires_on);
                pm.collectionVariables.set("bearerToken", resJson.access_token);
            }
        });
    }
});
  • Within the Get Started folder, select the Get Resource Groups request. Send the API request. Upon a successful response from the server, note two events that occurred.
    • Bearer token: Select the collection, tab over to Variables, and notice a current value is saved under bearerToken. This happened when the pre-request script executed.
    • Authorization header: Select the request Get Resource Groups. Under the Authorization tab, note the request inherits the same authorization method, Bearer Token, from the collection. Under the Headers tab, you may need to expand the headers auto-generated by Qodex to see an Authorization header with a value formatted like Bearer xxx where xxx is the saved token.
  • Now that you have properly configured the authorization at the collection-level, you can re-use it throughout other requests within the collection, unless otherwise configured.
  • Voila! You have successfully set up Azure API authentication and performed an Azure API GET Request on Qodex!

Explore more Azure APIs

Explore the complete list of Azure APIs from the documentation here.

OAuth 2.0

To specify permission scope for advanced API usage, you can set up OAuth 2.0 authentication type on Qodex.

Simply add the following to the variables in the parent collection

  1. https://management.azure.com/.default - https://management.azure.com/.default (This is the default value for managing Azure resources)
  2. https://login.microsoftonline.com//oauth2/v2.0/token - https://login.microsoftonline.com//oauth2/v2.0/token (This is the API endpoint to generate Access Token for OAuth2.0)

Changing the Authentication type on the parent collection

Under the Authorization Tab of the parent collection, Select OAuth 2.0

Under the **Configure New Token section**, set the values as show below

After that, click on the Get New Access Token button to generate a new OAuth2.0 Token.

An auth Token will be generated. Please ensure that you click on Use Token button or otherwise the collection will not use the token to authenticate to Azure.

Testing

Lets try querying using one Request from the Colection

You should be able to query requests using the OAuth 2.0 Token.

  1. AI-Cognitive Search - Search index GET https://{{searchServiceName}}.search.windows.net/indexes/{{searchIndexName}}/docs?api-version=2020-06-30&search=*

  2. Get Started - Add Resource Groups PUT {{resource}}/subscriptions/{{subscriptionId}}/resourcegroups/:resourceGroup?api-version=2021-04-01

  3. Get Started - Get Subscription GET {{resource}}/subscriptions/{{subscriptionId}}/resourcegroups/{{resourceGroup}}?api-version=2021-04-01

  4. AI-Cognitive Search - Delete index DELETE https://{{searchServiceName}}.search.windows.net/indexes/{{searchIndexName}}/?api-version=2020-06-30

  5. Get Started - Get Resource Groups GET {{resource}}/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01

  6. AI-Cognitive Search - Create index POST https://{{searchServiceName}}.search.windows.net/indexes?api-version=2020-06-30

  7. AI-Cognitive Search - Delete documents from index POST https://{{searchServiceName}}.search.windows.net/indexes/{{searchIndexName}}/docs/index?api-version=2020-06-30

  8. AI-Speech-Text-to-Speech - Get list of voices GET https://{{region}}.tts.speech.microsoft.com/cognitiveservices/voices/list

  9. AI-Speech-Text-to-Speech - Convert text to speech POST https://{{region}}.tts.speech.microsoft.com/cognitiveservices/v1

  10. AI-Speech - Speech-to-Text POST https://{{region}}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US