Skip to content
This repository was archived by the owner on Feb 23, 2024. It is now read-only.

Commit 65a5665

Browse files
lucashuet93lucashuet93
committed
update creator readme
1 parent 9e9a91d commit 65a5665

File tree

3 files changed

+171
-87
lines changed

3 files changed

+171
-87
lines changed

‎src/APIM_ARMTemplate/README.md

Lines changed: 168 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -14,50 +14,46 @@ This utility creates [Resource Manager templates](https://docs.microsoft.com/en-
1414

1515
## Create the Config File
1616

17-
The utility requires one argument, --configFile, which points to a yaml file that links to policy and Open API Spec files and on which the entire process is dependent. The file contains a Creator Configuration object whose schema and related schemas are listed below:
18-
19-
### Schemas
17+
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:
2018

2119
#### Creator Configuration
2220

2321
| Property | Type | Required | Value |
2422
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
2523
| version | string | Yes | Configuration version. |
26-
| apimServiceName | string | Yes | Name of APIM service to deploy resources into. |
27-
| apiVersionSet | [APIVersionSetConfiguration](#APIVersionSetConfiguration) | No | VersionSet configuration. |
28-
| api | [APIConfiguration](#APIConfiguration) | Yes | API configuration. |
24+
| apimServiceName | string | Yes | Name of the APIM service to deploy resources into. |
25+
| apiVersionSets | Array<[APIVersionSetConfiguration](#APIVersionSetConfiguration)> | No | List of API Version Set configurations. |
26+
| apis | Array<[APIConfiguration](#APIConfiguration)> | Yes | List of API configurations. |
27+
| products | Array<[ProductConfiguration](#ProductConfiguration)> | No | List of Product configurations. |
28+
| loggers | Array<[LoggerConfiguration](#LoggerConfiguration)> | No | List of Logger configurations. |
29+
| authorizationServers | Array<[AuthorizationServerContractProperties](#https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/authorizationservers#AuthorizationServerContractProperties)> | No | List of Authorization Server configurations. |
30+
| backends | Array<[BackendContractProperties](#https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/backends#BackendContractProperties)> | No | List of Backend configurations. |
2931
| outputLocation | string | Yes | Local folder the utility will write templates to. |
3032
| linked | boolean | No | Determines whether the utility should create a master template that links to all generated templates. |
3133
| linkedTemplatesBaseUrl| string | No | Location that stores linked templates. Required if 'linked' is set to true. |
3234

33-
#### APIVersionSetConfiguration
34-
35-
| Property | Type | Required | Value |
36-
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
37-
| id | string | No | ID of the API Version Set. |
38-
| displayName | string | Yes | Name of API Version Set. |
39-
| description | string | No | Description of API Version Set. |
40-
| versioningScheme | enum | Yes | A value that determines where the API Version identifer will be located in a HTTP request. - Segment, Query, Header |
41-
| versionQueryName | string | No | Name of query parameter that indicates the API Version if versioningScheme is set to query. |
42-
| versionHeaderName | string | No | Name of HTTP header parameter that indicates the API Version if versioningScheme is set to header. |
43-
4435
#### APIConfiguration
4536

4637
| Property | Type | Required | Value |
4738
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
4839
| name | string | Yes | API identifier. Must be unique in the current API Management service instance. |
40+
| description | string | No | Description of the API. |
41+
| serviceUrl | string | No | Absolute URL of the backend service implementing this API. |
42+
| type | enum | No | Type of API. - http or soap |
4943
| openApiSpec | string | Yes | Location of the Open API Spec file. Can be url or local file. |
5044
| policy | string | No | Location of the API policy XML file. Can be url or local file. |
5145
| 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. |
5246
| subscriptionRequired | boolean | No | Specifies whether an API or Product subscription is required for accessing the API. |
47+
| isCurrent | boolean | No | Indicates if API revision is current api revision. |
5348
| apiVersion | string | No | Indicates the Version identifier of the API if the API is versioned. |
54-
| apiVersionDescription | string | No | Description of the Api Version. |
55-
| revision | string | No | Describes the Revision of the Api. If no value is provided, default revision 1 is created. |
56-
| revisionDescription | string | No | Description of the Api Revision. |
49+
| apiVersionDescription | string | No | Description of the API Version. |
50+
| apiRevision | string | No | Describes the Revision of the API. If no value is provided, default revision 1 is created. |
51+
| apiRevisionDescription| string | No | Description of the Api Revision. |
5752
| 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. |
5853
| operations | Dictionary<string, [APIOperationPolicyConfiguration](#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. |
5954
| authenticationSettings| [AuthenticationSettingsContract](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2018-06-01-preview/service/apis#AuthenticationSettingsContract) | No | Collection of authentication settings included into this API. |
6055
| products | string | No | Comma separated list of existing products to associate the API with. |
56+
| protocols | string | No | Comma separated list of protocols used between client and APIM service. |
6157
| diagnostic | [APIDiagnosticConfiguration](#APIDiagnosticConfiguration) | No | Diagnostic configuration. |
6258

6359
#### APIOperationPolicyConfiguration
@@ -71,77 +67,165 @@ The utility requires one argument, --configFile, which points to a yaml file tha
7167
| Property | Type | Required | Value |
7268
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
7369
| name | enum | No | Name of API Diagnostic - azureEventHub or applicationInsights |
74-
| alwaysLog | enum | No | Specifies for what type of messages sampling settings should not apply. - allErrors |
75-
| loggerId | string | Yes | Resource Id of an existing target logger. |
76-
| sampling | object | No | Sampling settings for Diagnostic. - [SamplingSettings object](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2018-06-01-preview/service/apis/diagnostics#SamplingSettings) |
77-
| frontend | object | No | Diagnostic settings for incoming/outgoing HTTP messages to the Gateway. - [PipelineDiagnosticSettings object](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2018-06-01-preview/service/apis/diagnostics#PipelineDiagnosticSettings) |
78-
| backend | object | No | Diagnostic settings for incoming/outgoing HTTP messages to the Backend - [PipelineDiagnosticSettings object](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2018-06-01-preview/service/apis/diagnostics#PipelineDiagnosticSettings) |
79-
| enableHttpCorrelationHeaders | boolean | No | Whether to process Correlation Headers coming to Api Management Service. Only applicable to Application Insights diagnostics. Default is true. |
70+
71+
_Additional properties found in [DiagnosticContractProperties](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/apis/diagnostics#DiagnosticContractProperties)_
72+
73+
#### APIVersionSetConfiguration
74+
75+
| Property | Type | Required | Value |
76+
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
77+
| id | string | No | ID of the API Version Set. |
78+
79+
_Additional properties found in [ApiVersionSetContractProperties](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/apiversionsets#ApiVersionSetContractProperties)_
80+
81+
#### ProductConfiguration
82+
83+
| Property | Type | Required | Value |
84+
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
85+
| policy | string | No | Location of the Product policy XML file. Can be url or local file. |
86+
87+
_Additional properties found in [ProductContractProperties](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/products#ProductContractProperties)_
88+
89+
#### LoggerConfiguration
90+
91+
| Property | Type | Required | Value |
92+
|-----------------------|-----------------------|-----------------------|--------------------------------------------------|
93+
| name | string | Yes | Name of the Logger |
94+
95+
_Additional properties found in [LoggerContractProperties](https://docs.microsoft.com/en-us/azure/templates/microsoft.apimanagement/2019-01-01/service/loggers#LoggerContractProperties)_
8096

8197
### Sample Config File
8298

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

85101
```
86102
version: 0.0.1
87-
apimServiceName: MyAPIMService
88-
apiVersionSet:
89-
id: myAPIVersionSetID
90-
displayName: myAPIVersionSet
91-
description: a description
92-
versioningScheme: Query
93-
versionQueryName: versionQuery
94-
versionHeaderName: versionHeader
95-
api:
96-
name: myAPI
97-
openApiSpec: ./swaggerPetstore.json
98-
policy: ./apiPolicyHeaders.xml
99-
suffix: conf
100-
subscriptionRequired: true
101-
apiVersion: v1
102-
apiVersionDescription: My first version
103-
revision: 1
104-
revisionDescription: My first revision
105-
#apiVersionSetId: myID
106-
operations:
107-
addPet:
108-
policy:
109-
deletePet:
110-
policy:
111-
authenticationSettings:
112-
subscriptionKeyRequired: false
113-
oAuth2:
114-
authorizationServerId: serverId
115-
scope: scope
116-
products: starter, platinum
117-
diagnostic:
118-
name: applicationinsights
119-
alwaysLog: allErrors
120-
loggerId: /subscriptions/24de26c5-cf48-4954-8400-013fe61042wd/resourceGroups/MyResourceGroup/providers/Microsoft.ApiManagement/service/MyAPIMService/loggers/myappinsights,
121-
sampling:
122-
samplingType: fixed
123-
percentage: 50
124-
frontend:
125-
request:
126-
headers:
127-
body:
128-
bytes: 512
129-
response:
130-
headers:
131-
body:
132-
bytes: 512
133-
backend:
134-
request:
135-
headers:
136-
body:
137-
bytes: 512
138-
response:
139-
headers:
140-
body:
141-
bytes: 512
142-
enableHttpCorrelationHeaders: true
143-
outputLocation: C:\Users\user1\Desktop\GeneratedTemplates
144-
linked: true
103+
apimServiceName: myAPIMService
104+
apiVersionSets:
105+
- id: myAPIVersionSetID
106+
displayName: swaggerPetstoreVersionSetLinked
107+
description: a description
108+
versioningScheme: Query
109+
versionQueryName: versionQuery
110+
versionHeaderName: versionHeader
111+
- id: secondAPIVersionSetID
112+
displayName: secondSet
113+
description: another description
114+
versioningScheme: Header
115+
versionQueryName: versionQuery
116+
versionHeaderName: versionHeader
117+
apis:
118+
- name: myAPI
119+
type: http
120+
description: myFirstAPI
121+
serviceUrl: http://myApiBackendUrl.com
122+
openApiSpec: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\OpenApiSpecs\swaggerPetstore.json
123+
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFiles\XMLPolicies\apiPolicyHeaders.xml
124+
suffix: conf
125+
subscriptionRequired: true
126+
isCurrent: true
127+
apiVersion: v1
128+
apiVersionDescription: My first version
129+
apiVersionSetId: myAPIVersionSetID
130+
apiRevision: 1
131+
apiRevisionDescription: My first revision
132+
operations:
133+
addPet:
134+
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\operationRateLimit.xml
135+
deletePet:
136+
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\operationRateLimit.xml
137+
products: starter, platinum
138+
authenticationSettings:
139+
oAuth2:
140+
authorizationServerId: myAuthServer
141+
scope: myScope
142+
diagnostic:
143+
name: applicationinsights
144+
alwaysLog: allErrors
145+
loggerId: myAppInsights
146+
sampling:
147+
samplingType: fixed
148+
percentage: 50
149+
frontend:
150+
request:
151+
headers:
152+
body:
153+
bytes: 512
154+
response:
155+
headers:
156+
body:
157+
bytes: 512
158+
backend:
159+
request:
160+
headers:
161+
body:
162+
bytes: 512
163+
response:
164+
headers:
165+
body:
166+
bytes: 512
167+
enableHttpCorrelationHeaders: true
168+
products:
169+
- displayName: platinum
170+
description: a test product
171+
terms: some terms
172+
subscriptionRequired: true
173+
approvalRequired: true
174+
subscriptionsLimit: 1
175+
state: notPublished
176+
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\productSetBodyBasic.xml
177+
loggers:
178+
- name: myAppInsights
179+
loggerType: applicationInsights
180+
description: a test app insights
181+
credentials:
182+
instrumentationKey: 45d4v88-fdfs-4b35-9232-731d82d4d1c6
183+
isBuffered: true
184+
authorizationServers:
185+
- displayName: myAuthServer
186+
description: test server
187+
clientRegistrationEndpoint: https://www.contoso.com/apps
188+
authorizationEndpoint: https://www.contoso.com/oauth2/auth
189+
authorizationMethods:
190+
- GET
191+
tokenEndpoint: https://www.contoso.com/oauth2/token
192+
supportState: true
193+
defaultScope: read write
194+
grantTypes:
195+
- authorizationCode
196+
- implicit
197+
bearerTokenSendingMethods:
198+
- authorizationHeader
199+
clientId: 1
200+
clientSecret: 2
201+
resourceOwnerUsername: un
202+
resourceOwnerPassword: pwd
203+
backends:
204+
- title: myBackend
205+
description: description5308
206+
url: https://backendname2644/
207+
protocol: http
208+
credentials:
209+
query:
210+
sv:
211+
- xx
212+
- bb
213+
header:
214+
x-my-1:
215+
- val1
216+
- val2
217+
authorization:
218+
scheme: Basic
219+
parameter: opensesma
220+
proxy:
221+
url: http://192.168.1.1:8080
222+
username: Contoso\admin
223+
password: opensesame
224+
tls:
225+
validateCertificateChain: false
226+
validateCertificateName: false
227+
outputLocation: C:\Users\myUsername\GeneratedTemplates
228+
linked: false
145229
linkedTemplatesBaseUrl : https://mystorageaccount.blob.core.windows.net/mycontainer
146230
```
147231

‎src/APIM_ARMTemplate/apimtemplate/Creator/ExampleFiles/YAMLConfigs/valid.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ apis:
4141
diagnostic:
4242
name: applicationinsights
4343
alwaysLog: allErrors
44-
loggerId: lucastestai
44+
loggerId: myAppInsights
4545
sampling:
4646
samplingType: fixed
4747
percentage: 50
@@ -72,7 +72,7 @@ products:
7272
approvalRequired: true
7373
subscriptionsLimit: 1
7474
state: notPublished
75-
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\productSetBodyBasic.xml # Optional, can be url or local file
75+
policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\XMLPolicies\productSetBodyBasic.xml
7676
loggers:
7777
- name: myAppInsights
7878
loggerType: applicationInsights

‎src/APIM_ARMTemplate/apimtemplate/Properties/launchSettings.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"profiles": {
33
"apimtemplate": {
44
"commandName": "Project",
5-
"commandLineArgs": "create --configFile ./Creator/ExampleFiles/YAMLConfigs/validTesting.yml"
5+
"commandLineArgs": "extract --sourceApimName LucasBlankLinked --destinationApimName LucasBlankUnlinked --resourceGroup LucasHuetHudsonInternal --fileFolder C:\\\\Users\\\\lucashh\\\\Desktop\\\\Projects\\\\APIM-ARM\\\\GeneratedTemplates\\\\Extractor\\\\SingleAPI --apiName firstAPI --policyXMLBaseUrl https://lucasarmtemplates.blob.core.windows.net/policies"
66
}
77
}
88
}

0 commit comments

Comments
 (0)