Establecer versión y revisión con Azure API Management

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

Este artículo fue publicado hace más de un año. La información puede estar desactualizada.

Este artículo describe cómo agregar versiones y revisiones con Azure API Management . Para configurar la versión y revisión de la API, implemente los recursos apis y apiVersionSets . Aprendamos a implementar estos recursos utilizando la ARM Template .

`ARM Template`

Primero, echemos un vistazo a toda la 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}

Echemos un vistazo más de cerca 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}

Mirando el name , se expresa como concat(parameters('serviceName'), '/', parameters('apiVersionSetName')) . concat es un tipo de función de plantilla para concatenar cadenas. Consulte el documento oficial ¹ para obtener una descripción de la función de plantilla.

Mirando el argumento de concat , serviceName y apiVersionSetName están conectados con / . Esto se debe a que el type de este recurso es Microsoft.ApiManagement/service/apiVersionSets , por lo que se nombra de acuerdo con la jerarquía de type . En cuanto al type , se describe como service/apiVersionSet . En consecuencia, el nombre también está configurado como {service name}/{apiVersionSet name} .

versioningScheme especifica cómo especificar la versión de API. Se pueden especificar tres valores: Segment , Query y Header .

Segment : especifique la versión en la ruta URL. por ejemplo / api / v1 /.
Query : especifique la versión en el parámetro de consulta.
Header : especifique la versión en el encabezado de la solicitud.

A continuación, eche un vistazo a las 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 se especifica de acuerdo con la estructura jerárquica de type como se explica en apiVersionSet . Una diferencia es que se agrega la cadena ;rev={apiRevision} . API Management tiene el concepto de revisiones, y solo una revisión se publica fuera (la revisión publicada se llama current revision ). Si implementa una API sin especificar esto ;rev={apiRevision} , la API implementada se convierte en la revisión actual. Sin embargo, creo que el enfoque habitual es implementar la revisión como un entorno verde, probarla y luego cambiarla, como la implementación Azul / Verde. En tal caso, en lugar de establecer directamente la API implementada como la revisión actual, es mejor crear la revisión detrás de escena y cambiarla como la revisión actual después de que se pasen las pruebas necesarias. Al especificar ;rev={apiRevision} , la API se puede implementar sin convertirse en la revisión actual. En este momento, no olvide especificar isCurrent en properties como false .

No olvides especificar dependsOn también. Este es un parámetro que define las dependencias de implementación. La versión no se puede especificar en apis si apiVersionSet no existe primero. Por lo tanto, es necesario especificar la dependencia como dependsOn aquí.

Desplegar

Por último, implementemos la plantilla anterior.

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>

Esto implementará la versión v1 de API, revisión 20191206. En cuanto a la revisión, no hay otra revisión en el momento de la primera implementación, por lo que se implementa por la fuerza como la revisión actual. Sin embargo, si ya tiene una revisión, puede implementarla sin actualizarse.

Resumen

Este artículo describe cómo agregar versiones y revisiones a API Management . El punto es que al agregar ;rev={revision} al nombre de la revisión, puede agregar una revisión para que no se convierta en la revisión actual.