Définir la version et la révision avec Azure API Management

📅2019/12/06👤mark241⏱️3 min

Cet article a été publié il y a plus d'un an. Les informations peuvent être obsolètes.

Cet article décrit comment ajouter des versions et des révisions avec Azure API Management . Pour définir la version et la révision de l'API, déployez les ressources apis et apiVersionSets . Apprenons à déployer ces ressources à l'aide du ARM Template .

`ARM Template`

Tout d'abord, jetons un coup d'œil à l'ensemble du ARM Template .

json

1{
2  "$schema": "https://schema.management.azure.com/schemas/2018-05-01/deploymentTemplate.json#",
3  "contentVersion": "1.0.0.0",
4  "parameters": {
5    "apiRevision": {
6      "type": "string",
7      "metadata": {
8        "description": "API Revision"
9      }
10    },
11    "apiVersion": {
12      "type": "string",
13      "metadata": {
14        "description": "API Version"
15      }
16    },
17    "serviceName": {
18      "type": "string",
19      "metadata": {
20        "description": "API Management Service Name"
21      }
22    },
23    "apiVersionSetName": {
24      "type": "string",
25      "metadata": {
26        "description": "API Management Version Set Name"
27      }
28    },
29    "apiName": {
30      "type": "string",
31      "metadata": {
32        "description": "API Name"
33      }
34    },
35    "apiDisplayName": {
36      "type": "string",
37      "metadata": {
38        "description": "API Display Name"
39      }
40    }
41  },
42  "variables": {},
43  "resources": [
44    {
45      "name": "[concat(parameters('serviceName'), '/', parameters('apiVersionSetName'))]",
46      "type": "Microsoft.ApiManagement/service/apiVersionSets",
47      "apiVersion": "2019-01-01",
48      "properties": {
49        "description": "version sets of my apis.",
50        "displayName": "[parameters('apiVersionSetName')]",
51        "versioningScheme": "Segment"
52      }
53    },
54    {
55      "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'))]",
56      "type": "Microsoft.ApiManagement/service/apis",
57      "apiVersion": "2019-01-01",
58      "dependsOn": [
59        "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('serviceName'), parameters('apiVersionSetName'))]"
60      ],
61      "properties": {
62        "description": "my api",
63        "displayName": "[parameters('apiDisplayName')]",
64        "apiVersionSetId": "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('serviceName'), parameters('apiVersionSetName'))]",
65        "apiVersion": "[parameters('apiVersion')]",
66        "apiRevision": "[parameters('apiRevision')]",
67        "authenticationSettings": {
68          "subscriptionKeyRequired": false
69        },
70        "path": "api",
71        "protocols": ["https"],
72        "isCurrent": false,
73        "subscriptionRequired": false
74      },
75      "resources": []
76    }
77  ]
78}

Examinons de plus près les apiVersionSets .

json

1{
2  "name": "[concat(parameters('serviceName'), '/', parameters('apiVersionSetName'))]",
3  "type": "Microsoft.ApiManagement/service/apiVersionSets",
4  "apiVersion": "2019-01-01",
5  "properties": {
6    "description": "version sets of my apis.",
7    "displayName": "[parameters('apiVersionSetName')]",
8    "versioningScheme": "Segment"
9  }
10}

En regardant le name , il est exprimé sous forme de concat(parameters('serviceName'), '/', parameters('apiVersionSetName')) . concat est une sorte de fonction de modèle pour concaténer des chaînes. Voir le document officiel ¹ pour une description de la fonction modèle.

En regardant l'argument de concat , serviceName et apiVersionSetName sont connectés avec / . En effet, le type de cette ressource est Microsoft.ApiManagement/service/apiVersionSets , elle est donc nommée en fonction de la hiérarchie des type . En regardant le type , il est décrit comme service/apiVersionSet . En conséquence, le nom est également configuré en tant que {service name}/{apiVersionSet name} .

versioningScheme spécifie comment spécifier la version de l'API. Trois valeurs peuvent être spécifiées: Segment , Query et Header - Header .

Segment : spécifiez la version dans le chemin URL. par exemple / api / v1 /.
Query : spécifiez la version dans le paramètre de requête.
Header - Header : spécifiez la version dans l'en-tête de la demande.

Ensuite, jetez un œil aux apis .

json

1{
2  "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'))]",
3  "type": "Microsoft.ApiManagement/service/apis",
4  "apiVersion": "2019-01-01",
5  "dependsOn": [
6    "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('serviceName'), parameters('apiVersionSetName'))]"
7  ],
8  "properties": {
9    "description": "my api",
10    "displayName": "[parameters('apiDisplayName')]",
11    "apiVersionSetId": "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('serviceName'), parameters('apiVersionSetName'))]",
12    "apiVersion": "[parameters('apiVersion')]",
13    "apiRevision": "[parameters('apiRevision')]",
14    "authenticationSettings": {
15      "subscriptionKeyRequired": false
16    },
17    "path": "api",
18    "protocols": ["https"],
19    "isCurrent": false,
20    "subscriptionRequired": false
21  },
22  "resources": []
23}

name est spécifié selon la structure hiérarchique de type comme expliqué dans apiVersionSet . Une différence est que la chaîne ;rev={apiRevision} est ajoutée. API Management a le concept de révisions et une seule révision est publiée à l'extérieur (la révision publiée est appelée la current revision ). Si vous déployez une API sans le spécifier ;rev={apiRevision} , l'API déployée devient la révision actuelle. Cependant, je pense que l'approche habituelle consiste à déployer la révision en tant qu'environnement vert, à la tester, puis à la basculer, comme le déploiement Blue / Green. Dans un tel cas, au lieu de définir directement l'API déployée comme révision actuelle, il est préférable de créer la révision en arrière-plan et de la changer en tant que révision actuelle une fois les tests nécessaires passés. En spécifiant ;rev={apiRevision} , l'API peut être déployée sans devenir la révision actuelle. Pour le moment, n'oubliez pas de spécifier isCurrent dans les properties comme false .

N'oubliez pas de spécifier dependsOn également. Il s'agit d'un paramètre qui définit les dépendances de déploiement. La version ne peut pas être spécifiée dans apis si apiVersionSet n'existe pas d'abord. Par conséquent, il est nécessaire de spécifier la dépendance comme dependsOn ici.

Déployer

Enfin, déployons le modèle ci-dessus.

powershell

1az group deployment create --resource-group <resourceGroupName> --template-file ./apis.json --parameters apiRevision="20191206" apiVersion="v1" serviceName=<serviceName> apiVersionSetName=<versionSetName> apiName=<apiName> apiDisplayName=<displayName>

Cela déploiera l'API version v1, révision 20191206. Quant à la révision, il n'y a pas d'autre révision au moment du premier déploiement, elle est donc déployée de force comme la révision actuelle. Cependant, si vous avez déjà une révision, vous pouvez la déployer sans devenir à jour.

Sommaire

Cet article décrit comment ajouter des versions et des révisions à la API Management . Le fait est qu'en ajoutant ;rev={revision} au nom de la révision, vous pouvez ajouter une révision afin qu'elle ne devienne pas la révision actuelle.