Подключите серверную часть к Azure API Management

📅👤mark241⏱️3 мин
GuidesAzureAPI Management
Поделиться:

Узнайте, как использовать ARM Template для добавления API в API Management . Используйте такие ресурсы, как operations , policy и backend чтобы подключить API к своей серверной части. В этой статье мы предполагаем, что серверная часть реализована в Azure functions .

Определить API

Сначала установите определение API Management в API Management . В API Management каждый API определяется ресурсом, называемым operations .

Определить operations

operations - это ресурс, соответствующий одному API. Вы можете определить путь и параметры API здесь, в этом ресурсе. Давайте посмотрим на ARM Template для operations .

json
1{
2  "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'), '/', parameters('operationName'))]",
3  "type": "Microsoft.ApiManagement/service/apis/operations",
4  "apiVersion": "2018-01-01",
5  "dependsOn": [
6    "[resourceId('Microsoft.ApiManagement/service/apis', parameters('serviceName'), concat(parameters('apiName'), ';rev=', parameters('apiRevision')))]",
7    "[resourceId('Microsoft.ApiManagement/service/backends', parameters('serviceName'), parameters('backendName'))]"
8  ],
9  "properties": {
10    "description": "GET Order",
11    "templateParameters": [
12      {
13        "name": "orderId",
14        "type": "string",
15        "values": []
16      }
17    ],
18    "responses": [],
19    "policies": null,
20    "displayName": "GetOrder",
21    "method": "GET",
22    "urlTemplate": "orders/{orderId}"
23  },
24  "resources": []
25}

Обратите внимание, что к имени добавляется rev;={apiRevision} , поскольку оно будет развернуто как конкретная ревизия, как упоминалось в другой статье 1. URL указывается в urlTemplate . Параметры переменных выражаются в формате {orderId} . Детали параметров описаны в templateParameters . Приведенный выше пример определяет, что типом orderId является строка. Для method укажите метод HTTP.

API, созданный из приведенного выше примера, будет GET http(s)://{API Management FQDN}/api/v1/orders/{orderId} . На этот раз мы определили часть /orders/{orderId} , а часть /api/v1 была определена в предыдущих apis и apiVersionSets 1. Вы можете импортировать OpenAPI.yaml для определения API. Я расскажу об этом в отдельной статье.

Определить backends

Далее определите backends .

json
1{
2  "name": "[concat(variables('serviceName'), '/', parameters('backendName'))]",
3  "type": "Microsoft.ApiManagement/service/backends",
4  "apiVersion": "2018-01-01",
5  "dependsOn": [
6    "[resourceId('Microsoft.ApiManagement/service/properties', parameters('serviceName'), parameters('propertyName'))]"
7  ],
8  "properties": {
9    "title": null,
10    "description": "Backend of API management",
11    "url": "[concat('https://', parameters('functionsAppName'),'.azurewebsites.net/api')]",
12    "protocol": "http",
13    "credentials": {
14      "query": {
15        "code": ["[concat('{{', parameters('propertyName'), '}}')]"]
16      }
17    },
18    "resourceId": "[concat('https://management.azure.com/subscriptions/', subscription().id, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.Web/sites/', parameters('functionsAppName'))]"
19  }
20}

backends - это буквально ресурсы, которые эквивалентны бэкэнд-сервисам, составляющим API. На этот раз мы предполагаем функцию HTTPTrigger функций Azure functions качестве бэкэнда. URL-адрес Azure functions указывается в url , а ресурс Azure functions указывается посредством resourceId . В этом случае маршрут HTTPTrigger Azure functions должен быть orders/{orderId} .

В credentials укажите ключ API для соединения с Azure functions . Приведенный выше пример шаблона означает, что учетные данные указываются в форме параметра запроса, например ?code=xxx , и задана символьная строка, указанная propertyName . Значение учетных данных имеет форму двойного вложения, такого как {{credential}} . Такие учетные данные, как ключ API, хранятся в ресурсе properties описанном ниже. Указанное здесь propertyName - это имя, которое указывает учетные данные, сохраненные в properties .

Кстати, чтобы указать здесь ключ API для Azure functions , вам необходимо получить ключ из Azure functions . listKeys для получения ключей в listKeys ARM Template используются функции-шаблоны listSecrets или listKeys , но они не работают listKeys для Azure functions v2 2. Лучше получить его заранее, используя Azure CLI 3.

powershell
1$resourceId = "/subscriptions/$subscriptionid/resourceGroups/$resourceGroup/providers/Microsoft.Web/sites/$functionsAppName"
2$url = "$resourceId/host/default/listKeys?api-version=2016-03-01"
3$ret = az rest --method post --uri $url | ConvertFrom-Json
4$key = $ret.functionKeys.default

Azure functions имеют клавишу хоста и функциональную клавишу. В этом случае используется ключ хоста. Проще говоря, функциональная клавиша - это клавиша для каждой функции, а клавиша хоста - это клавиша, которая может быть подключена ко всем функциям.

Чтобы связать API с бэкэндом, вам нужно также указать и бэкэнд в policy .

Определить policy

Наконец, установите policy для подключения бэкэнда и управления API. Policy - это важная функция, которая может добавлять различные обработки к API Management . Здесь мы используем один из них для подключения к бэкэнду.

json
1{
2  "variables": {
3    "backendPolicy": "[concat('<policies>\r\n  <inbound>\r\n    <base />\r\n    <set-backend-service id=\"apim-generated-', 'policy','\" backend-id=\"', parameters('backendName'), '\" />\r\n  </inbound>\r\n  <backend>\r\n    <base />\r\n  </backend>\r\n  <outbound>\r\n    <base />\r\n  </outbound>\r\n  <on-error>\r\n    <base />\r\n  </on-error>\r\n</policies>')]"
4  },
5  "resources": [
6    {
7      "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'), '/', 'policy')]",
8      "type": "Microsoft.ApiManagement/service/apis/policies",
9      "apiVersion": "2018-01-01",
10      "properties": {
11        "policyContent": "[variables('backendPolicy')]",
12        "contentFormat": "xml"
13      }
14    }
15  ]
16}

policy указана в XML в policyContent . backendPolicy определяется в variables , и вы можете видеть, что определена строка xml. Дело в том, что серверный ресурс определяется backend-id . В результате ранее созданный серверный ресурс указывается в policy .

Определить properties

properties - это ресурс для сохранения значения параметра, используемого в API Management в формате ключ-значение. Здесь мы будем использовать этот ресурс для хранения ключа API для подключения к внутренним функциям Azure.

json
1{
2  "type": "Microsoft.ApiManagement/service/properties",
3  "name": "[concat(parameters('serviceName'), '/', parameters('propertyName'))]",
4  "apiVersion": "2018-06-01-preview",
5  "scale": null,
6  "properties": {
7    "displayName": "[parameters('propertyName')]",
8    "value": "[parameters('functionHostKey')]",
9    "tags": ["key", "function"],
10    "secret": true
11  }
12}

Замените displayName именем свойства, которое вы указали ранее в бэкэндах. Укажите секретное значение для value . В этом случае укажите ключ API Azure functions полученных ранее с помощью Azure CLI . tags - это тег, который будет использоваться при последующем поиске свойств. Давайте определим произвольную строку символов. Если для параметра secret установлено значение true , свойство будет зашифровано и защищено.

Развертывание

Итак, давайте развернем 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    "serviceName": {
6      "type": "string",
7      "metadata": {
8        "description": "Service Name"
9      }
10    },
11    "apiName": {
12      "type": "string",
13      "metadata": {
14        "description": "API Name"
15      }
16    },
17    "apiRevision": {
18      "type": "string",
19      "metadata": {
20        "description": "API Revision"
21      }
22    },
23    "operationName": {
24      "type": "string",
25      "metadata": {
26        "description": "Operation name"
27      }
28    },
29    "backendName": {
30      "type": "string",
31      "metadata": {
32        "description": "Backend Name"
33      }
34    },
35    "functionHostKey": {
36      "type": "securestring",
37      "metadata": {
38        "description": "Host key for the functions app"
39      }
40    },
41    "functionAppName": {
42      "type": "string",
43      "metadata": {
44        "description": "Functions App Name"
45      }
46    },
47    "propertyName": {
48      "type": "string",
49      "metadata": {
50        "description": "Property Name"
51      }
52    }
53  },
54  "variables": {
55    "backendPolicy": "[concat('<policies>\r\n  <inbound>\r\n    <base />\r\n    <set-backend-service id=\"apim-generated-', 'policy','\" backend-id=\"', parameters('backendName'), '\" />\r\n  </inbound>\r\n  <backend>\r\n    <base />\r\n  </backend>\r\n  <outbound>\r\n    <base />\r\n  </outbound>\r\n  <on-error>\r\n    <base />\r\n  </on-error>\r\n</policies>')]"
56  },
57  "resources": [
58    {
59      "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'), '/', parameters('operationName'))]",
60      "type": "Microsoft.ApiManagement/service/apis/operations",
61      "apiVersion": "2019-01-01",
62      "dependsOn": [
63        "[resourceId('Microsoft.ApiManagement/service/backends', parameters('serviceName'), parameters('backendName'))]"
64      ],
65      "properties": {
66        "description": "GET Order",
67        "templateParameters": [
68          {
69            "name": "orderId",
70            "type": "string",
71            "values": []
72          }
73        ],
74        "responses": [],
75        "policies": null,
76        "displayName": "GetOrder",
77        "method": "GET",
78        "urlTemplate": "orders/{orderId}"
79      },
80      "resources": []
81    },
82    {
83      "name": "[concat(parameters('serviceName'), '/', parameters('apiName'), ';rev=', parameters('apiRevision'), '/', 'policy')]",
84      "type": "Microsoft.ApiManagement/service/apis/policies",
85      "apiVersion": "2018-01-01",
86      "properties": {
87        "policyContent": "[variables('backendPolicy')]",
88        "contentFormat": "xml"
89      }
90    },
91    {
92      "name": "[concat(parameters('serviceName'), '/', parameters('backendName'))]",
93      "type": "Microsoft.ApiManagement/service/backends",
94      "apiVersion": "2018-01-01",
95      "dependsOn": [
96        "[resourceId('Microsoft.ApiManagement/service/properties', parameters('serviceName'), parameters('propertyName'))]"
97      ],
98      "properties": {
99        "title": null,
100        "description": "Backend of API management",
101        "url": "[concat('https://', parameters('functionAppName'),'.azurewebsites.net/api')]",
102        "protocol": "http",
103        "credentials": {
104          "query": {
105            "code": ["[concat('{{', parameters('propertyName'), '}}')]"]
106          }
107        },
108        "resourceId": "[concat('https://management.azure.com/subscriptions/', subscription().id, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.Web/sites/', parameters('functionAppName'))]"
109      }
110    },
111    {
112      "type": "Microsoft.ApiManagement/service/properties",
113      "name": "[concat(parameters('serviceName'), '/', parameters('propertyName'))]",
114      "apiVersion": "2018-06-01-preview",
115      "scale": null,
116      "properties": {
117        "displayName": "[parameters('propertyName')]",
118        "value": "[parameters('functionHostKey')]",
119        "tags": ["key", "function"],
120        "secret": true
121      }
122    }
123  ]
124}

Теперь API можно развернуть на экземпляре службы, используя вышеуказанный шаблон.

Footnotes

  1. Set version and revision with Azure API Management ↩ ↩2

  2. Changes to Key Management in Functions V2 ↩

  3. Managing Azure Functions Keys (using the new ARM APIs!) ↩

Поделиться:

Связанные статьи