Добавление настраиваемых действий в REST API Azure

  • Статья

В этой статье рассматриваются требования и рекомендации по созданию конечных точек настраиваемых поставщиков ресурсов Azure, на которых применяются настраиваемые действия. Если вы не знакомы с настраиваемыми поставщиками ресурсов Azure, перейдите к этой обзорной статье.

Как определить конечную точку действия

Конечная точка — это URL-адрес, указывающий на службу, которая реализует контракт между ней и Azure. Конечная точка определяется в настраиваемом поставщике ресурсов. Она может быть любым общедоступным URL-адресом. В примере ниже есть действиеmyCustomAction, которое реализуется с помощью endpointURL.

Пример ResourceProvider:

{
  "properties": {
    "actions": [
      {
        "name": "myCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus",
  "type": "Microsoft.CustomProviders/resourceProviders",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
  "name": "{resourceProviderName}"
}

Создание конечной точки действия

Конечная точка, которая применяет действие, должна обрабатывать запрос и ответ для нового API в Azure. После создания поставщика настраиваемых ресурсов с действием создается новый набор API в Azure. В этом случае действие создаст новый API действия Azure для вызовов POST:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction

Входящий запрос API Azure:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction?api-version=2018-09-01-preview
Authorization: Bearer eyJ0e...
Content-Type: application/json

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Этот запрос в дальнейшем будет направлен в конечную точку в формате:

POST https://{endpointURL}/?api-version=2018-09-01-preview
Content-Type: application/json
X-MS-CustomProviders-RequestPath: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Аналогичным образом ответ из конечной точки в дальнейшем перенаправляется обратно клиенту. Ответ из конечной точки должен вернуть:

  • Допустимый документ объекта JSON. Все массивы и строки должны быть вложены в объект верхнего уровня.
  • У заголовка Content-Type должно быть значение "application/json; charset=utf-8".
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Ответ настраиваемого поставщика ресурсов Azure:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Вызов настраиваемого действия

Настраиваемое действие вне настраиваемого поставщика ресурсов можно вызвать двумя основными способами:

  • Azure CLI
  • Шаблоны Azure Resource Manager

Azure CLI

az resource invoke-action --action {actionName} \
                          --ids /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName} \
                          --request-body \
                            '{
                                "myProperty1": "myPropertyValue1",
                                "myProperty2": {
                                    "myProperty3": "myPropertyValue3"
                                }
                            }'
Параметр Обязательно Описание
action да Имя действия, определенного в ResourceProvider.
ids да Идентификатор ресурса ResourceProvider.
request-body нет Текст запроса, который будет отправляться в конечную точку.

Шаблон Azure Resource Manager

Примечание

Для действий в шаблонах Azure Resource Manager предусмотрена ограниченная поддержка. Чтобы действие можно было вызвать внутри шаблона, его имя должно содержать префикс list.

Пример ResourceProvider с действием List:

{
  "properties": {
    "actions": [
      {
        "name": "listMyCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus"
}

Пример шаблона Диспетчера ресурсов Azure:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "variables": {
        "resourceIdentifier": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
        "apiVersion": "2018-09-01-preview",
        "functionValues": {
            "myProperty1": "myPropertyValue1",
            "myProperty2": {
                "myProperty3": "myPropertyValue3"
            }
        }
    },
    "resources": [],
    "outputs": {
        "myCustomActionOutput": {
            "type": "object",
            "value": "[listMyCustomAction(variables('resourceIdentifier'), variables('apiVersion'), variables('functionValues'))]"
        }
    }
}
Параметр Обязательно Описание
resourceIdentifier да Идентификатор ресурса ResourceProvider.
версия_API да Версия API для среды выполнения ресурса. Всегда должно использоваться значение "2018-09-01-preview".
functionValues нет Текст запроса, который будет отправляться в конечную точку.

Дальнейшие действия