將自訂動作新增至 Azure REST API

發行項
03/25/2024

本文將逐一解說建立要實作自訂動作的 Azure 自訂資源提供者端點之需求和最佳做法。如果您不熟悉 Azure 自訂資源提供者，請參閱自訂資源提供者概觀。

如何定義動作端點

端點是指向服務的 URL，此服務會在其與 Azure 之間實作基礎合約。端點是在自訂資源提供者中定義，可以是任何可公開存取的 URL。下列範例有一個名為 myCustomAction 的動作，由 endpointURL 實作。

範例 ResourceProvider：

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

建置動作端點

實作動作的端點必須處理 Azure 中新 API 的要求和回應。建立具有動作的自訂資源提供者時，會在 Azure 中產生一組新的 API。在此情況下，此動作會產生新的 Azure 動作 API 以進行 POST 呼叫：

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

Azure API 傳入要求：

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

接著會以下列格式將此要求轉送至端點：

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

同樣地，系統也會將來自端點的回應轉送回給客戶。端點的回應應傳回：

有效的 JSON 物件文件。所有陣列和字串都應該在最上層物件下方巢狀化。
Content-Type 標頭應該設定為 "application/json; charset=utf-8"。

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

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

Azure 自訂資源提供者回應：

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

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

呼叫自訂動作

從自訂資源提供者呼叫自訂動作主要有兩種方式：

Azure CLI
Azure Resource Manager 範本

Azure CLI

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

參數	必要	描述
action	是	ResourceProvider 中定義的動作名稱。
ids	是	ResourceProvider 的資源識別碼。
request-body	否	將傳送至端點的要求本文。

Azure Resource Manager 範本

注意

動作在 Azure Resource Manager 範本中受到的支援有限。為了能在範本內呼叫動作，其名稱中必須包含 list 首碼。

具有清單動作的範例 ResourceProvider：

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

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

參數	必要	描述
resourceIdentifier	是	ResourceProvider 的資源識別碼。
apiVersion	是	資源執行階段的 API 版本。此版本應一律為 "2018-09-01-preview"。
functionValues	否	將傳送至端點的要求本文。

共用方式為