Imposta la versione e la revisione con Gestione API di Azure

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

Questo articolo è stato pubblicato più di un anno fa. Le informazioni potrebbero essere obsolete.

Questo articolo descrive come aggiungere versioni e revisioni con Azure API Management . Per impostare la versione e la revisione dell'API, distribuire le risorse apis e apiVersionSets . Impariamo come distribuire queste risorse usando il ARM Template .

`ARM Template`

Innanzitutto, diamo un'occhiata all'intero 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}

Diamo un'occhiata più da vicino a 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}

Guardando il name , viene espresso come concat(parameters('serviceName'), '/', parameters('apiVersionSetName')) . concat è una sorta di funzione template per concatenare stringhe. Vedi il documento ufficiale ¹ per una descrizione della funzione template.

Guardando l'argomento di concat , serviceName e apiVersionSetName sono collegati con / . Questo perché il type di questa risorsa è Microsoft.ApiManagement/service/apiVersionSets , quindi è denominato in base alla gerarchia dei type . Guardando il type , viene descritto come service/apiVersionSet . Di conseguenza, il nome è anche configurato come {service name}/{apiVersionSet name} .

versioningScheme specifica come specificare la versione dell'API. È possibile specificare tre valori: Segment , Query e Header .

Segment : specificare la versione nel percorso URL. ad es. / api / v1 /.
Query : specificare la versione nel parametro query.
Header ： Specificare la versione nell'intestazione della richiesta.

Quindi, dai un'occhiata ad 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 viene specificato in base alla struttura gerarchica del type come spiegato in apiVersionSet . Una differenza è che viene aggiunta la stringa ;rev={apiRevision} . API Management ha il concetto di revisioni e solo una revisione è pubblicata all'esterno (la revisione pubblicata è chiamata current revision ). Se si distribuisce un'API senza specificarla ;rev={apiRevision} , l'API distribuita diventa la revisione corrente. Tuttavia, penso che l'approccio abituale sia distribuire la revisione come ambiente verde, testarla e quindi cambiarla, come la distribuzione Blue / Green. In tal caso, anziché impostare direttamente l'API distribuita come revisione corrente, è meglio creare la revisione dietro le quinte e cambiarla come la revisione corrente dopo aver superato i test necessari. Specificando ;rev={apiRevision} , l'API può essere distribuita senza diventare la revisione corrente. Al momento, non dimenticare di specificare isCurrent nelle properties come false .

Non dimenticare di specificare dependsOn . Questo è un parametro che definisce le dipendenze di distribuzione. La versione non può essere specificata in apis se apiVersionSet non esiste prima. Pertanto, è necessario specificare la dipendenza come dependsOn qui.

Deploy

Infine, implementiamo il modello sopra.

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>

In questo modo verrà distribuita l'API versione v1, revisione 20191206. Per quanto riguarda la revisione, non vi sono altre revisioni al momento della prima distribuzione, quindi viene distribuita forzatamente come revisione corrente. Tuttavia, se hai già una revisione, puoi distribuirla senza diventare corrente.

Sommario

Questo articolo descrive come aggiungere versioni e revisioni a API Management . Il punto è che aggiungendo ;rev={revision} al nome della revisione, è possibile aggiungere una revisione in modo che non diventi la revisione corrente.