Aggiunta di risorse personalizzate all'API REST di Azure

Articolo
06/01/2023

Questo articolo illustra i requisiti e le procedure consigliate per la creazione di endpoint provider di risorse personalizzati di Azure che implementano risorse personalizzate. Se non si ha familiarità con i provider di risorse personalizzati di Azure, vedere la panoramica sui provider di risorse personalizzati.

Come definire un endpoint 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 personalizzato e può essere qualsiasi URL accessibile pubblicamente. L'esempio seguente include una risorsaType denominata myCustomResource implementata da endpointURL.

ResourceProvider di esempio:

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

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 personalizzato con un resourceType , verrà generato un nuovo set di API in Azure. In questo caso, resourceType genererà una nuova API risorsa di Azure per PUT, GETe per eseguire CRUD in una singola risorsa GET e DELETE 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 personalizzati offrono due tipi di routingType: "" e "ProxyProxy, Cache".

tipo di routing proxy

ProxyIl routingType proxy "" di tutti i metodi di richiesta all'endpoint specificato nel provider di risorse personalizzato. Quando usare "Proxy":

È necessario controllare completamente la risposta.
Integrazione di sistemi con risorse esistenti.

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

Tipo di routing della cache proxy

I proxy PUT di routingType "Proxy, Cache" e i metodi di richiesta all'endpointDELETE specificati nel provider di risorse personalizzato. Il provider di risorse personalizzato restituirà GET automaticamente le richieste in base a ciò che ha archiviato nella cache. Se una risorsa personalizzata è contrassegnata con cache, il provider di risorse personalizzato aggiungerà anche/sovrascrivere i campi nella risposta per rendere conformi le API di 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 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 personalizzato:

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	Obbligatoria	Descrizione
is-full-object	Sì	Indica che l'oggetto proprietà include altre opzioni, come location, tags, sku, e/o plan.
id	Sì	ID della risorsa personalizzata. Questa operazione deve essere disattivata da ResourceProvider
properties	Sì	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	Obbligatoria	Descrizione
id	Sì	ID della risorsa personalizzata. Questa operazione deve essere disattivata da ResourceProvider.

Recuperare una risorsa personalizzata di Azure:

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

Parametro	Obbligatoria	Descrizione
id	Sì	ID della risorsa personalizzata. Questa operazione deve essere disattivata da ResourceProvider

Modello di Azure Resource Manager

Nota

Le risorse richiedono che la risposta contenga un idoggetto , namee typedall'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:

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	Obbligatoria	Descrizione
resourceTypeName	Sì	Nome del resourceType definito nel provider di risorse personalizzato.
resourceProviderName	Sì	Nome dell'istanza del provider di risorse personalizzato.
customResourceName	Sì	Nome della risorsa personalizzata.