Aggiunta di risorse personalizzate all'API REST di Azure

Articolo
05/27/2024

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

Parametro	Richiesto	Descrizione
is-full-object	yes	Indica che l'oggetto proprietà include altre opzioni, come location, tags, sku, e/o plan.
id	yes	ID della risorsa personalizzata. L'elemento deve esistere all'esterno di ResourceProvider
proprietà	yes	Il corpo della richiesta che verrà inviato all'endpoint.

Eliminare una risorsa personalizzata di Azure:

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

Parametro	Richiesto	Descrizione
id	yes	ID della risorsa personalizzata. L'elemento deve esistere all'esterno di ResourceProvider.

Recuperare una risorsa personalizzata di Azure:

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

Parametro	Richiesto	Descrizione
id	yes	ID della risorsa personalizzata. L'elemento deve esistere all'esterno di ResourceProvider

Modello di Azure Resource Manager

Nota

Le risorse richiedono che la risposta contenga un oggetto id,name e type appropriato dall'endpoint.

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

Parametro	Richiesto	Descrizione
resourceTypeName	yes	Il nome del resourceType definito nel provider di risorse personalizzate.
resourceProviderName	yes	Nome dell'istanza del provider di risorse personalizzate.
customResourceName	yes	Nome della risorsa personalizzata.

Condividi tramite