Aggiunta di azioni personalizzate all'API REST di Azure

  • Articolo

Questo articolo esamina i requisiti e le procedure consigliate per creare endpoint dei provider di risorse personalizzati di Azure che vogliono implementare azioni personalizzate. Se non si ha familiarità con i provider di risorse personalizzati di Azure, vedere la panoramica dei provider di risorse personalizzati.

Come definire un endpoint azione

Un endpoint è un URL che punta a un servizio, che implementa il contratto sottostante tra di esso e Azure. L'endpoint è definito nel provider di risorse personalizzato e può essere qualsiasi URL accessibile pubblicamente. L'esempio seguente include un’azione denominata myCustomAction implementata da endpointURL.

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

Creazione di un endpoint azione

Un endpoint che implementa un’azione deve gestire la richiesta e la risposta per la nuova API in Azure. Quando viene creato un provider di risorse personalizzato con un’azione , verrà generato un nuovo set di API in Azure. In questo caso, l'azione genererà una nuova API di azione di Azure per le chiamate POST :

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

Richiesta in ingresso dell’API di 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"
    }
}

Questa richiesta verrà quindi inoltrata all’endpoint nel modulo:

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

Analogamente, la risposta dell’endpoint viene poi reinoltrata al cliente. La risposta dell'endpoint deve restituire:

  • Un documento oggetto JSON valido Tutte le matrici e le stringhe devono essere annidate in un oggetto superiore.
  • L'intestazione Content-Type deve essere impostata su "application/json; charset=utf-8".
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

Risposta del provider di risorse personalizzato di Azure:

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

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

Chiamata di un'azione personalizzata

Esistono due modi principali per chiamare un'azione personalizzata da un provider di risorse personalizzato:

  • Interfaccia della riga di comando di Azure
  • Modelli di Azure Resource Manager

Interfaccia della riga di comando di Azure

az resource invoke-action --action {actionName} \
                          --ids /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName} \
                          --request-body \
                            '{
                                "myProperty1": "myPropertyValue1",
                                "myProperty2": {
                                    "myProperty3": "myPropertyValue3"
                                }
                            }'
Parametro Richiesto Descrizione
action yes nome dell'azione definita in ResourceProvider.
ids yes ID risorsa di ResourceProvider.
request-body no corpo della richiesta che verrà inviato all’endpoint.

Modello di Azure Resource Manager

Nota

Le azioni hanno un supporto limitato nei modelli di Resource Manager di Azure. Affinché l'azione venga chiamata all'interno di un modello, deve contenere il prefisso list nel nome.

Esempio di ResourceProvider con azione elenco:

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

Modello di Azure Resource Manager di esempio:

{
    "$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'))]"
        }
    }
}
Parametro Richiesto Descrizione
resourceIdentifier yes ID risorsa di ResourceProvider.
apiVersion yes Versione API del runtime della risorsa. Deve essere sempre "2018-09-01-preview".
functionValues no corpo della richiesta che verrà inviato all’endpoint.

Passaggi successivi