Dodawanie akcji niestandardowych do interfejsu API REST platformy Azure

Artykuł
06/01/2023

W tym artykule przedstawiono wymagania i najlepsze rozwiązania dotyczące tworzenia punktów końcowych niestandardowego dostawcy zasobów platformy Azure, które implementują akcje niestandardowe. Jeśli nie znasz dostawców zasobów niestandardowych platformy Azure, zapoznaj się z omówieniem niestandardowych dostawców zasobów.

Jak zdefiniować punkt końcowy akcji

Punkt końcowy to adres URL wskazujący usługę, która implementuje bazowy kontrakt między nim a platformą Azure. Punkt końcowy jest zdefiniowany w niestandardowym dostawcy zasobów i może być dowolnym publicznie dostępnym adresem URL. Poniższy przykład zawiera akcję o nazwie myCustomAction zaimplementowaną przez endpointURLprogram .

Przykładowy zasóbProvider:

{
  "properties": {
    "actions": [
      {
        "name": "myCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus",
  "type": "Microsoft.CustomProviders/resourceProviders",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
  "name": "{resourceProviderName}"
}

Tworzenie punktu końcowego akcji

Punkt końcowy, który implementuje akcję, musi obsługiwać żądanie i odpowiedź dla nowego interfejsu API na platformie Azure. Po utworzeniu niestandardowego dostawcy zasobów z akcją zostanie wygenerowany nowy zestaw interfejsów API na platformie Azure. W takim przypadku akcja wygeneruje nowy interfejs API akcji platformy Azure dla POST wywołań:

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

Żądanie przychodzące interfejsu API platformy Azure:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction?api-version=2018-09-01-preview
Authorization: Bearer eyJ0e...
Content-Type: application/json

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

To żądanie zostanie następnie przekazane do punktu końcowego w formularzu:

POST https://{endpointURL}/?api-version=2018-09-01-preview
Content-Type: application/json
X-MS-CustomProviders-RequestPath: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Podobnie odpowiedź z punktu końcowego jest następnie przekazywana z powrotem do klienta. Odpowiedź z punktu końcowego powinna zwrócić:

Prawidłowy dokument obiektu JSON. Wszystkie tablice i ciągi powinny być zagnieżdżone w górnej części obiektu.
Nagłówek Content-Type powinien być ustawiony na wartość "application/json; charset=utf-8".

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Odpowiedź niestandardowego dostawcy zasobów platformy Azure:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

Wywoływanie akcji niestandardowej

Istnieją dwa główne sposoby wywoływania akcji niestandardowej od niestandardowego dostawcy zasobów:

Interfejs wiersza polecenia platformy Azure
Szablony usługi Azure Resource Manager

Interfejs wiersza polecenia platformy Azure

az resource invoke-action --action {actionName} \
                          --ids /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName} \
                          --request-body \
                            '{
                                "myProperty1": "myPropertyValue1",
                                "myProperty2": {
                                    "myProperty3": "myPropertyValue3"
                                }
                            }'

Parametr	Wymagane	Opis
action	Tak	Nazwa akcji zdefiniowanej w elemecie ResourceProvider.
Identyfikatory	Tak	Identyfikator zasobu dostawcy zasobów.
treść żądania	Nr	Treść żądania, która zostanie wysłana do punktu końcowego.

Szablon usługi Azure Resource Manager

Uwaga

Akcje mają ograniczoną obsługę szablonów usługi Azure Resource Manager. Aby akcja została wywołana wewnątrz szablonu, musi zawierać list prefiks w nazwie.

Przykładowy zasóbProvider z akcją listy:

{
  "properties": {
    "actions": [
      {
        "name": "listMyCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus"
}

Przykładowy szablon usługi Azure Resource Manager:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "variables": {
        "resourceIdentifier": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
        "apiVersion": "2018-09-01-preview",
        "functionValues": {
            "myProperty1": "myPropertyValue1",
            "myProperty2": {
                "myProperty3": "myPropertyValue3"
            }
        }
    },
    "resources": [],
    "outputs": {
        "myCustomActionOutput": {
            "type": "object",
            "value": "[listMyCustomAction(variables('resourceIdentifier'), variables('apiVersion'), variables('functionValues'))]"
        }
    }
}

Parametr	Wymagane	Opis
resourceIdentifier	Tak	Identyfikator zasobu dostawcy zasobów.
apiVersion	Tak	Wersja interfejsu API środowiska uruchomieniowego zasobów. Powinna to być zawsze wartość "2018-09-01-preview".
functionValues	Nr	Treść żądania, która zostanie wysłana do punktu końcowego.