Aggiunta di risorse personalizzate all'API REST di Azure

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

Come definire un endpoint di risorsa

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 personalizzate e può essere qualsiasi URL accessibile pubblicamente. L'esempio seguente include un resourceType denominato myCustomResource implementato da endpointURL.

Esempio di ResourceProvider:

{
  "properties": {
    "resourceTypes": [
      {
        "name": "myCustomResource",
        "routingType": "Proxy, Cache",
        "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 di risorsa

Un endpoint che implementa un resourceType deve gestire la richiesta e la risposta per la nuova API in Azure. Quando viene creato un provider di risorse personalizzate con resourceType, verrà generato un nuovo set di API in Azure. In questo caso, il resourceType genererà una nuova API delle risorse di Azure per PUT, GETe DELETE per eseguire CRUD su una singola risorsa, nonché GET per recuperare tutte le risorse esistenti:

Modificare una singola risorsa (PUT, GETe DELETE):

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

Recuperare tutte le risorse (GET):

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

Per le risorse personalizzate, i provider di risorse personalizzate offrono due tipi di routingType:"Proxy" e "Proxy, Cache".

Tipo di routing proxy

RoutingType "Proxy" esegue il proxy di tutti i metodi di richiesta all'endpointspecificato nel provider di risorse personalizzate. Quando usare “Proxy”:

• È necessario il controllo completo sulla risposta.
• Integrazione di sistemi con risorse esistenti.

Per altre informazioni sulle risorse "Proxy", vedere le informazioni di riferimento sul proxy di risorse personalizzate

Tipo di routing della cache proxy

routingType "Proxy, Cache" esegue il proxy dei soli metodi di richiesta PUT e DELETE all'endpoint specificato nel provider di risorse personalizzate. Il provider di risorse personalizzate restituirà automaticamente GET richieste in base a quanto archiviato nella cache. Se una risorsa personalizzata è contrassegnata con la cache, il provider di risorse personalizzate aggiungerà/sovrascriverà anche i campi nella risposta per rendere le API conformi ad Azure. Quando usare “Proxy, Cache”:

• Creazione di un nuovo sistema senza risorse esistenti.
• Usare l'ecosistema di Azure esistente.

Per altre informazioni sulle risorse "Proxy, Cache", vedere le informazioni di riferimento sulla cache delle risorse personalizzate

Creazione di una risorsa personalizzata

Esistono due modi principali per creare una risorsa personalizzata da un provider di risorse personalizzate:

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

Interfaccia della riga di comando di Azure

Creare una risorsa personalizzata:

az resource create --is-full-object \
                   --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/{resourceTypeName}/{customResourceName} \
                   --properties \
                    '{
                        "location": "eastus",
                        "properties": {
                            "myProperty1": "myPropertyValue1",
                            "myProperty2": {
                                "myProperty3": "myPropertyValue3"
                            }
                        }
                    }'

Eliminare una risorsa personalizzata di Azure:

az resource delete --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/{resourceTypeName}/{customResourceName}

Recuperare una risorsa personalizzata di Azure:

az resource show --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/{resourceTypeName}/{customResourceName}

Modello di Azure Resource Manager

I modelli di Azure Resource Manager richiedono che id, namee type vengano restituiti correttamente dall'endpoint downstream. Una risposta di risorsa restituita deve essere nel formato seguente:

Risposta dell'endpoint di esempio:

{
  "properties": {
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3": "myPropertyValue3"
    }
  },
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{customResourceName}",
  "name": "{customResourceName}",
  "type": "Microsoft.CustomProviders/resourceProviders/{resourceTypeName}"
}

Modello di Azure Resource Manager di esempio:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "type": "Microsoft.CustomProviders/resourceProviders/{resourceTypeName}",
            "name": "{resourceProviderName}/{customResourceName}",
            "apiVersion": "2018-09-01-preview",
            "location": "eastus",
            "properties": {
                "myProperty1": "myPropertyValue1",
                "myProperty2": {
                    "myProperty3": "myPropertyValue3"
                }
            }
        }
    ]
}

Passaggi successivi

• Panoramica sui provider di risorse personalizzate di Azure
• Avvio rapido: Creare un provider di risorse personalizzate e distribuire le risorse personalizzate
• Esercitazione: creare azioni e risorse personalizzate in Azure
• Procedura: aggiunta di azioni personalizzate all'API REST di Azure
• Informazioni di riferimento per il proxy di risorse personalizzate
• Informazioni di riferimento per la cache di risorse personalizzate