Incorporación de acciones personalizadas a la API REST de Azure

  • Artículo

Este artículo le guiará a través de los requisitos y procedimientos recomendados para crear puntos de conexión del proveedor de recursos personalizados de Azure que implementan acciones personalizadas. Si no está familiarizado con los proveedores de recursos personalizados de Azure, consulte la introducción a los proveedores de recursos personalizados.

Definición de un punto de conexión de acción

Un punto de conexión es una dirección URL que apunta a un servicio que implementa el contrato subyacente entre él y Azure. El punto de conexión se define en el proveedor de recursos personalizados y puede ser cualquier dirección URL accesible públicamente. En el ejemplo siguiente hay una acción denominada myCustomAction implementada por endpointURL.

ResourceProvider de ejemplo:

{
  "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}"
}

Creación de un punto de conexión de acción

Un punto de conexión que implementa una acción debe controlar la solicitud y la respuesta de la nueva API en Azure. Cuando se crea un proveedor de recursos personalizados con una acción, generará un nuevo conjunto de API en Azure. En este caso, la acción generará una API de acción de Azure nueva para las llamadas POST:

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

Solicitud entrante de Azure API:

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"
    }
}

Esta solicitud se reenviará al punto de conexión de esta forma:

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"
    }
}

De manera similar, la respuesta del punto de conexión se reenvía de vuelta al cliente. La respuesta del punto de conexión debería devolver:

  • Un documento de objeto JSON válido. Todas las matrices y cadenas deben estar anidadas bajo un objeto superior.
  • El encabezado Content-Type se debe establecer en "application/json; charset=utf-8".
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

Respuesta del proveedor de recursos personalizado de Azure:

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

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

Llamada a una acción personalizada

Hay dos formas principales de llamar a una acción personalizada fuera de un proveedor de recursos personalizado:

  • Azure CLI
  • Plantillas del Administrador de recursos de Azure

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"
                                }
                            }'
Parámetro Obligatorio Descripción
action sí El nombre de la acción que se definió en el ResourceProvider.
ids sí El identificador del recurso del ResourceProvider.
request-body no El cuerpo de la solicitud que se enviará al punto de conexión.

Plantilla de Azure Resource Manager

Nota:

Las acciones tienen compatibilidad limitada con las plantillas de Azure Resource Manager. Para que sea posible llamar a la acción dentro de una plantilla, debe contener el prefijo list en el nombre.

ResourceProvider de ejemplo con acción de lista:

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

Plantilla de Azure Resource Manager de ejemplo:

{
    "$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'))]"
        }
    }
}
Parámetro Obligatorio Descripción
resourceIdentifier sí El identificador del recurso del ResourceProvider.
apiVersion sí La versión de la API del entorno en tiempo de ejecución de un recurso. Siempre debe ser "2018-09-01-preview".
functionValues no El cuerpo de la solicitud que se enviará al punto de conexión.

Pasos siguientes