Adicionar Recursos Personalizados à API REST do Azure

Artigo
06/01/2023

Este artigo irá analisar os requisitos e as melhores práticas para criar pontos finais do Fornecedor de Recursos Personalizados do Azure que implementam recursos personalizados. Se não estiver familiarizado com os Fornecedores de Recursos Personalizados do Azure, veja a descrição geral dos fornecedores de recursos personalizados.

Como definir um ponto final de recurso

Um ponto final é um URL que aponta para um serviço, que implementa o contrato subjacente entre o mesmo e o Azure. O ponto final é definido no fornecedor de recursos personalizado e pode ser qualquer URL acessível publicamente. O exemplo abaixo tem um resourceType chamado myCustomResource implementado pelo endpointURL.

ResourceProvider de Exemplo:

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

Criar um ponto final de recurso

Um ponto final que implementa um resourceType tem de processar o pedido e a resposta para a nova API no Azure. Quando um fornecedor de recursos personalizado com um resourceType é criado, irá gerar um novo conjunto de APIs no Azure. Neste caso, o resourceType irá gerar uma nova API de recursos do Azure para PUT, GETe DELETE para executar CRUD num único recurso, bem como GET para obter todos os recursos existentes:

Manipular Recurso Único (PUT, GETe DELETE):

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

Obter Todos os Recursos (GET):

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

Para recursos personalizados, os fornecedores de recursos personalizados oferecem dois tipos de routingTypes: "Proxy" e "Proxy, Cache".

Tipo de encaminhamento de proxy

O routingType "Proxy" proxie todos os métodos de pedido para o ponto final especificado no fornecedor de recursos personalizado. Quando utilizar "Proxy":

É necessário controlo total sobre a resposta.
Integrar sistemas com recursos existentes.

Para saber mais sobre os recursos "Proxy", veja a referência do proxy de recursos personalizado

Tipo de encaminhamento de cache de proxy

O routingType "Proxy, Cache" proxies apenas PUT e DELETE solicita métodos para o ponto final especificado no fornecedor de recursos personalizado. O fornecedor de recursos personalizado devolverá GET automaticamente pedidos com base no que armazenou na respetiva cache. Se um recurso personalizado estiver marcado com cache, o fornecedor de recursos personalizado também adicionará/substituirá campos na resposta para tornar as APIs compatíveis com o Azure. Quando utilizar "Proxy, Cache":

Criar um novo sistema que não tem recursos existentes.
Trabalhe com o ecossistema do Azure existente.

Para saber mais sobre os recursos "Proxy, Cache", veja a referência da cache de recursos personalizada

Criar um recurso personalizado

Existem duas formas principais de criar um recurso personalizado a partir de um fornecedor de recursos personalizado:

CLI do Azure
Modelos do Azure Resource Manager

CLI do Azure

Criar um recurso personalizado:

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

Parâmetro	Necessário	Descrição
is-full-object	sim	Indica que o objeto de propriedades inclui outras opções, como localização, etiquetas, sku e/ou plano.
ID	sim	O ID de recurso do recurso personalizado. Isto deve existir fora do ResourceProvider
propriedades	sim	O corpo do pedido que será enviado para o ponto final.

Eliminar um Recurso Personalizado do Azure:

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

Parâmetro	Necessário	Descrição
ID	sim	O ID de recurso do recurso personalizado. Isto deve existir fora do ResourceProvider.

Obter um Recurso Personalizado do Azure:

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

Parâmetro	Necessário	Descrição
ID	sim	O ID de recurso do recurso personalizado. Isto deve existir fora do ResourceProvider

Modelo do Azure Resource Manager

Nota

Os recursos exigem que a resposta contenha um , namee type adequado iddo ponto final.

Os Modelos de Resource Manager do Azure necessitam de id, namee type são devolvidos corretamente a partir do ponto final a jusante. Uma resposta de recurso devolvida deve estar no formulário:

Resposta do ponto final de exemplo :

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

Modelo de Resource Manager do Azure de exemplo:

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

Parâmetro	Necessário	Descrição
resourceTypeName	sim	O nome do resourceType definido no fornecedor de recursos personalizado.
resourceProviderName	sim	O nome da instância do fornecedor de recursos personalizado.
customResourceName	sim	O nome do recurso personalizado.

Partilhar via