Azure API Managementでバージョンとリビジョンを設定する

📅2019/12/06👤mark241⏱️約3分

この記事は1年以上前に公開されたものです。情報が古くなっている可能性があります。

本記事では、Azure API Managementでバージョンやリビジョンを追加する方法を説明します。 API のバージョニングやリビジョンを設定するにはapis、apiVersionSetsというリソースをデプロイします。 ARM Templateを使ってこれらのリソースをデプロイする方法を学んでいきましょう。

ARM Template

まず今回使用する 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}

まず、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}

nameをみると、concat(parameters('serviceName'), '/', parameters('apiVersionSetName'))という表現になっています。 concatはテンプレート関数と呼ばれるもので、文字列を連結するための関数です。テンプレート関数の説明はMicrosoftの公式ドキュメント¹を参照してください。

concatの引数を見ると、serviceNameとapiVersionSetNameが/でつながっています。これはこのリソースのtypeがMicrosoft.ApiManagement/service/apiVersionSetsであるため、typeの階層構造に合わせて名前を付けているためです。typeを見ると、service/apiVersionSetとなっていますね。それに合わせて名前も<service名>/<apiVersionSet名>という構成をとっているのです。

versioningSchemeはどのように API のバージョンを指定するかを指定しています。Segment, Query, Headerの 3 つの値を指定することができます。

Segment: URL のパスでバージョンを指定します。例えば、/api/v1/のような形です。
Query: クエリパラメータでバージョンを指定します。
Header：リクエストの header でバージョンを指定します。

次は、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が、先ほどと同じようにtypeの階層構造に合わせて指定されています。1 点異なるのは、;rev=<apiRevison>という文字列が追加されていることです。API Management には、リビジョンという概念があり、外部に公開されるのは、1 つのリビジョンだけです(公開されているリビジョンを current リビジョンと呼びます)。この;rev=<apiRevison>という指定をせずに API をデプロイすると、デプロイした API が Current リビジョンとなります。しかし、通常は、Blue/Green デプロイのように、まず、Green 環境としてデプロイし、テストを行ってから BG スイッチするような手法がとられると思います。そのような場合、デプロイした API をいきなり Current リビジョンとするのではなく、一つのリビジョンとして裏で作成しておき、後からリビジョン切り替えができた方がいいでしょう。;rev=<apiRevison>を指定することで、API を Currentリビジョンにすることなく、デプロイすることができます。この時に、合わせてpropertiesのisCurrentをfalseに、apiRevisionにnameで指定したのと同じrevisionを指定することも忘れずに。

dependsOnの指定も忘れずに行ってください。これはデプロイの依存関係を規定するためのパラメータです。apisの中でバージョンを指定していますので、先にapiVersionSetが存在していないと、バージョンの指定ができません。したがって、ここで、dependsOnとして依存関係を明記しておく必要があります。

デプロイ

では、上記のテンプレートをデプロイしていきましょう。

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>

これにより、API のバージョン v1 、リビジョン20191206がデプロイされます。リビジョンについては、初めてのデプロイ時は他にリビジョンが存在しないため、強制的に current リビジョンとしてデプロイされますが、すでにリビジョンが存在する状態であれば、current にならずにデプロイすることができると思います。