Skip to content

Latest commit

 

History

History
407 lines (351 loc) · 24.6 KB

File metadata and controls

407 lines (351 loc) · 24.6 KB

Table of Contents

  1. Creator
  2. Extractor

Creator

This utility creates Resource Manager templates for an API based on the OpenAPI Specification of the API. Optionally, you can provide policies you wish to apply to the API and its operations in seperate files.

Create the Config File

The utility requires one argument, --configFile, which points to a yaml file that controls the ARM templates generated by the Creator tool. The file contains a Creator Configuration object whose schema and related schemas are listed below:

Creator Configuration

Property Type Required Value
version string Yes Configuration version.
apimServiceName string Yes Name of the APIM service to deploy resources into.
policy string No Location of the global service policy XML file. Can be url or local file.
apiVersionSets Array<APIVersionSetConfiguration> No List of API Version Set configurations.
apis Array<APIConfiguration> Yes List of API configurations.
products Array<ProductConfiguration> No List of Product configurations.
loggers Array<LoggerConfiguration> No List of Logger configurations.
authorizationServers Array<AuthorizationServerContractProperties> No List of Authorization Server configurations.
backends Array<BackendContractProperties> No List of Backend configurations.
outputLocation string Yes Local folder the utility will write templates to.
linked boolean No Determines whether the utility should create a master template that links to all generated templates.
linkedTemplatesBaseUrl string No Location that stores linked templates. Required if 'linked' is set to true.
linkedTemplatesUrlQueryString string No Query string appended to linked templates uris that enables retrieval from private storage.
tags Array<TagConfiguration> No List of Tags configurations.
subscriptionKeyParameterNames APITemplateSubscriptionKeyParameterNames No subscription key parameter name.

APIConfiguration

Property Type Required Value
name string Yes API identifier. Must be unique in the current API Management service instance.
description string No Description of the API.
serviceUrl string No Absolute URL of the backend service implementing this API.
type enum No Type of API. - http or soap
openApiSpec string Yes Location of the Open API Spec file. Can be url or local file.
policy string No Location of the API policy XML file. Can be url or local file.
suffix string Yes Relative URL uniquely identifying this API and all of its resource paths within the API Management service instance. It is appended to the API endpoint base URL specified during the service instance creation to form a public URL for this API.
subscriptionRequired boolean No Specifies whether an API or Product subscription is required for accessing the API.
isCurrent boolean No Indicates if API revision is current api revision.
apiVersion string No Indicates the Version identifier of the API if the API is versioned.
apiVersionDescription string No Description of the API Version.
apiRevision string No Describes the Revision of the API. If no value is provided, default revision 1 is created.
apiRevisionDescription string No Description of the Api Revision.
apiVersionSetId string No A resource identifier for the related ApiVersionSet. Value must match the resource id on an existing version set and is irrelevant if the apiVersionSet property is supplied.
operations Dictionary<string, APIOperationPolicyConfiguration> No XML policies that will be applied to operations within the API. Keys must match the operationId property of one of the API's operations.
authenticationSettings AuthenticationSettingsContract No Collection of authentication settings included into this API.
products string No Comma separated list of existing products to associate the API with.
protocols string No Comma separated list of protocols used between client and APIM service.
diagnostic APIDiagnosticConfiguration No Diagnostic configuration.
tags string No Comma separated list of tags to associate the API with. Tags can be existing or nonexisting. For nonexisting tags, it will automatically generate new tags on the API instance

APIOperationPolicyConfiguration

Property Type Required Value
policy string Yes Location of the operation policy XML file. Can be url or local file.

APIDiagnosticConfiguration

Property Type Required Value
name enum No Name of API Diagnostic - azureEventHub or applicationInsights

Additional properties found in DiagnosticContractProperties

APIVersionSetConfiguration

Property Type Required Value
id string No ID of the API Version Set.

Additional properties found in ApiVersionSetContractProperties

ProductConfiguration

Property Type Required Value
policy string No Location of the Product policy XML file. Can be url or local file.

Additional properties found in ProductContractProperties

LoggerConfiguration

Property Type Required Value
name string Yes Name of the Logger

Additional properties found in LoggerContractProperties

TagConfiguration

Property Type Required Value
displayName string Yes DisplayName and name of the tag

Additional properties found in TagContractProperties

APITemplateSubscriptionKeyParameterNames

Property Type Required Value
header string Yes header name of the subscription.
query string Yes query parameter name of the subscription.

Additional properties found in APITemplateSubscriptionKeyParameterNames

Sample Config File

The following is a full config.yml file with each property listed:

version: 0.0.1
apimServiceName: myAPIMService
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFiles\XMLPolicies\globalServicePolicy.xml
apiVersionSets:
    - id: myAPIVersionSetID
      displayName: swaggerPetstoreVersionSetLinked
      description: a description
      versioningScheme: Query
      versionQueryName: versionQuery
      versionHeaderName: versionHeader
    - id: secondAPIVersionSetID
      displayName: secondSet
      description: another description
      versioningScheme: Header
      versionQueryName: versionQuery
      versionHeaderName: versionHeader
apis:
    - name: myAPI
      type: http
      description: myFirstAPI
      serviceUrl: http://myApiBackendUrl.com
      openApiSpec: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\OpenApiSpecs\swaggerPetstore.json
      policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFiles\XMLPolicies\apiPolicyHeaders.xml
      suffix: conf
      subscriptionRequired: true
      isCurrent: true
      apiVersion: v1
      apiVersionDescription: My first version
      apiVersionSetId: myAPIVersionSetID
      apiRevision: 1
      apiRevisionDescription: My first revision 
      products: myProduct   
      tags: Universe, myTag
      operations:
        addPet:
          policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\operationRateLimit.xml
        deletePet:
          policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\operationRateLimit.xml
      products: starter, platinum
      authenticationSettings:
        oAuth2:
            authorizationServerId: myAuthServer
            scope: myScope
      diagnostic:
        name: applicationinsights
        alwaysLog: allErrors
        loggerId: myAppInsights
        sampling:
          samplingType: fixed
          percentage: 50
        frontend: 
          request:
            headers:
            body: 
              bytes: 512
          response: 
            headers:
            body: 
              bytes: 512
        backend: 
          request:
            headers:
            body: 
              bytes: 512
          response: 
            headers:
            body: 
              bytes: 512
        enableHttpCorrelationHeaders: true
products:
    - displayName: platinum
      description: a test product
      terms: some terms
      subscriptionRequired: true
      approvalRequired: true
      subscriptionsLimit: 1
      state: notPublished
      policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\productSetBodyBasic.xml
tags:
    - displayName: Universe
loggers:
    - name: myAppInsights
      loggerType: applicationInsights
      description: a test app insights
      credentials:
        instrumentationKey: 45d4v88-fdfs-4b35-9232-731d82d4d1c6
      isBuffered: true
authorizationServers:
    - displayName: myAuthServer
      description: test server
      clientRegistrationEndpoint: https://www.contoso.com/apps
      authorizationEndpoint: https://www.contoso.com/oauth2/auth
      authorizationMethods:
        - GET
      tokenEndpoint: https://www.contoso.com/oauth2/token
      supportState: true
      defaultScope: read write
      grantTypes:
        - authorizationCode
        - implicit
      bearerTokenSendingMethods:
        - authorizationHeader
      clientId: 1
      clientSecret: 2
      resourceOwnerUsername: un
      resourceOwnerPassword: pwd
backends:
    - title: myBackend
      description: description5308
      url: https://backendname2644/
      protocol: http
      credentials:
        query: 
          sv: 
            - xx
            - bb
        header: 
          x-my-1:
            - val1
            - val2
        authorization: 
          scheme: Basic
          parameter: opensesma
      proxy:
        url: http://192.168.1.1:8080
        username: Contoso\admin
        password: opensesame
      tls:
        validateCertificateChain: false
        validateCertificateName: false
outputLocation: C:\Users\myUsername\GeneratedTemplates
linked: false
linkedTemplatesBaseUrl : https://mystorageaccount.blob.core.windows.net/mycontainer
linkedTemplatesUrlQueryString : ?sv=2018-03-28&ss=bfqt&srt=sco&sp=rwdlacup&se=2019-12-22T23:12:53Z&st=2019-09-09T14:12:53Z&spr=https&sig=uFTldJEYPH888QVzKb7q7eLq0Xt%2Bu35UTqpFGUYo6uc%3D

Running the Creator

Below are the steps to run the Creator from the source code:

  • Clone this repository and restore its packages using dotnet restore
  • Navigate to {path_to_folder}/src/APIM_ARMTemplate/apimtemplate directory
  • Run the following command: dotnet run create --configFile CONFIG_YAML_FILE_LOCATION

You can also run it directly from the releases.

Extractor

This utility generates Resource Manager templates by extracting existing configurations of one or more APIs in an API Management instance.

Prerequisite

To be able to run the Extractor, you would first need to install the Azure CLI.

Running the Extractor

Below are the steps to run the Extractor from the source code:

  • Clone this repository and navigate to {path_to_folder}/src/APIM_ARMTemplate/apimtemplate
  • Restore its packages using dotnet restore
  • Make sure you have signed in using Azure CLI and have switched to the subscription containing the API Management instance from which the configurations will be extracted.
az login
az account set --subscription <subscription_id>

Extractor Arguments

You have two choices when specifying your settings:

  1. By using a json file with key-values where the keys matches the table below. Use the extractorConfig argument: extract --extractorConfig c:/temp/extractSettings.json. See more examples.
  2. Pass the arguments on the command line. For instance extract --sourceApimName my-feature-apim --destinationApimName company-stable-apim --resourceGroup my-feature-rg --fileFolder c:\temp\apim-extract --apiName MyFeatureV1Api.
Property Required Value
sourceApimName Yes Name of the source APIM instance.
destinationApimName Yes Name of the destination APIM instance.
resourceGroup Yes Name of the resource group.
fileFolder Yes Path to output folder
apiName No Name of API. If provided, Extractor executes single API extraction. Otherwise, Extractor executes full extraction. Note: This is the "Name" value as seen in the API settings, not "Display Name" and is case sensitive.
linkedTemplatesBaseUrl No Linked templates remote location. If provided, Extractor generates master template and requires linked templates pushed to remote location.
linkedTemplatesUrlQueryString No Query string appended to linked templates uris that enables retrieval from private storage.
linkedTemplatesSasToken No String appended to end of the linked templates uris that enables adding a SAS token or other query parameters.
policyXMLBaseUrl No Policy XML files remote location. If provided, Extractor generates policies folder with xml files, and requires they be pushed to remote location.
splitAPIs No If set to "true", then generate multiple api folders, each api will have a seperate folder, with a separate master template to deploy this api. If this single api has a version set, then a version set folder will generate instead, then all apis that belongs to this version set will be included in the version set folder, apis in this version set can be deployed separately using every api's master template, or they can be deployed together using the master template in "VersionSetMasterFolder" folder
apiVersionSetName No Name of the APIVersionSet. If provided, extract all apis within this apiversionset. It will generate seperate folder for each api and also a master folder to link all apis in this apiversionset
mutipleAPIs No Specify multiple APIs to extract. Generate templates for each API, also generate an aggregated templates folder to deploy these APIs together at a time
includeAllRevisions No Set to "true" will extract all revisions for the single API. Will work only with "apiName" paramter, where you specify which API's revisions to extract. Generate templates for each revision, also generate an aggregated master folder to deploy these revisions together at one time. Note: there are many complicated issues with deploying revisions, make sure your deployment won't overwrite or break the existing ones

Note

  • Can not use "splitAPIs" and "apiName" at the same time, since using "apiName" only extract one API
  • Can not use "apiName" and "mutipleAPIs" at the same time
  • Can only "includeAllRevisions" with "apiName"

Extractor Parameter File Example

Executing a single API extraction with linked templates and policy file generation, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "apiName": "<api_name>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>"
}

Extract all APIs with linked templates linking all apis and policy file, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>"
}

Extract all APIs with seperated api folders, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>",
    "splitAPIs": "true"
}

Extract all APIs within an apiversionset, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>",
    "apiVersionSetName": "<api-version-set-name>"
}

Extract single API with all revisions, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>",
    "apiName": "<api_name>",
    "includeAllRevisions": "true"
}

Extract multiple APIs, use the following parameters:

{
    "sourceApimName": "<source-apim-name>",
    "destinationApimName": "<destination-apim-name>",
    "resourceGroup": "<resource-group>",
    "fileFolder": "<destination-file-folder>",
    "linkedTemplatesBaseUrl": "<linked_templates_remote_location>",
    "policyXMLBaseUrl": "<policies_remote_location>",
    "mutipleAPIs": "api1, api2, api3"
}

Run the extractor

dotnet run extract

You can also run it directly from the releases.