Adicionar ações personalizadas à API REST do Azure

  • Artigo

Este artigo abordará os requisitos e as melhores práticas para a criação de pontos de extremidade do Provedor de Recursos Personalizados do Azure que implementam ações personalizadas. Se você não conhecer os Provedores de Recursos Personalizados do Azure, confira a visão geral dos provedores de recursos personalizados.

Como definir um ponto de extremidade de ação

Um ponto de extremidade é uma URL que aponta para um serviço, que implementa o contrato subjacente entre ele e o Azure. O ponto de extremidade é definido no provedor de recursos personalizado e pode ser qualquer URL acessível publicamente. O exemplo abaixo tem uma ação chamada myCustomAction, implementada por endpointURL.

ResourceProvider de exemplo:

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

Criando um ponto de extremidade de ação

Um ponto de extremidade que implementa uma ação deve gerenciar a solicitação e a resposta para a nova API no Azure. Quando um provedor de recursos personalizado com uma ação é criado, ele gera um novo conjunto de APIs no Azure. Nesse caso, a ação vai gerar uma nova API de ação do Azure para chamadas POST:

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

Solicitação de Entrada da API do 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"
    }
}

Esta solicitação será encaminhada para o ponto de extremidade no formulário:

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

Da mesma forma, a resposta do ponto de extremidade é encaminhada de volta para o cliente. A resposta do ponto de extremidade deve retornar:

  • Um documento de objeto JSON válido. Todas as matrizes e cadeias de caracteres devem ser aninhadas abaixo de um objeto superior.
  • O cabeçalho Content-Type deve ser definido como "application/json; charset=utf-8".
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

Resposta do Provedor de Recursos Personalizados do Azure:

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

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

Chamando uma ação personalizada

Há duas maneiras principais de criar uma ação personalizada com base em um provedor de recursos personalizado:

  • CLI do Azure
  • Modelos do Azure Resource Manager

CLI do Azure

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 Obrigatório Descrição
ação sim O nome da ação definida no ResourceProvider.
ids sim A ID do recurso do ResourceProvider.
corpo da solicitação não O corpo da solicitação que será enviado ao ponto de extremidade.

Modelo do Azure Resource Manager

Observação

As ações têm suporte limitado em modelos de Azure Resource Manager. Para que a ação seja chamada dentro de um modelo, ela deve conter o list prefixo em seu nome.

Exemplo de ResourceProvider com Ação de Lista:

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

Modelo de exemplo do Azure Resource Manager:

{
    "$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 Obrigatório Descrição
resourceIdentifier sim A ID do recurso do ResourceProvider.
apiVersion sim Versão da API do runtime do recurso. Deve ser sempre "2018-09-01-preview".
functionValues não O corpo da solicitação que será enviado ao ponto de extremidade.

Próximas etapas