Forem: Markus Meyer

How to create an Azure API Management Service with Developer Portal with CI/CD using Azure DevOps

Markus Meyer — Wed, 28 Feb 2024 13:51:12 +0000

Prerequisites
Step 1: Create an Azure API Management Service
Step 2: Set Up the App Registration for the Developer Portal
Step 3: Register the app registration with the API Management service
Complete Code

In this blog post, we will walk through the steps to create an Azure API Management service and set up the Developer Portal. Azure API Management is a fully managed service that enables organizations to publish, secure, and manage APIs at scale. The Developer Portal is a customizable self-service portal where developers can discover, learn, and consume your APIs. Azure DevOps CI/CD pipeline will be used to automate the deployment of the API Management service and the Developer Portal. Bicep will be used to define the infrastructure as code for the API Management service and the Developer Portal.

The Azure DevOps pipeline uses three steps to complete the deployment:

The Developer Portal with Azure Active Directory authentication:

Prerequisites

Before we begin, make sure you have the following:

Azure DevOps service principal with the necessary permissions to create and manage resources in Azure.
this service principal should have at least the following permissions:
- Application.ReadWrite.OwnedBy

Step 1: Create an Azure API Management Service

The following Bicep code defines an Azure API Management service with the required configuration options, such as the publisher email and name. The apim resource creates an API Management service with the specified properties, including the pricing tier and location.

@description('The email address of the owner of the service')
@minLength(1)
param publisherEmail string

@description('The name of the owner of the service')
@minLength(1)
param publisherName string

@description('Location for all resources.')
param location string = resourceGroup().location

var apimName = 'apim-eval-mm-${uniqueString(resourceGroup().id)}'
resource apim 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: apimName
  location: location
  sku: {
    name: 'Developer'
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: publisherEmail
    publisherName: publisherName
  }
}

Configure App Insights

App Insights is a monitoring and diagnostics service that helps you understand how your application is performing and how it's being used. You can use App Insights to monitor the performance and usage of your APIs in the API Management service. The following Bicep code creates an App Insights resource and configures it to send telemetry data to a Log Analytics workspace.

var logAnalyticsWorkspaceName = 'log-eval-mm-${uniqueString(resourceGroup().id)}'
resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: logAnalyticsWorkspaceName
  location: location
  properties: any({
    retentionInDays: 90
    features: {
      searchVersion: 1
    }
    sku: {
      name: 'Standalone'
    }
  })
}

var appInsightsName = 'appi-eval-mm-${uniqueString(resourceGroup().id)}'
resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: appInsightsName
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
    WorkspaceResourceId: logAnalyticsWorkspace.id
    publicNetworkAccessForIngestion: 'Enabled'
    publicNetworkAccessForQuery: 'Enabled'
  }
}

resource namedValueAppInsightsKey 'Microsoft.ApiManagement/service/namedValues@2023-05-01-preview' = {
  parent: apim
  name: 'instrumentationKey'
  properties: {
    tags: []
    secret: false
    displayName: 'instrumentationKey'
    value: appInsights.properties.InstrumentationKey
  }
}

resource apimLogger 'Microsoft.ApiManagement/service/loggers@2023-05-01-preview' = {
  parent: apim
  name: 'apimlogger'
  properties: {
    resourceId: appInsights.id
    description: 'Application Insights for APIM'
    loggerType: 'applicationInsights'
    credentials: {
      instrumentationKey: '{{instrumentationKey}}'
    }
  }
  dependsOn: [
    namedValueAppInsightsKey
  ]
}

Step 2: Set Up the App Registration for the Developer Portal

The Developer Portal will use Azure Active Directory (Azure AD / Microsoft Entra ID) for authentication and authorization. You can configure the Developer Portal to use Microsoft Entra ID by creating an app registration with Powershell and granting it the necessary permissions to access the API Management service.

Create App Registration

# Create the app registration. $appName is the same name as the API Management service.
$newApp = az ad app create --display-name $appName --sign-in-audience AzureADMyOrg

Create client secret

The app registration needs a client secret to authenticate with the API Management service. You can use the following command to create a client secret for the app registration.

# Create client secret
$clientSecret = az ad app credential reset --id $appId --years 42 --display-name eval-secret --append --output tsv --query "password"

Configure authentication

The app registration needs to be configured to enable implicit grant settings and redirect URIs for the Developer Portal. You can use the following commands to configure the app registration for the Developer Portal.

$webJson = @{
    implicitGrantSettings = @{
        enableIdTokenIssuance     = $true
        enableAccessTokenIssuance = $true
    }
    redirectUris          = @()
} | ConvertTo-Json -d 4 -Compress
if ($IsWindows -eq $true) {
    $webJson = $webJson | ConvertTo-Json -d 4
}

az ad app update --id $appId --set web=$webJson

$replyUrlSignInAad = "https://$appName.portal.azure-api.net/signin-aad"
$replyUrlSignIn = "https://$appName.developer.azure-api.net/signin"

$spaJson = @{
    redirectUris = @(
        "$replyUrlSignInAad"
        "$replyUrlSignIn"
    )
} | ConvertTo-Json -d 4 -Compress

if ($IsWindows -eq $true) {
    $spaJson = $spaJson | ConvertTo-Json -d 4
}
az ad app update --id $appId --set spa=$spaJson

Grant permissions

The app registration needs to be granted the necessary permissions to access the API Management service. You can use the following commands to grant the app registration the necessary permissions to access the API Management service.

Azure Active Directory Graph
- Directory.Read.All
- User.Read
Microsoft Graph
- Directory.Read.All
- User.Read

az ad app permission add --id $appId --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role
az ad app permission add --id $appId --api 00000003-0000-0000-c000-000000000000 --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope
az ad app permission add --id $appId --api 00000002-0000-0000-c000-000000000000 --api-permissions 5778995a-e1bf-45b8-affa-663a9f3f4d04=Role
az ad app permission add --id $appId --api 00000002-0000-0000-c000-000000000000 --api-permissions 311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope

To finalize the configuration, you need to grant admin consent to the app registration.

Note: As mentioned in the screenshot, Azure Active Directory Graph is obsolete. If you enabling the Developer Portal in the Azure Portal, the same permissions will be used.

Step 3: Register the app registration with the API Management service

The app registration needs to be registered with the API Management service to enable the Developer Portal. This can be done using the following Bicep code to add the Aad identity provider to the API Management service.

var tenantId = subscription().tenantId
resource developerPortalIdentityMicrosoftEntraId 'Microsoft.ApiManagement/service/identityProviders@2023-05-01-preview' = {
  parent: apim
  name: 'Aad'
  properties: {
    clientId: apimAppId
    clientSecret: apimAppClientSecret
    signinTenant: tenantId
    allowedTenants: [
      tenantId
    ]
    type: 'aad'
    clientLibrary: 'MSAL-2'
  }
}

Complete Code

The complete code consists of the following files:

Add-DeveloperPortal-Microsoft-Entra-Id.ps1
- Powershell script to create the app registration and configure it for the Developer Portal.
apim.bicep
- Bicep file to create the API Management service and configure App Insights.
apim.developer.bicep
- Bicep file to register the app registration with the API Management service.
azure-pipeline.yaml
- Azure DevOps pipeline to automate the deployment of the API Management service and the Developer Portal.

Bicep API Management service

Bicep file to create the API Management service and configure App Insights apim.bicep.

@description('The email address of the owner of the service')
@minLength(1)
param publisherEmail string

@description('The name of the owner of the service')
@minLength(1)
param publisherName string

@description('Location for all resources.')
param location string = resourceGroup().location

var apimName = 'apim-eval-mm-${uniqueString(resourceGroup().id)}'
resource apim 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: apimName
  location: location
  sku: {
    name: 'Developer'
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: publisherEmail
    publisherName: publisherName
  }
}

var tenantId = subscription().tenantId

var keyVaultName = 'kv-eval-mm-${uniqueString(resourceGroup().id)}'
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: keyVaultName
  location: location
  properties: {
    enabledForTemplateDeployment: true
    enablePurgeProtection: true
    enableRbacAuthorization: true
    enableSoftDelete: true
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: tenantId
  }
}

var logAnalyticsWorkspaceName = 'log-eval-mm-${uniqueString(resourceGroup().id)}'
resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: logAnalyticsWorkspaceName
  location: location
  properties: any({
    retentionInDays: 90
    features: {
      searchVersion: 1
    }
    sku: {
      name: 'Standalone'
    }
  })
}

var appInsightsName = 'appi-eval-mm-${uniqueString(resourceGroup().id)}'
resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: appInsightsName
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
    WorkspaceResourceId: logAnalyticsWorkspace.id
    publicNetworkAccessForIngestion: 'Enabled'
    publicNetworkAccessForQuery: 'Enabled'
  }
}

resource namedValueAppInsightsKey 'Microsoft.ApiManagement/service/namedValues@2023-05-01-preview' = {
  parent: apim
  name: 'instrumentationKey'
  properties: {
    tags: []
    secret: false
    displayName: 'instrumentationKey'
    value: appInsights.properties.InstrumentationKey
  }
}

resource apimLogger 'Microsoft.ApiManagement/service/loggers@2023-05-01-preview' = {
  parent: apim
  name: 'apimlogger'
  properties: {
    resourceId: appInsights.id
    description: 'Application Insights for APIM'
    loggerType: 'applicationInsights'
    credentials: {
      instrumentationKey: '{{instrumentationKey}}'
    }
  }
  dependsOn: [
    namedValueAppInsightsKey
  ]
}

Bicep API Management Developer Portal

Bicep file to register the app registration with the API Management service apim.developer.bicep.

@description('Client Secret of App Registration for APIM Developer Portal')
@secure()
@minLength(1)
param apimAppClientSecret string

@description('AppId of App Registration for APIM Developer Portal')
@minLength(1)
param apimAppId string

var apimName = 'apim-eval-mm-${uniqueString(resourceGroup().id)}'
resource apim 'Microsoft.ApiManagement/service@2023-05-01-preview' existing = {
  name: apimName
}

var tenantId = subscription().tenantId

resource developerPortalIdentityMicrosoftEntraId 'Microsoft.ApiManagement/service/identityProviders@2023-05-01-preview' = {
  parent: apim
  name: 'Aad'
  properties: {
    clientId: apimAppId
    clientSecret: apimAppClientSecret
    signinTenant: tenantId
    allowedTenants: [
      tenantId
    ]
    type: 'aad'
    clientLibrary: 'MSAL-2'
  }
}

Powershell

Powershell script to create the app registration and configure it for the Developer Portal Add-DeveloperPortal-Microsoft-Entra-Id.ps1.

<#
.SYNOPSIS
This code adds a new App Registration to Microsoft Entra Id.

.DESCRIPTION
This code adds the App Registration, creates a service principal and return the ClientSecret.

.PARAMETER ApimName
Specify the API Management Service name.

.OUTPUTS
Returns the ClientSecret and AppId.

.EXAMPLE
Example usage of the code:
 .\Add-DeveloperPortal-Microsoft-Entra-Id.ps1 -ApimName apim-eval-mm-ta4jvourkbccs

.NOTES
  The user / service principal running this script must have the necessary permissions to create an App Registration in the Azure AD tenant:
  At least: Application.ReadWrite.OwnedBy
#>

[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]
    $ApimName
)

$appName = $ApimName
Write-Host "Creating app registration for '$appName'..."


try {
    $existingApp = az ad app list --display-name $appName --query "[0]"

    if (-not $existingApp) {


        Write-Host "App does not exist. Creating app registration..."

        # Create the app registration
        $newApp = az ad app create --display-name $appName --sign-in-audience AzureADMyOrg 

        if (-not $newApp) {
            Write-Error -Message "Cannot add App Registration" -ErrorAction Stop
            return;
        }
        $appId = az ad app list --display-name $appName --query "[].[appId]" --output tsv

        # Create client secret
        $clientSecret = az ad app credential reset --id $appId --years 42 --display-name eval-secret --append --output tsv --query "password"

        $webJson = @{
            implicitGrantSettings = @{
                enableIdTokenIssuance     = $true
                enableAccessTokenIssuance = $true
            }
            redirectUris          = @()
        } | ConvertTo-Json -d 4 -Compress
        if ($IsWindows -eq $true) {
            $webJson = $webJson | ConvertTo-Json -d 4
        }

        az ad app update --id $appId --set web=$webJson

        $replyUrlSignInAad = "https://$appName.portal.azure-api.net/signin-aad"
        $replyUrlSignIn = "https://$appName.developer.azure-api.net/signin"

        $spaJson = @{
            redirectUris = @(
                "$replyUrlSignInAad"
                "$replyUrlSignIn"
            )
        } | ConvertTo-Json -d 4 -Compress

        if ($IsWindows -eq $true) {
            $spaJson = $spaJson | ConvertTo-Json -d 4
        }
        az ad app update --id $appId --set spa=$spaJson

        # requiredResourceAccess
        az ad app permission add --id $appId --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role
        az ad app permission add --id $appId --api 00000003-0000-0000-c000-000000000000 --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope
        az ad app permission add --id $appId --api 00000002-0000-0000-c000-000000000000 --api-permissions 5778995a-e1bf-45b8-affa-663a9f3f4d04=Role
        az ad app permission add --id $appId --api 00000002-0000-0000-c000-000000000000 --api-permissions 311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope
    }
    else {
        Write-Output "App registration with the name '$appName' already exists."
        Write-Output "No new app registration created."
    }
}
catch {
    Write-Output $_
    Write-Error -Message "Error on adding App Registration" -ErrorAction Stop
}

# Return the client secret and app id
return @($clientSecret, $appId)

Pipeline

Azure DevOps pipeline to automate the deployment of the API Management service and the Developer Portal azure-pipeline.yaml.

The Powershell script returns the app registration details, such as the app ID and client secret, which are used in the Bicep files to configure the API Management service and the Developer Portal. Write-Host "##vso[task.setvariable variable=apimClientSecret;issecret=true]$appRegistrationClientSecret" is used to store this information as a secret in the Azure DevOps pipeline which will be passed later to the Bicep file.

trigger:
  branches:
    include:
    - feature/*

pool:
  vmImage: ubuntu-latest

variables:
  ServiceConnectionName: 'Azure Service Connection'
  ResourceGroupName: 'eval.webapp'
  DeploymentDefaultLocation: 'westeurope'

jobs:
- job:
  steps:
  - task: AzureResourceManagerTemplateDeployment@3
    inputs:
      connectedServiceName: $(ServiceConnectionName)
      location: $(DeploymentDefaultLocation)
      resourceGroupName: $(ResourceGroupName)
      csmFile: apim.bicep
      overrideParameters: -publisherEmail lorem@ipsum -publisherName 'Lorem'
  - task: AzureCLI@2
    displayName: Deploy DEV - App Registration Script
    inputs:
      azureSubscription: $(ServiceConnectionName)
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Create App Registration"
        $appRegistration=$(Build.SourcesDirectory)/Add-DeveloperPortal-Microsoft-Entra-Id.ps1 -ApimName apim-eval-mm-ta4jvourkbccs
        $appRegistrationClientSecret = $appRegistration[0]
        $appRegistrationAppId = $appRegistration[1]
        Write-Host "##vso[task.setvariable variable=apimClientSecret;issecret=true]$appRegistrationClientSecret"
        Write-Host "##vso[task.setvariable variable=apimAppId;issecret=false]$appRegistrationAppId"

  - task: AzureResourceManagerTemplateDeployment@3
    condition: and(succeeded(), ne(variables['apimClientSecret'], ''), ne(variables['apimAppId'], ''))
    inputs:
      connectedServiceName: $(ServiceConnectionName)
      location: $(DeploymentDefaultLocation)
      resourceGroupName: $(ResourceGroupName)
      csmFile: apim.developer.bicep
      overrideParameters: '-apimAppClientSecret $(apimClientSecret) -apimAppId $(apimAppId)'

Deploying OpenAPI in Azure API Management with Terraform

Markus Meyer — Wed, 22 Jun 2022 10:52:10 +0000

An OpenAPI definition has to be deployed to API Management. The deployment is done with Terraform. Will an updated OpenAPI definition also update API Management API and operations?

The entire code can be found in GitHub https://github.com/PlanBGmbH/usecases.azure.apimanagement/tree/main/src/APIM-with-OpenAPI

1 Terraform

2 Create API

3 Update API

1 Terraform

With Terraform, API Management and also the Example API is created.
Thefore the local OpenAPI definition file has to be imported.

resource "azurerm_api_management" "example" {
  name                = var.apim_name
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  publisher_name      = "PlanB. GmbH"
  publisher_email     = "markus1.meyer@plan-b-gmbh.om"

  sku_name = "Developer_1"
}

resource "azurerm_api_management_api" "example" {
  name                = "example-api"
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.example.name
  revision            = "1"
  display_name        = "Example API"
  path                = "example"
  protocols           = ["https"]

  import {
    content_format = "openapi"
    content_value  = file("${path.module}/example-api.yaml")
  }
}

2 Create API

The initial version of the OpenAPI contains only the path '/users/{username}' with a GET and PUT operation.
The OpenAPI definition is copied from https://github.com/Redocly/openapi-template/blob/gh-pages/openapi.yaml

# This is an **example** API to demonstrate features of OpenAPI specification.
# It doesn't cover all OpenAPI features. For more full example check out: https://github.com/APIs-guru/petstore_extended

openapi: 3.0.1
info:
  version: '1.0.0' # Your API version
  # It can be any string but it is better to use semantic versioning: http://semver.org/
  # Warning: OpenAPI requires the version to be a string, but without quotation marks YAML can recognize it as a number.

  title: Example.com # Replace with your API title
  # Keep it simple. Don't add "API" or version at the end of the string.

  termsOfService: 'https://example.com/terms/' # [Optional] Replace with an URL to your ToS
  contact:
    email: contact@example.com # [Optional] Replace with your contact email
    url: 'http://example.com/contact' # [Optional] Replace with link to your contact form
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  x-logo:
    url: 'https://redocly.github.io/openapi-template/logo.png'

  # Describe your API here, you can use GFM (https://guides.github.com/features/mastering-markdown) here
  description: |
    This is an **example** API to demonstrate features of OpenAPI specification
    # Introduction
    This API definition is intended to to be a good starting point for describing your API in 
    [OpenAPI/Swagger format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).
    It also demonstrates features of [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool and 
    [Redoc](https://github.com/Redocly/Redoc) documentation engine. So beyond the standard OpenAPI syntax we use a few 
    [vendor extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md).
    # OpenAPI Specification
    The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which
    allows both humans and computers to discover and understand the capabilities of the service without access to source
    code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can 
    understand and interact with the remote service with a minimal amount of implementation logic. Similar to what
    interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.
externalDocs:
  description: Find out how to create a GitHub repo for your OpenAPI definition.
  url: 'https://github.com/Rebilly/generator-openapi-repo'

# A list of tags used by the definition with additional metadata.
# The order of the tags can be used to reflect on their order by the parsing tools.
  - name: User
    description: Operations about user
servers:
  - url: 'http://example.com/api/v1'
  - url: 'https://example.com/api/v1'

# Holds the relative paths to the individual endpoints. The path is appended to the
# basePath in order to construct the full URL. 
paths:
  '/users/{username}': # path parameter in curly braces

    # parameters list that are used with each operation for this path
    parameters:
      - name: pretty_print
        in: query
        description: Pretty print response
        schema:
          type: boolean
    get: # documentation for GET operation for this path
      tags:
        - User

      # summary is up to 120 symbold but we recommend to be shortest as possible
      summary: Get user by user name

      # you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown
      description: |
        Some description of the operation. 
        You can use `markdown` here.

      # operationId should be unique across the whole specification
      operationId: getUserByName

      # list of parameters for the operation
      parameters:
        - name: username
          in: path
          description: The name that needs to be fetched
          required: true
          schema:
            type: string
        - name: with_email
          in: query
          description: Filter users without email
          schema:
            type: boolean

      # security schemas applied to this operation
      security:
        - main_auth:
            - 'read:users' # for oauth2 provide list of scopes here
        - api_key: []
      responses: # list of responses
        '200':
          description: Success
          content:
            application/json: # operation response mime type
              schema: # response schema can be specified for each response
                $ref: '#/components/schemas/User'
              example: # response example
                username: user1
                email: user@example.com
        '403':
          description: Forbidden
        '404':
          description: User not found
    # documentation for PUT operation for this path
    put:
      tags:
        - User
      summary: Updated user
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: The name that needs to be updated
          required: true
          schema:
            type: string
      security:
        - main_auth:
            - 'write:users'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid user supplied
        '404':
          description: User not found
      # request body documentation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
        description: Updated user object
        required: true

# An object to hold reusable parts that can be used across the definition
components:
  schemas:
    Email:
      description: User email address
      type: string
      format: test
      example: john.smith@example.com
    User:
      type: object
      properties:
        username:
          description: User supplied username
          type: string
          minLength: 4
          example: John78
        firstName:
          description: User first name
          type: string
          minLength: 1
          example: John
        lastName:
          description: User last name
          type: string
          minLength: 1
          example: Smith
        email:
          $ref: '#/components/schemas/Email'
  headers:
    ExpiresAfter:
      description: date in UTC when token expires
      schema:
        type: string
        format: date-time
  # Security scheme definitions that can be used across the definition.
  securitySchemes:
    main_auth: # security definition name (you can name it as you want)
      # the following options are specific to oauth2 type
      type: oauth2 # authorization type, one of: oauth2, apiKey, http
      flows:
        implicit:
          authorizationUrl: 'http://example.com/api/oauth/dialog'
          scopes:
            'read:users': read users info
            'write:users': modify or remove users
    api_key:  # security definition name (you can name it as you want)
      type: apiKey 
      # The following options are specific to apiKey type
      in: header # Where API key will be passed: header or query
      name: api_key # API key parameter name
    basic_auth: # security definition name (you can name it as you want)
      type: http
      scheme: basic

Execute terraform:

terraform plan

terraform apply

The API Management with API 'Example API' is successfully created:

3 Update API

The OpenAPI definition is updated with path '/echo'.

# This is an **example** API to demonstrate features of OpenAPI specification.
# It doesn't cover all OpenAPI features. For more full example check out: https://github.com/APIs-guru/petstore_extended

openapi: 3.0.1
info:
  version: '1.0.0' # Your API version
  # It can be any string but it is better to use semantic versioning: http://semver.org/
  # Warning: OpenAPI requires the version to be a string, but without quotation marks YAML can recognize it as a number.

  title: Example.com # Replace with your API title
  # Keep it simple. Don't add "API" or version at the end of the string.

  termsOfService: 'https://example.com/terms/' # [Optional] Replace with an URL to your ToS
  contact:
    email: contact@example.com # [Optional] Replace with your contact email
    url: 'http://example.com/contact' # [Optional] Replace with link to your contact form
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  x-logo:
    url: 'https://redocly.github.io/openapi-template/logo.png'

  # Describe your API here, you can use GFM (https://guides.github.com/features/mastering-markdown) here
  description: |
    This is an **example** API to demonstrate features of OpenAPI specification
    # Introduction
    This API definition is intended to to be a good starting point for describing your API in 
    [OpenAPI/Swagger format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).
    It also demonstrates features of [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool and 
    [Redoc](https://github.com/Redocly/Redoc) documentation engine. So beyond the standard OpenAPI syntax we use a few 
    [vendor extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md).
    # OpenAPI Specification
    The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which
    allows both humans and computers to discover and understand the capabilities of the service without access to source
    code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can 
    understand and interact with the remote service with a minimal amount of implementation logic. Similar to what
    interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.
externalDocs:
  description: Find out how to create a GitHub repo for your OpenAPI definition.
  url: 'https://github.com/Rebilly/generator-openapi-repo'

# A list of tags used by the definition with additional metadata.
# The order of the tags can be used to reflect on their order by the parsing tools.
tags:
  - name: Echo
    description: Example echo operations
  - name: User
    description: Operations about user
servers:
  - url: 'http://example.com/api/v1'
  - url: 'https://example.com/api/v1'

# Holds the relative paths to the individual endpoints. The path is appended to the
# basePath in order to construct the full URL. 
paths:
  '/users/{username}': # path parameter in curly braces

    # parameters list that are used with each operation for this path
    parameters:
      - name: pretty_print
        in: query
        description: Pretty print response
        schema:
          type: boolean
    get: # documentation for GET operation for this path
      tags:
        - User

      # summary is up to 120 symbold but we recommend to be shortest as possible
      summary: Get user by user name

      # you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown
      description: |
        Some description of the operation. 
        You can use `markdown` here.

      # operationId should be unique across the whole specification
      operationId: getUserByName

      # list of parameters for the operation
      parameters:
        - name: username
          in: path
          description: The name that needs to be fetched
          required: true
          schema:
            type: string
        - name: with_email
          in: query
          description: Filter users without email
          schema:
            type: boolean

      # security schemas applied to this operation
      security:
        - main_auth:
            - 'read:users' # for oauth2 provide list of scopes here
        - api_key: []
      responses: # list of responses
        '200':
          description: Success
          content:
            application/json: # operation response mime type
              schema: # response schema can be specified for each response
                $ref: '#/components/schemas/User'
              example: # response example
                username: user1
                email: user@example.com
        '403':
          description: Forbidden
        '404':
          description: User not found
    # documentation for PUT operation for this path
    put:
      tags:
        - User
      summary: Updated user
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: The name that needs to be updated
          required: true
          schema:
            type: string
      security:
        - main_auth:
            - 'write:users'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid user supplied
        '404':
          description: User not found
      # request body documentation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
        description: Updated user object
        required: true
  /echo: # path parameter in curly braces
    post: # documentation for POST operation for this path
      tags:
        - Echo
      summary: Echo test
      description: Receive the exact message you've sent
      operationId: echo
      security:
        - api_key: []
        - basic_auth: []
      responses:
        '200':
          description: OK
          # document headers for this response
          headers:
            X-Rate-Limit: # Header name
              description: calls per hour allowed by the user
              schema: # Header schema
                type: integer
                format: int32
            X-Expires-After:
              $ref: '#/components/headers/ExpiresAfter'
          content:
            application/json:
              schema:
                type: string
              examples:
                response:
                  value: Hello world!
            application/xml:
              schema:
                type: string
            text/csv:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: Hello world!
          application/xml:
            schema:
              type: string
              example: Hello world!
        description: Echo payload
        required: true

# An object to hold reusable parts that can be used across the definition
components:
  schemas:
    Email:
      description: User email address
      type: string
      format: test
      example: john.smith@example.com
    User:
      type: object
      properties:
        username:
          description: User supplied username
          type: string
          minLength: 4
          example: John78
        firstName:
          description: User first name
          type: string
          minLength: 1
          example: John
        lastName:
          description: User last name
          type: string
          minLength: 1
          example: Smith
        email:
          $ref: '#/components/schemas/Email'
  headers:
    ExpiresAfter:
      description: date in UTC when token expires
      schema:
        type: string
        format: date-time
  # Security scheme definitions that can be used across the definition.
  securitySchemes:
    main_auth: # security definition name (you can name it as you want)
      # the following options are specific to oauth2 type
      type: oauth2 # authorization type, one of: oauth2, apiKey, http
      flows:
        implicit:
          authorizationUrl: 'http://example.com/api/oauth/dialog'
          scopes:
            'read:users': read users info
            'write:users': modify or remove users
    api_key:  # security definition name (you can name it as you want)
      type: apiKey 
      # The following options are specific to apiKey type
      in: header # Where API key will be passed: header or query
      name: api_key # API key parameter name
    basic_auth: # security definition name (you can name it as you want)
      type: http
      scheme: basic

Execute Terraform:

terraform plan

Plan: 0 to add, 1 to change, 0 to destroy.

terraform apply

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

After deployment, the changes to the OpenAPI definition were deployed and the added operation Echo test exists:

API Management - Convert SOAP POST to GET

Markus Meyer — Tue, 21 Jun 2022 16:52:24 +0000

API Management is receiving a SOAP POST request with XML in the request body.
Data from the request body has to be forwarded to a GET operation

Import SOAP Service

The public soap service
https://www.dataaccess.com/webservicesserver/numberconversion.wso?op=NumberToDollars is imported in API Management.

The imported SOAP service in API management:

Request-Body for SOAP service:

<?xml version="1.0" encoding="utf-8"?>
<Envelope xmlns="http://www.w3.org/2003/05/soap-envelope">
  <Body>
    <NumberToDollars xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dataaccess.com/webservicesserver/">
      <dNum>1</dNum>
    </NumberToDollars>
  </Body>
</Envelope>

The target API

An additional operation in the Echo API returns the mocked status 200.

<policies>
    <inbound>
        <base />
        <mock-response status-code="200" content-type="application/json" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

This target API has to be replaced with a real-world API.

Transform POST to GET

The incoming request body is escaped and also has additional double quotes which has to be removed:

string xml = context.Request.Body.As<string>(preserveContent: true);
xml = Regex.Unescape(xml);

// Remove the double quotes
xml = xml.Remove(0,1);
xml = xml.Remove(xml.Length-1,1);

Transform the XML string into a JSON object:

XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

var json = JsonConvert.SerializeObject(doc);
var data = JObject.Parse(json );

The transformed JSON string:

{
  "?xml": {
    "@version": "1.0",
    "@encoding": "utf-8"
  },
  "Envelope": {
    "@xmlns": "http://www.w3.org/2003/05/soap-envelope",
    "Body": {
      "NumberToDollars": {
        "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
        "@xmlns": "http://www.dataaccess.com/webservicesserver/",
        "dNum": "1"
      }
    }
  }
}

Finally, the wanted data has to be returned from the JSON Object:

JObject envelope = data["Envelope"] as JObject;
JObject body = envelope["Body"] as JObject;
JObject numberToDollars = body["NumberToDollars"] as JObject;

return numberToDollars["dNum"].Value<string>();

The data has to be forwarded to the mocked API with a GET request:

<set-method>GET</set-method>
<set-backend-service base-url="https://rfqapiservicey27itmeb4cf7q.azure-api.net/echo/200/" />
<rewrite-uri template="@("/test?q=" + context.Variables.GetValueOrDefault<string>("num"))" copy-unmatched-params="false" />

Result

The complete policy:

<policies>
    <inbound>
        <base />
        <set-variable name="num" value="@{
            string xml = context.Request.Body.As<string>(preserveContent: true);
            xml = Regex.Unescape(xml);

            // Remove the double quotes
            xml = xml.Remove(0,1);
            xml = xml.Remove(xml.Length-1,1);

            XmlDocument doc = new XmlDocument();
            doc.LoadXml(xml);

            var data = JObject.Parse(JsonConvert.SerializeObject(doc));
            JObject envelope = data["Envelope"] as JObject;
            JObject body = envelope["Body"] as JObject;
            JObject numberToDollars = body["NumberToDollars"] as JObject;

            return numberToDollars["dNum"].Value<string>();
            }" />
        <set-method>GET</set-method>
        <set-backend-service base-url="https://rfqapiservicey27itmeb4cf7q.azure-api.net/echo/200/" />
        <rewrite-uri template="@("/test?q=" + context.Variables.GetValueOrDefault<string>("num"))" copy-unmatched-params="false" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Testing it in API management:

The trace log:

GitHub answer

Cosmos Db - Increase the paging result size

Markus Meyer — Mon, 20 Jun 2022 13:36:50 +0000

I wasn't aware that the paging size in the Cosmos Db Data explorer can be configured.
So it was able to increase the page size from 100 to 1000,

Settings

The settings gear opens a configuration dialog:

The dialog with

Page options
Enable cross-partition query
Max degree of parallelism

Result:

Before:

After:

Data

The Cosmos Db was filled with Sample data by using Data migration tool.

Azure Function with identity-based connections

Markus Meyer — Wed, 15 Jun 2022 07:11:54 +0000

1 Objective

2 Managed identity

3 Azure Table binding

Configure an identity-based connection

Some connections in Azure Functions can be configured to use an identity instead of a secret. Support depends on the extension using the connection. In some cases, a connection string may still be required in Functions even though the service to which you are connecting supports identity-based connections. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

Tutorial: Create a function app that connects to Azure services using identities instead of secrets

This tutorial shows you how to configure a function app using Azure Active Directory identities instead of secrets or connection strings, where possible. Using identities helps you avoid accidentally leaking sensitive secrets and can provide better visibility into how data is accessed.

Well, this is really awesome :-)

Please find the my complete code for an identity-based connection at

https://github.com/MarkusMeyer13/azure.functions.tables

1 Objective

Create an Azure Function with identity-based connections to AzureWebJobsStorage and a Table Storage.

2 Managed identity

Create an Azure Function with a managed identity:

The following script assigns the system-assigned managed identity to the new Azure Function app.

storageAccountFunction='strfunctionmm01'
resourceGroup='eval.table'
functionName='SampleFunctionMM01'

az appservice plan create --resource-group $resourceGroup --name 'samplePlan' 
az functionapp create --name $functionName --resource-group $resourceGroup --storage-account $storageAccountFunction --os-type Linux --functions-version 4 --plan 'samplePlan'

az functionapp identity assign --name $functionName --resource-group $resourceGroup

Created managed identity in Azure Function:

Retrieve the Ids for managed identity and storage account and assign the Storage Blob Data Contributor role.

functionManagedId=$(az functionapp identity show --name $functionName --resource-group $resourceGroup --query principalId -o tsv)

storageAccountFunctionId=$(az storage account list --resource-group $resourceGroup --query "[?name=='$storageAccountFunction'].id" -o tsv)
az role assignment create --role "Storage Blob Data Contributor" --scope $storageAccountFunctionId --assignee-principal-type ServicePrincipal --assignee-object-id $functionManagedId

The Storage Account with the assigned role:

The last step is to remove the default AzureWebJobsStorage configuration and set only the storage account name AzureWebJobsStorage__accountName:

az functionapp config appsettings delete --name $functionName --resource-group $resourceGroup --setting-names "AzureWebJobsStorage"
az functionapp config appsettings set --name $functionName --resource-group $resourceGroup --settings AzureWebJobsStorage__accountName=${storageAccountFunction}

No connection strings in the Azure Function configuration:

Edit the AzureWebJobsStorage configuration

Update the name from AzureWebJobsStorage to the exact name AzureWebJobsStorage__accountName. This setting tells the host to use the identity instead of looking for a stored secret. The new setting uses a double underscore (__), which is a special character in application settings.

3 Azure Table binding

The new Azure WebJobs Tables extension is used for the Azure Function binding:

The Azure Function shall add and delete entities in Table Storage.
The Table Storage is part of a different Storage Account than AzureWebJobsStorage. So the Connection has to be specified in the binding:

public static async Task<IActionResult> AddAsync(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "sample")] HttpRequest req,
    [Table("Sample", Connection = "SampleTableConnection")] TableClient client,
    ILogger log)
{
// ...
}

Grant permission to the identity - Azure Table API extension

Binding type	Example built-in roles (Azure Storage1)
Input binding	Storage Table Data Reader
Output binding	Storage Table Data Contributor

Therefore the managed identity has to be assigned with the Storage Table Data Contributor role for Azure Table Storage.

storageAccount='strsample'
resourceGroup='eval.table'
functionName='SampleFunctionMM01'

functionManagedId=$(az functionapp identity show --name $functionName --resource-group $resourceGroup --query principalId -o tsv)

storageAccountId=$(az storage account list --resource-group $resourceGroup --query "[?name=='$storageAccount'].id" -o tsv)
az role assignment create --role "Storage Table Data Contributor" --scope $storageAccountId --assignee-principal-type ServicePrincipal --assignee-object-id $functionManagedId

The assigned role Storage Table Data Contributor:

The naming convention for connection:

Using endpoint and token credential

<ConnectionName>__endpoint = https://...table.core.windows.net

tableEndpoint="https://$storageAccount.table.core.windows.net"
az functionapp config appsettings set --name $functionName --resource-group $resourceGroup --settings SampleTableConnection__endpoint=$tableEndpoint

Finally, all Azure Function settings do no longer contain connection strings:

Please get the complete code here:

git clone https://github.com/MarkusMeyer13/azure.functions.tables.git

Links

Azure services that can use managed identities to access other services

What’s new in the Azure Functions Tables extension for

Unit Test Azure Function with Table Extension in C#

Markus Meyer — Mon, 13 Jun 2022 14:04:54 +0000

1 Functions

2 Unit Tests

The new webjobs extensions can be used for Azure Table Storage CRUD operations with Azure Functions:

Add nuget package to your Azure Function

nuget.org: Microsoft.Azure.WebJobs.Extensions.Tables

dotnet add package Microsoft.Azure.WebJobs.Extensions.Tables

Please find the complete code at https://github.com/MarkusMeyer13/azure.functions.tables

1 Functions

Using the TableClient is straight forward.

AddEntityAsync

TableEntity with TableClient :

[FunctionName("Add")]
public static async Task<IActionResult> AddAsync(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "sample")] HttpRequest req,
    [Table("Sample", Connection = "SampleTableConnection")] TableClient client,
    ILogger log)
{
    var body = await req.ReadAsStringAsync().ConfigureAwait(false);

    var data = JObject.Parse(body);

    var entity = new TableEntity(data["Country"].Value<string>(), data["Company"].Value<string>())
    {
        ["Description"] = data["Description"].Value<string>()
    };

    var result = await client.AddEntityAsync(entity).ConfigureAwait(false);
    log.LogInformation($"Add - added");

    return new NoContentResult();
}

Request-Body:

{
    "Country": "Germany",
    "Company": "Lorem",
    "Description": "Ipsum"
}

DeleteEntityAsync

TableEntity with PartitionKey, RowKey and TableClient:

[FunctionName("Delete")]
public static async Task<IActionResult> DeleteAsync(
    [HttpTrigger(AuthorizationLevel.Function, "delete", Route = "sample/{partitionKey}/{rowKey}")] HttpRequest req,
    [Table("Sample", Connection = "SampleTableConnection")] TableClient client,
    string partitionKey,
    string rowKey,
    ILogger log)
{
    var result = await client.DeleteEntityAsync(partitionKey, rowKey).ConfigureAwait(false);
    log.LogInformation($"Delete - StatusCode: {result.Status}");
    log.LogInformation($"Delete - Content: {result.Content}");

    if (result.Status.Equals(404))
    {
        log.LogInformation($"Delete - not found");
        return new NotFoundResult();
    }

    log.LogInformation($"Delete - deleted");

    return new NoContentResult();
}

2 Unit Tests

The TableClient and the Azure.Response are mocked:

var mockResponse = new Mock<Azure.Response>();
mockResponse.SetupGet(x => x.Status).Returns((int)HttpStatusCode.NotFound);
mockResponse.SetupGet(x => x.Content).Returns(BinaryData.FromString("{\"odata.error\":{\"code\":\"ResourceNotFound\",\"message\":{\"lang\":\"en-US\",\"value\":\"The specified resource does not exist.\\nRequestId:19ab49c9-2002-001c-145f-7d77db000000\\nTime:2022-06-11T06:47:53.2893442Z\"}}}"));

Mock<TableClient> tableClient = new Mock<TableClient>();
tableClient.Setup(_ => _.DeleteEntityAsync(It.IsAny<string>(), It.IsAny<string>(), default, default))
    .ReturnsAsync(mockResponse.Object);

DeleteEntityAsync returns

StatusCode: 404
Content: {"odata.error":{"code":"ResourceNotFound","message":{"lang":"en-US","value":"The specified resource does not exist.\nRequestId:19ab49c9-2002-001c-145f-7d77db000000\nTime:2022-06-11T06:47:53.2893442Z"}}}

if the entity is not found.

DeleteEntityAsync returns no content

StatusCode: 204
Content:

if the entity is found.

VS Code - REST Client - WSL

Markus Meyer — Mon, 11 Jan 2021 11:44:09 +0000

Usually, I use Postman for doing REST requests.

But from time to time, Postman takes a long time to start or it crashes.

So I had a look into VS Code with REST Client.

It's straight forward to use it. Please find a short tutorial here.

I'm developing on my laptop and also on a VM.
The VM is required to access systems of the client that are running on-premise or in VNet in the cloud.

My local machine connects through VPN to VM.
Often, I do need to develop in the VM via RDP.
By using UnitTests and Mocks it's possible to do this on my local machine. I just need the repositories.

So, I'm not able to REST Client from my local machine, but I can use cURL.

On my VM (Windows 10), WSL is running.

I connect with ssh from my local machine to the VM.

ssh markusm@10...

Then I execute

wsl

From VS Code, I Copy Request as cURL:

And paste it into my terminal on my local machine.

Curl on WSL:

Azure VNet Peering

Markus Meyer — Sun, 03 Jan 2021 13:40:31 +0000

1 Current project situation

2 Hub and Spoke network

3 VNet Peering

4 Lab

4.1 Lab Topology

4.2 Lab VNet

4.2.1 Lab VNet Peering

4.3 Lab Functions

4.3.1 Lab Functions - VNet

4.3.2 Functions - Access Restrictions

4.4 Lab API Management

4.4.1 Lab API Management - VNet

4.5 Lab Data Flow and Requests

4.5.1 VM Cloud to On-Premise-Function

4.5.2 VM On-Premise to On-Premise-Function

4.5.3 VM Cloud to Cloud-Function

4.5.4 VM On-Premise to Cloud-Function

5 Code and Deployment

6 Further information

1 Current project situation

Our current project contains about 20 Azure Functions Apps in Premium Plan. These Functions Apps are connected with an Express Route to the On-Premise network and use a VNET subnet which is part of the On-Premise network.

This setup has a few drawbacks:

Based on the permissions, network changes can only be done by the company network group and not by the project group.
Because it's the same network, subnets and IP addresses are limited
Azure Function Apps running in a Premium Plan can scale out to 100 instances. Which means up to 100 IPs will be required for running the Azure Function Apps.

2 Hub and Spoke network

Implement a hub-spoke network topology on Azure

The hub is a virtual network in Azure that acts as a central point of connectivity to your on-premises network. The spokes are virtual networks that peer with the hub, and can be used to isolate workloads. Traffic flows between the on-premises datacenter and the hub through an ExpressRoute or VPN gateway connection.

Hub-spoke network topology in Azure

3 VNet Peering

With VNet Peering, Azure Virtual Networks can be connected:

Azure supports the following types of peering:

Virtual network peering: Connect virtual networks within the same Azure region.

Global virtual network peering: Connecting virtual networks across Azure regions.

4 Lab

For evaluation purpose, a lab has to be created with the following resources:

Azure Function Apps
Azure API Management
VNets
VMs
- for connection testing

All resources are deployed in the same region.

The lab simulates a Hub and Spoke network.
HTTP-Requests are made from VMs to test the data flow.

4.1 Lab Topology

The lab consists of two VNets:

vnet-cloud
- 172.16.0.0/16
- Spoke
vnet-on-premise
- 10.0.0.0/8
- Hub and simulates the On-Premise-Network
- simpler setup

API Management provides HTTP-Endpoints which forwards the requests to the Functions.

4.2 Lab VNet

vnet-cloud with three subnets:

snet-vnet-cloud-backends
- 172.16.64.0/19
- for VM for making Http-requests
snet-vnet-cloud-apim
- 172.16.252.0/22
- for API Management
snet-vnet-cloud-resources
- 172.16.32.0/19
- for Azure Function App

vnet-on-premise with two subnets:

snet-vnet-on-premise-backends
- 10.96.0.0/11
- for VM for making Http-requests
snet-vnet-on-premise
- 10.128.0.0/9
- for Azure Function App which represents a on-premise system

4.2.1 Lab VNet Peering

Both VNet Peerings are created with an ARM Template in the same subscription.
Please check the How-To Guide if you want to create VNet Peering in different Subscriptions or with different deployment models.

4.3 Lab Functions

Azure Functions networking options

VNet Integration depends on use of a dedicated subnet. When you provision a subnet, the Azure subnet loses 5 IPs for from the start.

Two Azure Functions Apps with HttpTrigger are deployed in the different VNets:

Function func-on-premise in VNET vnet-on-premise simualtes a On-Premise-System with Http-Endpoint.

4.3.1 Lab Functions - VNet

At least the Azure Function Premium Plan has to be used to configure Functions Apps with VNet integration.

The storage accounts are also part of the (VNet)[https://docs.microsoft.com/en-us/azure/storage/common/storage-network-security]:

4.3.2 Functions - Access Restrictions

Following Access Restrictions are configured for the Function App to allow only requests from API Management:

So, the Function App can only be accessed from Subnet snet-vnet-cloud-apim 172.16.252.0/22.

4.4 Lab API Management

API Management has one API with two operations which forwards the requests to the Azure Function Apps:

Policies:

/evaluation/cloud

cloud-function: https://func-cloud.azurewebsites.net/api

    <inbound>
        <base />
        <set-backend-service base-url="{{cloud-function}}" />
        <rewrite-uri template="/CloudTrigger" copy-unmatched-params="true" />
    </inbound>

/evaluation/onpremise:

on-premise-function: https://func-on-premise.azurewebsites.net/api

    <inbound>
        <base />
        <set-backend-service base-url="{{on-premise-function}}" />
        <rewrite-uri template="/OnPremiseTrigger" copy-unmatched-params="true" />
    </inbound>

4.4.1 Lab API Management - VNet

API Management is part of the VNet subnet snet-vnet-cloud-apim and deployed as an internal VNet.

4.5 Lab Data Flow and Requests

4.5.1 VM Cloud to On-Premise-Function

A request from the Cloud-VNet to API Management forwards the request to the Function in the On-Premise-VNet:

Mermaid

curl https://apim-eval-peering.azure-api.net/evaluation/onpremise

4.5.2 VM On-Premise to On-Premise-Function

A request from the On-Premise-VNet to API Management forwards the request to the Function in the On-Premise-VNet:

Mermaid

curl https://apim-eval-peering.azure-api.net/evaluation/onpremise

4.5.3 VM Cloud to Cloud-Function

A request from the Cloud-VNet to API Management forwards the request to the Function in the Cloud-VNet:

Mermaid

curl https://apim-eval-peering.azure-api.net/evaluation/cloud

4.5.4 VM On-Premise to Cloud-Function

A request from the On-Premise-VNet to API Management forwards the request to the Function in the Cloud-VNet:

Mermaid

curl https://apim-eval-peering.azure-api.net/evaluation/cloud

5 Code and Deployment

The entire code can be found in GitHub.

All the resources (Azure resources, Function Apps, VMs) can be deployed with a script:

bash deploy.sh

Deploy only Azure resources:

6 Further information

Choosing between Azure VNet Peering and VNet Gateways

VNet peering - connecting VNets within the same Azure region
Global VNet peering - connecting VNets across Azure regions

Enable containers to use Azure Virtual Network capabilities

Sync two CosmosDB collections with an Azure Function

Markus Meyer — Sat, 17 Oct 2020 11:35:40 +0000

1 Objective

2 Cosmos DB

3 Azure Function

4 Result

1 Objective

Data in the Cosmos DB has to be optimized for querying.
Therefore some best practices have to be considered.

Best practices for Azure Cosmos DB: Data modeling, Partitioning and RUs

Performance tips for Azure Cosmos DB and .NET SDK v2

An Azure Function will be used to automatically copy data from one Cosmos DB collection to another collection with a different PartitionKey.

2 Cosmos DB

The Cosmos DB collection is used to store customer data:

Customer:

{
    "id":"000001",
    "CustomerId":"000001",
    "EmailAddress":"user1@lorem.com",
    "Country": "Germany"
}

The Cosmos DB database has two collections for storing customer data:

2.1 Customer

One collection is optimized for query data by EmailAddress with PartitionKey /EmailAddress.
This is also the primary collection for storing the received data.

2.2 Customer-by-Country

This collection is optimized for query data by Country with PartitionKey /Country.

3 Azure Function

The Azure Functions has a CosmosDBTrigger. Every time a customer is created or updated in the collection customer, the Function will be triggered.

Attention: The Function will not be trigger if a customer was deleted!

The trigger is configured with customer collection.

The outbound binding uses an IAsyncCollector to add the received data to the collection customer_by_country.

FunctionCode:

public static class SyncCosmosDb
{
    [FunctionName(nameof(Sync))]
    public static void Sync(
        [CosmosDBTrigger(
                databaseName: "evaluation",
                collectionName: "customer",
                ConnectionStringSetting = "cosmos-mm-eval",
                LeaseCollectionName = "leases",
                CreateLeaseCollectionIfNotExists=true
            )]IReadOnlyList<dynamic> input,
        [CosmosDB(
                databaseName: "evaluation",
                collectionName: "customer-by-country",
                ConnectionStringSetting = "cosmos-mm-eval")] IAsyncCollector< dynamic> output,
        ILogger log)

    {

        foreach (var item in input)
        {
            output.AddAsync(item);
        }
    }
}

The Cosmos DB connection string has to be configured in local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AzureWebJobsDashboard": "UseDevelopmentStorage=true",
    "cosmos-mm-eval": "secret",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet"
  }
}

The complete solution can be found in my GitHub repository.

4 Result

Both collections contain the same data:

Collection customer:

Collection customer-by-country:

Create Azure API Management API Operation with Azure CLI

Markus Meyer — Wed, 14 Oct 2020 17:58:08 +0000

To create an Azure API Management API or Operation you have to use the current version of Azure CLI:

Install Azure CLI

Check installed version:

az --version

Install or update Azure CLI

Login

Before creating the API you have to be logged in. Maybe you have to select the correct tenant.

az login

Script

Please find the Microsoft documentation here:

az apim api create

az apim api operation create

The script requires an existing API Management:

$resourceGroupName = "eval.datatransformation"
$serviceName = "mm-sample"
$apiId="lorem-ipsum"
$apiDisplayName="Lorem Ipsum"
$apiId="Lorem"
$apiPath="/lorem-ipsum"
$operationPath="/"
$operationDisplayName="Get"
$operationDescription="Gets the data"

az login

# create the API
az apim api create --service-name $serviceName  -g $resourceGroupName --api-id $apiId --path $apiPath --display-name $apiDisplayName

# create the Operation
az apim api operation create --service-name $serviceName  -g $resourceGroupName --api-id $apiId --url-template $operationPath --method "GET" --display-name $operationDisplayName --description $operationDescription

Result

The API and operation is created:

Deploy ASP.NET Core Web App to Azure with GitHub Actions

Markus Meyer — Mon, 12 Oct 2020 03:24:19 +0000

1 Objective

2 Create app

3 Repository

4 Setup Azure Environment

5 GitHub Actions

5.1 GitHub Actions - Deployment

6 Result

1 Objective

For learning purposes, I want to create a simple ASP.NET Core app and deploy it.
The focus is on GitHub Actions to deploy the app to Azure.

2 Create app

Create a new directory for your app.
E.g. HelloHappyCodingWeb

Run the following command to create the web app:

dotnet new web

You can edit the source code in Visual Studio Code:

I made modified the Startup.cs to have my own Hello World ;-)

Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGet("/", async context =>
        {
            await context.Response.WriteAsync("Hello Happy Coding!");
        });
    });
}

To test the app, run the following command, and open the Url in your browser:

dotnet run

Output:

Now listening on: http://localhost:5000

3 Repository

Create a repository in Github. In my case, I named it HelloHappyCodingWeb.
So I got the following remote Url:

https://github.com/MarkusMeyer13/HelloHappyCodingWeb.git

If you did not specify any .gitignore during the creation process of your GitHub repository, you can add the default Visual Studio .gitignore by using curl.
Add .gitignore:

curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/master/VisualStudio.gitignore

Prepare your local folder for git and commit all your files:

git init
git add .
git commit -m "Initial"

To connect to your newly created GitHub repository, the following commands have to be executed:

git remote add origin https://github.com/MarkusMeyer13/HelloHappyCodingWeb.git
git push --set-upstream origin  master

4 Setup Azure Environment

As a prerequisite for the deployment, the Azure App Service has to exist.

This can be done in various ways. I will use Azure CLI.

az login

The following script creates a Resource Group with the App Service Plan and the App Service for hosting the app.

$rg = "HappyCoding"
$appPlan = "HappyCodingPlan"
$appName = "happycoding-mm"
az group create -l westeurope -n $rg
az appservice plan create -g $rg -n $appPlan
az webapp create --resource-group $rg --plan $appPlan --name $appName --runtime "DOTNETCORE|3.1"

If you are using PowerShell, you have to escape the runtime value with additional single quotes:

az  webapp create --resource-group $rg --plan $appPlan --name $appName --runtime '"DOTNETCORE|3.1"'

PowerShell Core:

Finally, the Resource Group with the App Service Plan and the App Service is created:

Please find additional documentation at Microsoft:

Create the App Service

az group create

az appservice plan create

az webapp create

5 GitHub Actions

GitHub Actions automates building, testing and deployments.

A GitHub Action can simply be created by clicking the Actions tab and start with an existing workflow.

In this case, the proposed workflow .NET Core can be used to build the app.

GitHub Actions workflows are defined with YAML.

dotnet-core.yml:

name: .NET Core

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.301
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --configuration Release --no-restore
    - name: Test
      run: dotnet test --no-restore --verbosity normal

5.1 GitHub Actions - Deployment

To deploy the app, the existing YAML has to be extended.

App Name

The app name, which was used to create the Azure App Service has to be set as an environment variable:

env:
  AZURE_WEBAPP_NAME: happycoding-mm    # set this to your application's name

This variable will be used in the deployment step:

    - name: 'Deploy to Azure WebApp'
      uses: azure/webapps-deploy@v2
      with:
        app-name: ${{ env.AZURE_WEBAPP_NAME }}
        publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
        package: './dotnetcorewebapp'

Authenticate deployment in Azure

A publish-profile is used to set the connection to Azure.
It's bad practice to store secrets (in this case the Publishing Profile) in a repository.
So the Publishing Profile has to be configured as GitHub Secret.

Before creating the secret the Publishing Profile has to be download from the Azure App Service Overview blade:

The content of the file has to inserted as secret value for AZURE_WEBAPP_PUBLISH_PROFILE:

Complete dotnet-core.yml:

name: .NET Core

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
env:
  AZURE_WEBAPP_NAME: happycoding-mm    # set this to your application's name

jobs:
  build-and-deploy:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.100-rc.1.20452.10
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --configuration Release --no-restore
    - name: Test
      run: dotnet test --no-restore --verbosity normal
    - name: dotnet publish
      run: |
        dotnet publish -c Release -o dotnetcorewebapp 
    - name: 'Deploy to Azure WebApp'
      uses: azure/webapps-deploy@v2
      with:
        app-name: ${{ env.AZURE_WEBAPP_NAME }}
        publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
        package: './dotnetcorewebapp'

That's all. Any commit in the master branch will trigger this workflow and deploy the app to Azure.

6 Result

After the successful deployment, the app is available in Azure:

https://happycoding-mm.azurewebsites.net/

App running on Azure:

The complete source code can be found in my GitHub Repository.

Please have a look at the Microsoft documentation:

Quickstart: Create an ASP.NET Core web app in Azure

Expose SOAP service in Azure API Management and store data in Blob

Markus Meyer — Sat, 26 Sep 2020 08:53:37 +0000

Liquid syntax error: 'raw' tag was never closed

Forem: Markus Meyer

How to create an Azure API Management Service with Developer Portal with CI/CD using Azure DevOps

Table of Contents

Prerequisites

Step 1: Create an Azure API Management Service

Configure App Insights

Step 2: Set Up the App Registration for the Developer Portal

Create App Registration

Create client secret

Configure authentication

Grant permissions

Step 3: Register the app registration with the API Management service

Complete Code

Bicep API Management service

Bicep API Management Developer Portal

Powershell

Pipeline

Deploying OpenAPI in Azure API Management with Terraform

Table of Contents

1 Terraform

2 Create API

3 Update API

API Management - Convert SOAP POST to GET

Import SOAP Service

The target API

Transform POST to GET

Result

Cosmos Db - Increase the paging result size

Settings

Result:

Data

Azure Function with identity-based connections

Table of Contents

1 Objective

2 Managed identity

3 Azure Table binding

Links

Unit Test Azure Function with Table Extension in C#

Table of Contents

1 Functions

AddEntityAsync

DeleteEntityAsync

2 Unit Tests

VS Code - REST Client - WSL

Azure VNet Peering

Table of Contents

1 Current project situation

2 Hub and Spoke network

3 VNet Peering

4 Lab

4.1 Lab Topology

4.2 Lab VNet

4.2.1 Lab VNet Peering

4.3 Lab Functions

4.3.1 Lab Functions - VNet

4.3.2 Functions - Access Restrictions

4.4 Lab API Management

4.4.1 Lab API Management - VNet

4.5 Lab Data Flow and Requests

4.5.1 VM Cloud to On-Premise-Function

4.5.2 VM On-Premise to On-Premise-Function

4.5.3 VM Cloud to Cloud-Function

4.5.4 VM On-Premise to Cloud-Function

5 Code and Deployment

6 Further information

Sync two CosmosDB collections with an Azure Function

Table of Contents

1 Objective

2 Cosmos DB

2.1 Customer

2.2 Customer-by-Country

3 Azure Function

4 Result

Create Azure API Management API Operation with Azure CLI

Install Azure CLI

Login

Script

Result

Deploy ASP.NET Core Web App to Azure with GitHub Actions

Table of Contents