使用 REST 建立、執行和刪除 Azure Machine Learning 資源

有數種方式可管理您的 Azure Machine Learning 資源。 您可以使用入口網站命令列介面或是 Python SDK。 或者,您可以選擇使用 REST API。 REST API 使用標準的 HTTP 指令動詞來建立、擷取、更新和刪除資源。 REST API 適用於任何可發出 HTTP 要求的語言或工具。 REST 的簡單結構使其成為指令碼環境及 MLOps 自動化的理想選擇。

在本文中,您將學會如何:

  • 擷取授權權杖
  • 使用服務主體驗證建立格式正確的 REST 要求
  • 使用 GET 要求取得 Azure Machine Learning 階層式資源的相關資訊
  • 使用 PUT 和 POST 要求來建立和修改資源
  • 使用 PUT 要求來建立 Azure Machine Learning 工作區
  • 使用 DELETE 要求來清除資源

必要條件

取得服務主體驗證權杖

系統管理 REST 要求會使用 OAuth2 隱含流程進行驗證。 此驗證流程會使用您訂用帳戶服務主體所提供的權杖。 若要取得此權杖,您將需要:

  • 您的租用戶識別碼 (識別訂用帳戶所屬的組織)
  • 您的用戶端識別碼 (將關聯至建立的權杖)
  • 您的用戶端密碼 (應加以保護)

您應該會在建立服務主體的回應中取得這些值。 如需取得這些值的詳細資訊,請參閱設定 Azure Machine Learning 資源和工作流程的驗證。 如果您使用公司訂用帳戶,則您可能沒有建立服務主體的權限。 在這種情況下,您應該使用免費或付費的個人訂用帳戶

若要取得權杖:

  1. 開啟終端機視窗
  2. 在命令列中輸入下列程式碼
  3. 請將 <YOUR-TENANT-ID><YOUR-CLIENT-ID><YOUR-CLIENT-SECRET> 替換為您自己的值。 在本文中,以角括弧括住的字串是您必須以適當值取代的變數。
  4. 執行命令
curl -X POST https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/token \
-d "grant_type=client_credentials&resource=https%3A%2F%2Fmanagement.azure.com%2F&client_id=<YOUR-CLIENT-ID>&client_secret=<YOUR-CLIENT-SECRET>" \

回應應提供有效期為一個小時的存取權杖:

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1578523094",
    "not_before": "1578519194",
    "resource": "https://management.azure.com/",
    "access_token": "YOUR-ACCESS-TOKEN"
}

請記下權杖,因為您將使用此權杖來驗證所有管理要求。 驗證方式是在所有要求中,設定授權標頭:

curl -h "Authorization:Bearer <YOUR-ACCESS-TOKEN>" ...more args...

注意

值的開頭為 "Bearer " 字串,包括單一空格,然後再新增權杖。

取得與您訂用帳戶相關聯的資源群組清單

若要取得與您訂用帳戶相關聯的資源群組清單,請執行:

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups?api-version=2022-04-01 -H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

在 Azure 範圍內有許多已發佈的 REST API。 每個服務提供者都會以自己的步調更新其 API,但是並不會中斷現有的程式。 服務提供者使用 api-version 引數來確保相容性。

重要

api-version 引數變數會因服務而異。 例如針對 Machine Learning 服務,目前的 API 版本為 2023-10-01; 若要尋找其他 Azure 服務的最新 API 版本,請參閱特定服務的 Azure REST API 參考

所有 REST 呼叫都應該會將 api-version 引數設定為預期的值。 即使 API 版本持續演進,您也可以依賴特定版本的語法和語義。 如果您將沒有 api-version 引數的要求傳送給提供者,則回應將會包含人類可閱讀的支援值清單。

上述呼叫將會產生下列格式的壓縮 JSON 回應:

{
    "value": [
        {
            "id": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourceGroups/RG1",
            "name": "RG1",
            "type": "Microsoft.Resources/resourceGroups",
            "location": "westus2",
            "properties": {
                "provisioningState": "Succeeded"
            }
        },
        {
            "id": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourceGroups/RG2",
            "name": "RG2",
            "type": "Microsoft.Resources/resourceGroups",
            "location": "eastus",
            "properties": {
                "provisioningState": "Succeeded"
            }
        }
    ]
}

深入了解工作區及其資源

若要在資源群組中取出工作區集合,請執行下列動作,並取代 <YOUR-SUBSCRIPTION-ID><YOUR-RESOURCE-GROUP><YOUR-ACCESS-TOKEN>

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

您同樣會收到 JSON 清單,這一次包含清單,其中每個項目都會詳細說明工作區:

{
    "id": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourceGroups/DeepLearningResourceGroup/providers/Microsoft.MachineLearningServices/workspaces/my-workspace",
    "name": "my-workspace",
    "type": "Microsoft.MachineLearningServices/workspaces",
    "location": "centralus",
    "tags": {},
    "etag": null,
    "properties": {
        "friendlyName": "",
        "description": "",
        "creationTime": "2023-01-03T19:56:09.7588299+00:00",
        "storageAccount": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourcegroups/DeepLearningResourceGroup/providers/microsoft.storage/storageaccounts/myworkspace0275623111",
        "containerRegistry": null,
        "keyVault": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourcegroups/DeepLearningResourceGroup/providers/microsoft.keyvault/vaults/myworkspace2525649324",
        "applicationInsights": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourcegroups/DeepLearningResourceGroup/providers/microsoft.insights/components/myworkspace2053523719",
        "hbiWorkspace": false,
        "workspaceId": "cba12345-abab-abab-abab-ababab123456",
        "subscriptionState": null,
        "subscriptionStatusChangeTimeStampUtc": null,
        "discoveryUrl": "https://centralus.experiments.azureml.net/discovery"
    },
    "identity": {
        "type": "SystemAssigned",
        "principalId": "abcdef1-abab-1234-1234-abababab123456",
        "tenantId": "1fedcba-abab-1234-1234-abababab123456"
    },
    "sku": {
        "name": "Basic",
        "tier": "Basic"
    }
}

若要使用工作區中的資源,您將從一般 management.azure.com 伺服器切換至工作區位置專屬的 REST API 伺服器。 請注意上方 JSON 回應中 discoveryUrl 金鑰的值。 如果您透過 GET 取得該 URL,則會收到類似下列的回應:

{
  "api": "https://centralus.api.azureml.ms",
  "catalog": "https://catalog.cortanaanalytics.com",
  "experimentation": "https://centralus.experiments.azureml.net",
  "gallery": "https://gallery.cortanaintelligence.com/project",
  "history": "https://centralus.experiments.azureml.net",
  "hyperdrive": "https://centralus.experiments.azureml.net",
  "labeling": "https://centralus.experiments.azureml.net",
  "modelmanagement": "https://centralus.modelmanagement.azureml.net",
  "pipelines": "https://centralus.aether.ms",
  "studiocoreservices": "https://centralus.studioservice.azureml.com"
}

api 回應的值是伺服器的 URL,可用於更多要求。 舉例來說,若要列出實驗,請傳送下列命令。 使用 api 回應的值 (例如 centralus.api.azureml.ms) 取代 REGIONAL-API-SERVER。 同時一樣取代 YOUR-SUBSCRIPTION-IDYOUR-RESOURCE-GROUPYOUR-WORKSPACE-NAMEYOUR-ACCESS-TOKEN

curl https://<REGIONAL-API-SERVER>/history/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/experiments?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

同樣地,若要在您的工作區中取出已註冊的模型,請傳送:

curl https://<REGIONAL-API-SERVER>/modelmanagement/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/models?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

請注意,若要列出實驗,路徑的開頭為 history/v1.0,若要列出模型,則路徑的開頭為 modelmanagement/v1.0。 REST API 分成數個作業群組,每個都具有不同的路徑。

區域 路徑
Artifacts /rest/api/azureml
資料存放區 /azure/machine-learning/how-to-access-data
超參數微調 hyperdrive/v1.0/
模型 modelmanagement/v1.0/
執行歷程記錄 execution/v1.0/ and history/v1.0/

您可以使用下列一般模式來探索 REST API:

URL 元件 範例
https://
區域 API 伺服器/ centralus.api.azureml.ms/
operations-path/ history/v1.0/
subscriptions/您的訂用帳戶識別碼/ subscriptions/abcde123-abab-abab-1234-0123456789abc/
resourceGroups/您的資源群組/ resourceGroups/MyResourceGroup/
providers/operation-provider/ providers/Microsoft.MachineLearningServices/
provider-resource-path/ workspaces/MyWorkspace/experiments/FirstExperiment/runs/1/
operations-endpoint/ artifacts/metadata/

使用 PUT 和 POST 要求來建立和修改資源

除了透過 GET 動詞的資源擷取之外,REST API 還支援建立定型、部署和監視 ML 解決方案所需的所有資源。

定型和執行 ML 模型需要計算資源。 您可以使用下列命令列出工作區的計算資源:

curl https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/computes?api-version=2023-10-01 \
-H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

若要建立或覆寫具名的計算資源,請使用 PUT 要求。 在下列命令中,除了照常取代 YOUR-SUBSCRIPTION-IDYOUR-RESOURCE-GROUPYOUR-WORKSPACE-NAMEYOUR-ACCESS-TOKEN,也請取代 YOUR-COMPUTE-NAME,以及 locationvmSizevmPriorityscaleSettingsadminUserNameadminUserPassword 的值。 下列命令會建立一個專用的單一節點 Standard_D1 (基本 CPU 計算資源),該資源將在 30 分鐘後縮小:

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/computes/<YOUR-COMPUTE-NAME>?api-version=2023-10-01' \
  -H 'Authorization:Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "eastus",
    "properties": {
        "computeType": "AmlCompute",
        "properties": {
            "vmSize": "Standard_D1",
            "vmPriority": "Dedicated",
            "scaleSettings": {
                "maxNodeCount": 1,
                "minNodeCount": 0,
                "nodeIdleTimeBeforeScaleDown": "PT30M"
            }
        }
    },
    "userAccountCredentials": {
        "adminUserName": "<ADMIN_USERNAME>",
        "adminUserPassword": "<ADMIN_PASSWORD>"
    }
}'

注意

在 Windows 的終端中,在傳送 JSON 資料時,您可能必須將雙引號符號逸出。 例如,"location" 這段文字會變成 \"location\"

成功的要求將會收到 201 Created 回應,但請注意,此回應只是表示佈建流程已開始。 您必須輪詢 (或使用入口網站) 來確認流程成功完成。

使用 REST 建立工作區

每個 Azure Machine Learning 工作區都依賴於其他四個 Azure 資源:Azure Container Registry 資源、Azure Key Vault、Azure Application Insights 和 Azure 儲存體帳戶。 必須具備這些資源,才能建立工作區。 如需建立每個這類資源的詳細資訊,請參閱 REST API 參考資料。

若要建立工作區,請將類似下列的呼叫透過 PUT 放入至 management.azure.com。 雖然此呼叫需要您設定大量變數,但其結構與本文所討論的其他呼叫相同。

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "AZURE-LOCATION>",
    "identity" : {
        "type" : "systemAssigned"
    },
    "properties": {
        "friendlyName" : "<YOUR-WORKSPACE-FRIENDLY-NAME>",
        "description" : "<YOUR-WORKSPACE-DESCRIPTION>",
        "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
        keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
        "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
        "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>"
    }
}'

您應該會收到 202 Accepted 回應,並在傳回的標頭中收到 Location URI。 您可以對此 URI 執行 GET 以取得部署的相關資訊,包括有用的偵錯資訊,如果您的其中一個相依資源發生問題,例如您忘記在容器上啟用系統管理員存取權等。

透過使用者指派的受控識別來建立工作區

建立工作區時,您可以指定使用者指派的受控識別,以用來存取相關聯的資源:ACR、KeyVault、Storage 和 App Insights。 若要建立具有使用者所指派受控識別的工作區,請使用下列要求本文。

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "AZURE-LOCATION>",
    "identity": {
      "type": "SystemAssigned,UserAssigned",
      "userAssignedIdentities": {
        "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ManagedIdentity/userAssignedIdentities/<YOUR-MANAGED-IDENTITY>": {}
      }
    },
    "properties": {
        "friendlyName" : "<YOUR-WORKSPACE-FRIENDLY-NAME>",
        "description" : "<YOUR-WORKSPACE-DESCRIPTION>",
        "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
        keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
        "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
        "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>"
    }
}'

使用客戶管理的加密金鑰來建立工作區

根據預設,工作區的中繼資料會儲存在 Microsoft 所維護的 Azure Cosmos DB 執行個體中。 此資料會使用 Microsoft 受控金鑰進行加密。 您也可以提供自己的金鑰,而不使用 Microsoft 管理的金鑰。 此方法會在您的 Azure 訂用帳戶中建立另一組資源來儲存資料。

若要建立使用您的金鑰進行加密的工作區,您必須滿足下列必要條件:

  • Azure Machine Learning 服務主體必須具有您 Azure 訂用帳戶的參與者存取權。
  • 您必須具有包含加密金鑰的現有 Azure Key Vault。
  • Azure Key Vault 必須位於要建立 Azure Machine Learning 工作區的相同 Azure 區域中。
  • Azure Key Vault 必須啟用虛刪除和清除保護,以防止在意外刪除時遺失資料。
  • 您必須在 Azure Key Vault 中擁有存取原則,以授與取得、包裝和解除包裝等 Azure Cosmos DB 應用程式存取權。

若要以使用者指派的受控識別建立工作區,並使用客戶管理的金鑰進行加密,請使用下列要求本文。 針對工作區使用使用者指派的受控識別時,也請將 userAssignedIdentity 屬性設定為受控識別的資源識別碼。

curl -X PUT \
  'https://management.azure.com/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-NEW-WORKSPACE-NAME>?api-version=2023-10-01' \
  -H 'Authorization: Bearer <YOUR-ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "eastus2euap",
    "identity": {
      "type": "SystemAssigned"
    },
    "properties": {
      "friendlyName": "<YOUR-WORKSPACE-FRIENDLY-NAME>",
      "description": "<YOUR-WORKSPACE-DESCRIPTION>",
      "containerRegistry" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.ContainerRegistry/registries/<YOUR-REGISTRY-NAME>",
      "keyVault" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>\
/providers/Microsoft.Keyvault/vaults/<YOUR-KEYVAULT-NAME>",
      "applicationInsights" : "subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.insights/components/<YOUR-APPLICATION-INSIGHTS-NAME>",
      "storageAccount" : "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.Storage/storageAccounts/<YOUR-STORAGE-ACCOUNT-NAME>",
      "encryption": {
        "status": "Enabled",
        "identity": {
          "userAssignedIdentity": null
        },      
        "keyVaultProperties": {
           "keyVaultArmId": "/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/\
providers/Microsoft.KeyVault/vaults/<YOUR-VAULT>",
           "keyIdentifier": "https://<YOUR-VAULT>.vault.azure.net/keys/<YOUR-KEY>/<YOUR-KEY-VERSION>",
           "identityClientId": ""
        }
      },
      "hbiWorkspace": false
    }
}'

刪除不再需要的資源

部分 (但非全部) 資源支援 DELETE 動詞。 在認可 REST API 執行刪除使用案例前,請參閱 API 參考資料。 舉例來說,若要刪除模型,您可以使用:

curl
  -X DELETE \
'https://<REGIONAL-API-SERVER>/modelmanagement/v1.0/subscriptions/<YOUR-SUBSCRIPTION-ID>/resourceGroups/<YOUR-RESOURCE-GROUP>/providers/Microsoft.MachineLearningServices/workspaces/<YOUR-WORKSPACE-NAME>/models/<YOUR-MODEL-ID>?api-version=2022-05-01' \
  -H 'Authorization:Bearer <YOUR-ACCESS-TOKEN>' 

疑難排解

資源提供者錯誤

建立 Azure Machine Learning 工作區或工作區所使用的資源時,您可能會收到類似下列訊息的錯誤:

  • No registered resource provider found for location {location}
  • The subscription is not registered to use namespace {resource-provider-namespace}

大部分資源提供者都會自動註冊,但並非全部。 如果您收到此訊息,則需要註冊先前提及的提供者。

下表包含 Azure Machine Learning 所需的資源提供者清單:

資源提供者 需要的原因
Microsoft.MachineLearningServices 建立 Azure Machine Learning 工作區。
Microsoft.Storage Azure 儲存體帳戶用來做為工作區的預設儲存體。
Microsoft.ContainerRegistry 工作區會使用 Azure Container Registry 來建置 Docker 映像。
Microsoft.KeyVault 工作區會使用 Azure Key Vault 來儲存秘密。
Microsoft.Notebooks Azure Machine Learning 計算執行個體上的整合式筆記本。
Microsoft.ContainerService 若您打算將已定型的模型部署至 Azure Kubernetes Service。

若您打算搭配 Azure Machine Learning 使用客戶自控金鑰,則必須註冊下列服務提供者:

資源提供者 需要的原因
Microsoft.DocumentDB 記錄工作區中繼資料的 Azure CosmosDB 執行個體。
Microsoft.Search Azure 搜尋可為工作區提供索引編製功能。

如果您打算搭配 Azure Machine Learning 使用受控虛擬網路,則必須註冊 Microsoft.Network 資源提供者。 建立受控虛擬網路的私人端點時,工作區會使用此資源提供者。

如需有關註冊資源提供者的詳細資訊,請參閱解決資源提供者註冊的錯誤

移動工作區

警告

不支援將 Azure Machine Learning 工作區移至不同的訂用帳戶,或將擁有的訂用帳戶移至新租用戶。 這麼做可能會導致錯誤。

刪除 Azure Container Registry

Azure Machine Learning 工作區會使用 Azure Container Registry (ACR) 進行某些作業。 它會在第一次需要 ACR 執行個體時自動建立一個。

警告

為工作區建立 Azure Container Registry 之後,請勿將其刪除。 這樣做將會造成您的 Azure Machine Learning 工作區中斷。

下一步