Definir versão e revisão com o Gerenciamento de API do Azure

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

Este artigo foi publicado há mais de um ano. As informações podem estar desatualizadas.

Este artigo descreve como adicionar versões e revisões com o Azure API Management . Para definir a versão e a revisão da API, implante os recursos apis e apiVersionSets . Vamos aprender como implantar esses recursos usando o ARM Template .

`ARM Template`

Primeiro, vamos dar uma olhada em todo o 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}

Vamos dar uma olhada em 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}

Observando o name , ele é expresso como concat(parameters('serviceName'), '/', parameters('apiVersionSetName')) . concat é um tipo de função de modelo para concatenar seqüências de caracteres. Veja o documento oficial ¹ para uma descrição da função de modelo.

Olhando para o argumento de concat , serviceName e apiVersionSetName estão conectados com / . Isso ocorre porque o type desse recurso é Microsoft.ApiManagement/service/apiVersionSets , portanto, é nomeado de acordo com a hierarquia de type . Olhando para o type , ele é descrito como service/apiVersionSet . Do mesmo modo, o nome também é configurado como {service name}/{apiVersionSet name} .

versioningScheme especifica como especificar a versão da API. Três valores podem ser especificados: Segment , Query e Header .

Segment : especifique a versão no caminho da URL. por exemplo, / api / v1 /.
Query : especifique a versão no parâmetro de consulta.
Header : Especifique a versão no cabeçalho da solicitação.

Em seguida, dê uma olhada nas 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 é especificado de acordo com a estrutura hierárquica do type conforme explicado em apiVersionSet . Uma diferença é que a string ;rev={apiRevision} é adicionada. API Management tem o conceito de revisões e apenas uma revisão é publicada fora (a revisão publicada é chamada de current revision ). Se você implantar uma API sem especificar isso ;rev={apiRevision} , a API implementada se tornará a revisão atual. No entanto, acho que a abordagem usual é implantar a revisão como um ambiente verde, testá-la e alterná-la, como a implantação Azul / Verde. Nesse caso, em vez de definir diretamente a API implantada como a revisão atual, é melhor criar a revisão nos bastidores e alterná-la como a revisão atual após a aprovação dos testes necessários. Ao especificar ;rev={apiRevision} , a API pode ser implantada sem se tornar a revisão atual. No momento, não se esqueça de especificar isCurrent nas properties como false .

Não se esqueça de especificar também o dependsOn . Este é um parâmetro que define dependências de implantação. A versão não pode ser especificada em apis se apiVersionSet não existir primeiro. Portanto, é necessário especificar a dependência como dependsOn aqui.

Implantar

Por fim, vamos implantar o modelo acima.

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>

Isso implementará a versão da API v1, revisão 20191206. Quanto à revisão, não há outra revisão no momento da primeira implantação; portanto, ela é implementada à força como a revisão atual. No entanto, se você já tiver uma revisão, poderá implantá-la sem se tornar atual.

Sumário

Este artigo descreveu como adicionar versões e revisões ao API Management . O ponto é que, adicionando ;rev={revision} ao nome da revisão, você pode adicionar uma revisão para que ela não se torne a revisão atual.