將自訂資源新增至 Azure REST API

文章
06/01/2023

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

如何定義資源端點

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

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

建置資源端點

實作 resourceType 的端點必須處理 Azure 中新 API 的要求和回應。建立具有 resourceType 的自訂資源提供者時，會在 Azure 中產生一組新的 API。在此案例中，resourceType 會為 PUT、GET 和 DELETE 產生新的 Azure 資源 API，在單一資源上執行 CRUD 及 GET，以取得所有現有的資源：

操作單一資源 (PUT、GET 和 DELETE)：

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

擷取所有資源 (GET)：

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

自訂資源提供者針對自訂資源提供兩種類型的 routingTypes："Proxy" 和 "Proxy, Cache"。

Proxy 路由類型

"Proxy" routingType 會將所有要求方法都通過 Proxy 處理到自訂資源提供者中指定的端點。使用 "Proxy" 的時機：

需要完全控制回應時。
整合系統與現有的資源時。

若要深入了解 "Proxy" 資源，請參閱自訂資源 Proxy 參考

Proxy 快取路由類型

"Proxy, Cache" routingType 只會將 PUT 和 DELETE 要求方法通過 Proxy 處理到自訂資源提供者中指定的端點。自訂資源提供者會根據其在快取中儲存的內容自動傳回 GET 要求。如果自訂資源已標示快取，自訂資源提供者也會新增/覆寫回應中的欄位，讓 API 符合 Azure 規範。使用 "Proxy, Cache" 的時機：

建立沒有現有資源的新系統時。
使用現有的 Azure 生態系統時。

若要深入了解 "Proxy, Cache" 資源，請參閱自訂資源快取參考

建立自訂資源

從自訂資源提供者建立自訂資源有兩個主要方式：

Azure CLI
Azure Resource Manager 範本

Azure CLI

建立自訂資源：

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

參數	必要	描述
is-full-object	是	指出屬性物件包含其他選項，例如位置、標籤、SKU 和/或方案。
id	是	自訂資源的資源識別碼。這應存在於 ResourceProvider 中
內容	是	將傳送至端點的要求本文。

刪除 Azure 自訂資源：

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

參數	必要	描述
id	是	自訂資源的資源識別碼。這應存在於 ResourceProvider 中。

擷取 Azure 自訂資源：

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

參數	必要	描述
id	是	自訂資源的資源識別碼。這應存在於 ResourceProvider 中

Azure Resource Manager 範本

注意

資源要求回應中包含來自端點的適當 id、name 和 type。

Azure Resource Manager 範本要求從下游端點正確傳回 id、name 和 type。傳回的資源回應應該採用下列格式：

端點回應範例：

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

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

參數	必要	描述
resourceTypeName	是	自訂資源提供者中定義的 resourceType 名稱。
resourceProviderName	是	自訂資源提供者執行個體名稱。
customResourceName	是	自訂資源名稱。

分享方式：