Ajout de ressources personnalisées à l’API REST Azure

Article
04/11/2023

Cet article passera par les conditions requises et les meilleures pratiques pour créer des points de terminaison de fournisseur de ressources personnalisées Azure qui implémentent les ressources personnalisées. Si vous n’êtes pas familiarisé avec les fournisseurs de ressources personnalisées Azure, consultez la vue d’ensemble des fournisseurs de ressources personnalisées.

Comment définir un point de terminaison de ressource

Un point de terminaison est une URL qui pointe vers un service, qui implémente le contrat sous-jacent entre ce dernier et Azure. Le point de terminaison est défini dans le fournisseur de ressources personnalisées. Il peut s’agir de n’importe quelle URL accessible publiquement. L’exemple ci-dessous a un resourceType appelé myCustomResource implémenté par endpointURL.

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

Création d’un point de terminaison de ressource

Un point de terminaison qui implémente un resourceType doit gérer la requête et la réponse pour la nouvelle API dans Azure. Lorsqu’un fournisseur de ressources personnalisées avec un resourceType est créé, il génère un nouvel ensemble d’API dans Azure. Dans ce cas, le resourceType génère une nouvelle API de ressource Azure pour PUT, GET et DELETE afin d’exécuter CRUD sur une ressource unique, ainsi que GET pour récupérer toutes les ressources existantes :

Manipuler une ressource unique (PUT, GET et DELETE) :

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

Récupérer toutes les ressources (GET) :

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

En ce qui concerne les ressources personnalisées, les fournisseurs de ressources personnalisées proposent deux types de routingTypes : « Proxy» et « Proxy, Cache ».

type de routage proxy

Le routingType « Proxy » envoie par proxy toutes les méthodes de requête vers le point de terminaison spécifié dans le fournisseur de ressources personnalisées. Quand utiliser «Proxy » :

Un contrôle total sur la réponse est nécessaire.
Intégration de systèmes à des ressources existantes.

Pour en savoir plus sur les ressources « Proxy », consultez Informations de référence sur les proxys de ressources personnalisées

type de routage de cache de proxy

Le routingType « Proxy, Cache » envoie par proxy les méthodes de requête PUT et DELETE uniquement vers le point de terminaison spécifié dans le fournisseur de ressources personnalisées. Le fournisseur de ressources personnalisées renvoie automatiquement les requêtes GET en fonction de ce qui est stocké dans son cache. Si une ressource personnalisée est marquée avec un cache, le fournisseur de ressources personnalisées ajoute/remplace également des champs dans la réponse pour que les API soient compatibles avec Azure. Quand utiliser «Proxy, Cache » :

Création d’un nouveau système ne contenant aucune ressource existante.
Utiliser un écosystème Azure existant.

Pour en savoir plus sur les ressources « Proxy, Cache », consultez Informations de référence sur les caches de ressources personnalisées

Création d’une ressource personnalisée

Deux méthodes permettent de créer une ressource personnalisée dans un fournisseur de ressources personnalisées :

Azure CLI
Modèles Azure Resource Manager

Azure CLI

Créer une ressource personnalisée :

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

Paramètre	Obligatoire	Description
is-full-object	Oui	Indique que l’objet properties inclut d’autres options telles que l’emplacement, les étiquettes, une référence SKU et/ou un plan.
id	Oui	ID de ressource de la ressource personnalisée. Il doit provenir de ResourceProvider
properties	Oui	Corps de la demande qui sera envoyé au point de terminaison.

Supprimer une ressource personnalisée Azure :

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

Paramètre	Obligatoire	Description
id	Oui	ID de ressource de la ressource personnalisée. Il doit provenir de ResourceProvider.

Récupérer une ressource personnalisée Azure :

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

Paramètre	Obligatoire	Description
id	Oui	ID de ressource de la ressource personnalisée. Il doit provenir de ResourceProvider

Modèle Azure Resource Manager

Notes

Les ressources nécessitent que la réponse contienne un id, name et type appropriés du point de terminaison.

Les modèles Azure Resource Manager nécessitent que id, name et type soient retournés correctement du point de terminaison en aval. Une réponse de ressource retournée doit se présenter sous la forme suivante :

Exemple de réponse de point de terminaison :

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

Exemple de modèle Azure Resource Manager :

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

Paramètre	Obligatoire	Description
resourceTypeName	Oui	Nom du resourceType défini dans le fournisseur de ressources personnalisées.
resourceProviderName	Oui	Nom de l’instance de fournisseur de ressources personnalisées.
customResourceName	Oui	Nom de la ressource personnalisée.