Como adicionar recursos personalizados à API REST do Azure

Artigo
06/01/2023

Este artigo abordará os requisitos e as melhores práticas para a criação de pontos de extremidade do Provedor de Recursos Personalizados do Azure que implementam recursos personalizados. Se você não conhecer os Provedores de Recursos Personalizados do Azure, confira a visão geral dos provedores de recursos personalizados.

Como definir o ponto de extremidade de um recurso

Um ponto de extremidade é uma URL que aponta para um serviço, que implementa o contrato subjacente entre ele e o Azure. O ponto de extremidade é definido no provedor de recursos personalizado e pode ser qualquer URL acessível publicamente. O exemplo a seguir tem um resourceType chamado myCustomResource implementado por 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}"
}

Criando um ponto de extremidade de recurso

Um ponto de extremidade que implementa um resourceType deve gerenciar a solicitação e a resposta para a nova API no Azure. Quando um provedor de recursos personalizado com um resourceType é criado, ele gera um novo conjunto de APIs no Azure. Nesse caso, o resourceType vai gerar uma nova API do Recurso do Azure para PUT, GET e DELETE a fim de executar CRUD em apenas um recurso, bem como GET para recuperar todos os recursos existentes:

Manipular recurso único (PUT, GET e DELETE):

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

Recuperar todos os recursos (GET):

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

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

tipo de roteamento com proxy

Os proxies routingType "Proxy" direcionam todos os todos métodos de solicitação para o ponto de extremidade especificado no provedor de recursos personalizado. Quando usar "Proxy":

É necessário controle total sobre a resposta.
Integração de sistemas com recursos existentes.

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

tipo de roteamento do cache de proxy

Os proxies routingType "Proxy, Cache" direcionam apenas os métodos de solicitação PUT e DELETE para o ponto de extremidade especificado no provedor de recursos personalizado. O provedor de recursos personalizado retornará automaticamente solicitações GET com base no que ele armazenou no cache dele. Se um recurso personalizado for marcado com cache, o provedor de recursos personalizado também adicionará/substituirá campos na resposta para tornar as APIs em conformidade com o Azure. Quando usar "Proxy, Cache":

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

Para saber mais sobre os recursos de "Proxy, Cache", confira a referência de cache de recurso personalizado

Criando um recurso personalizado

Há duas maneiras principais de criar um recurso personalizado com base em um provedor 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	Obrigatório	Descrição
is-full-object	sim	Indica que o objeto de propriedades inclui outras opções, como localização, tags, SKU e/ou plano.
id	sim	A ID de recurso referente ao recurso personalizado. Isso deve existir com base no ResourceProvider
properties	sim	O corpo da solicitação que será enviado ao ponto de extremidade.

Excluir um Recurso Personalizado do Azure:

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

Parâmetro	Obrigatório	Descrição
id	sim	A ID de recurso referente ao recurso personalizado. Isso deve existir fora do ResourceProvider.

Recuperar um Recurso Personalizado do Azure:

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

Parâmetro	Obrigatório	Descrição
id	sim	A ID de recurso referente ao recurso personalizado. Isso deve existir com base no ResourceProvider

Modelo do Azure Resource Manager

Observação

Os recursos exigem que a resposta contenha id, name e type apropriados do ponto de extremidade.

Os Modelos do Azure Resource Manager exigem que id, name e type sejam retornados corretamente do ponto de extremidade downstream. Uma resposta de recurso retornada deve estar no formato:

Exemplo de resposta do ponto de extremidade:

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

Parâmetro	Obrigatório	Descrição
resourceTypeName	sim	O nome do resourceType definido no provedor de recursos personalizados.
resourceProviderName	sim	O nome da instância do provedor de recursos personalizado.
customResourceName	sim	O nome do recurso personalizado.

Compartilhar via