使用 REST 创建、运行和删除 Azure 机器学习资源

Artículo
09/13/2024

可通过多种方式管理 Azure 机器学习资源。可以使用门户、命令行接口或 Python SDK。或者，可以选择 REST API。 REST API 使用 HTTP 谓词以标准方式创建、检索、更新和删除资源。 REST API 适用于可发出 HTTP 请求的任何语言或工具。 REST 具有简单的结构，因此它往往是适合脚本编写环境和 MLOps 自动化的良好选择。

在本文中，学习如何：

检索授权令牌
使用服务主体身份验证创建格式正确的 REST 请求
使用 GET 请求检索有关 Azure 机器学习分层资源的信息
使用 PUT 与 POST 请求创建和修改资源
使用 PUT 请求创建 Azure 机器学习工作区
使用 DELETE 请求清理资源

先决条件

你对其拥有管理权限的 Azure 订阅。如果没有此类订阅，请尝试注册免费或付费的个人订阅
一个 Azure 机器学习工作区。
管理 REST 请求使用服务主体身份验证。遵循为 Azure 机器学习资源和工作流设置身份验证中的步骤在工作区中创建服务主体
curl 实用工具。在适用于 Linux 的 Windows 子系统或任何 UNIX 分发版中均已提供了 curl 程序。在 PowerShell 中，curl 是 Invoke-WebRequest 的别名，并且 curl -d "key=val" -X POST uri 变成了 Invoke-WebRequest -Body "key=val" -Method POST -Uri uri。

检索服务主体身份验证令牌

使用 OAuth2 隐式流对管理 REST 请求进行身份验证。此身份验证流使用订阅服务主体提供的令牌。若要检索此令牌，需要提供：

租户 ID（标识订阅所属的组织）
客户端 ID（将与创建的令牌相关联）
客户端机密（应予以保护）

应从创建服务主体的响应中获取这些值。为 Azure 机器学习资源和工作流设置身份验证一文介绍了如何获取这些值。如果使用公司订阅，则可能无权创建服务主体。在这种情况下，应使用免费或付费的个人订阅。

若要检索令牌，请执行以下操作：

打开终端窗口
在命令行中输入以下代码
请将 <YOUR-TENANT-ID>、<YOUR-CLIENT-ID> 和 <YOUR-CLIENT-SECRET> 替换为自己的值。在本文中，用尖括号括住的字符串是变量，你必须将其替换为自己的相应值。
运行命令

curl -X POST https://login.chinacloudapi.cn/<YOUR-TENANT-ID>/oauth2/token \
-d "grant_type=client_credentials&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%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.chinacloudapi.cn/",
    "access_token": "YOUR-ACCESS-TOKEN"
}

请记下该令牌，因为你以后需要用它来对所有管理请求进行身份验证。为此，可在所有请求中设置一个授权标头：

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

注意

该值以字符串“Bearer ”开头，其中包含一个空格，你需要在空格后面添加该令牌。

获取与订阅关联的资源组列表

若要检索与订阅关联的资源组列表，请运行：

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

整个 Azure 上发布了许多的 REST API。每家服务提供商会按照自己的步调更新其 API，但这样做不会破坏现有的程序。服务提供商使用 api-version 参数来确保兼容性。

重要

api-version 参数因服务而异。例如，对于机器学习服务，当前的 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": "chinaeast2",
            "properties": {
                "provisioningState": "Succeeded"
            }
        },
        {
            "id": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourceGroups/RG2",
            "name": "RG2",
            "type": "Microsoft.Resources/resourceGroups",
            "location": "chinaeast2",
            "properties": {
                "provisioningState": "Succeeded"
            }
        }
    ]
}

向下钻取到工作区及其资源

若要检索资源组中的工作区集，请运行以下命令，替换其中的 <YOUR-SUBSCRIPTION-ID>、<YOUR-RESOURCE-GROUP> 和 <YOUR-ACCESS-TOKEN>：

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

同样，你会收到一个 JSON 列表，这次，该 JSON 列表包含一个列表，其中的每个项详细提供了有关工作区的信息：

{
    "id": "/subscriptions/12345abc-abbc-1b2b-1234-57ab575a5a5a/resourceGroups/DeepLearningResourceGroup/providers/Microsoft.MachineLearningServices/workspaces/my-workspace",
    "name": "my-workspace",
    "type": "Microsoft.MachineLearningServices/workspaces",
    "location": "chinaeast2",
    "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://chinaeast2.experiments.ml.azure.cn/discovery"
    },
    "identity": {
        "type": "SystemAssigned",
        "principalId": "abcdef1-abab-1234-1234-abababab123456",
        "tenantId": "1fedcba-abab-1234-1234-abababab123456"
    },
    "sku": {
        "name": "Basic",
        "tier": "Basic"
    }
}

若要处理工作区中的资源，需从常规 management.chinacloudapi.cn 服务器切换到特定于工作区位置的 REST API 服务器。请记下上述 JSON 响应中 discoveryUrl 密钥的值。如果 GET 该 URL，会收到如下响应：

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

api 响应的值是服务器 URL，你可将其用于其他请求。例如，若要列出试验，请发送以下命令。请将 REGIONAL-API-SERVER 替换为 api 响应的值（例如 chinaeast2.api.ml.azure.cn）。还像往常一样替换 YOUR-SUBSCRIPTION-ID、YOUR-RESOURCE-GROUP、YOUR-WORKSPACE-NAME 和 YOUR-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 划分为多个操作组，每个操作组具有不同的路径。

区域	`Path`
Artifacts	https://learn.microsoft.com/rest/api/azureml
数据存储	/machine-learning/how-to-access-data
超参数优化	hyperdrive/v1.0/
模型	modelmanagement/v1.0/
运行历史记录	execution/v1.0/ and history/v1.0/

可以使用以下常规模式浏览 REST API：

URL 组成部分	示例
https://
REGIONAL-API-SERVER/	chinaeast2.api.ml.azure.cn/
operations-path/	history/v1.0/
subscriptions/YOUR-SUBSCRIPTION-ID/	subscriptions/abcde123-abab-abab-1234-0123456789abc/
resourceGroups/YOUR-RESOURCE-GROUP/	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.chinacloudapi.cn/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-ID、YOUR-RESOURCE-GROUP、YOUR-WORKSPACE-NAME 和 YOUR-ACCESS-TOKEN 之外，还需替换 YOUR-COMPUTE-NAME 以及 location、vmSize、vmPriority、scaleSettings、adminUserName 和 adminUserPassword 的值。以下命令可创建一个专用单节点 Standard_D1（基本 CPU 计算资源），该资源将在 30 分钟后纵向缩减：

curl -X PUT \
  'https://management.chinacloudapi.cn/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": "chinaeast2",
    "properties": {
        "computeType": "AmlCompute",
        "properties": {
            "vmSize": "Standard_D1",
            "vmPriority": "Dedicated",
            "scaleSettings": {
                "maxNodeCount": 1,
                "minNodeCount": 0,
                "nodeIdleTimeBeforeScaleDown": "PT30M"
            }
        }
    }
}'

注意

在 Windows 终端中，可能需要在发送 JSON 数据时对双引号符号进行转义。也就是说，诸如 "location" 之类的文本将变成 \"location\"。

成功的请求将获取 201 Created 响应，但请注意，此响应仅表示预配过程已开始。需要通过轮询（或使用门户）来确认它是否成功完成。

使用 REST 创建工作区

每个 Azure 机器学习工作区都依赖于四个其他 Azure 资源：Azure 容器注册表资源、Azure Key Vault、Azure Application Insights 和 Azure 存储帐户。只有存在这些资源，才能创建工作区。有关创建每个此类资源的详细信息，请查阅 REST API 参考。

若要创建工作区，请在 management.chinacloudapi.cn 中放置 (PUT) 如下所示的调用。尽管此调用要求设置大量的变量，但在结构上，它与本文所述的其他调用相同。

curl -X PUT \
  'https://management.chinacloudapi.cn/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。你可以使用 GET 请求获取此 URI 以获得有关部署信息，包括在某个依赖资源出现问题时（例如，忘记在容器注册表中启用管理员访问权限）提供的有用调试信息。

使用用户分配的托管标识创建工作区

创建工作区时，可以指定用户分配的托管标识，该标识将用于访问关联的资源：ACR、KeyVault、存储和 App Insights。若要使用用户分配的托管标识创建工作区，请使用以下请求正文。

curl -X PUT \
  'https://management.chinacloudapi.cn/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>"
    }
}'

使用客户托管的加密密钥创建工作区

默认情况下，工作区的元数据存储在 Azure 维护的 Azure Cosmos DB 实例中。该数据是使用 Azure 管理的密钥加密的。也可以提供自己的密钥，而不使用 Azure 管理的密钥。这样做会在 Azure 订阅中创建另一组资源来存储数据。

若要创建使用你的密钥进行加密的工作区，需要满足以下先决条件：

Azure 机器学习服务主体必须拥有对 Azure 订阅的参与者访问权限。
你必须具有包含加密密钥的现有 Azure Key Vault。
Azure Key Vault 必须存在于你要在其中创建 Azure 机器学习工作区的同一 Azure 区域。
Azure Key Vault 必须启用软删除和清除保护，以防止意外删除时丢失数据。
Azure Key Vault 中必须具有访问策略，该策略授予对 Azure Cosmos DB 应用程序的“获取”、“包装”和“解包”访问权限。

若要创建使用用户分配的托管标识和客户管理的密钥进行加密的工作区，请使用以下请求正文。对工作区使用用户分配的托管标识时，还应将 userAssignedIdentity 属性设置为托管标识的资源 ID。

curl -X PUT \
  'https://management.chinacloudapi.cn/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": "chinaeast2euap",
    "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.cn/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 机器学习工作区或工作区使用的资源时，可能会收到类似于以下消息的错误：

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

大多数资源提供程序会自动注册，但并非全部。如果收到此消息，则需要注册所提到的提供程序。

下表包含 Azure 机器学习所需的资源提供程序的列表：

资源提供程序	为什么需要它
Microsoft.MachineLearningServices	创建 Azure 机器学习工作区。
Microsoft.Storage	Azure 存储帐户用作该工作区的默认存储。
Microsoft.ContainerRegistry	Azure 容器注册表被工作区用来生成 Docker 映像。
Microsoft.KeyVault	该工作区使用 Azure Key Vault 来存储机密。
Microsoft.Notebooks	Azure 机器学习计算实例上集成的笔记本。
Microsoft.ContainerService	如果计划将训练后的模型部署到 Azure Kubernetes 服务。

如果计划将客户管理的密钥与 Azure 机器学习一起使用，则必须注册以下服务提供程序：

资源提供程序	为什么需要它
Microsoft.DocumentDB	用于记录工作区元数据的 Azure CosmosDB 实例。
Microsoft.Search	Azure 搜索为工作区提供索引编制功能。

如果打算将托管虚拟网络与 Azure 机器学习配合使用，必须注册 Microsoft.Network 资源提供程序。为托管虚拟网络创建专用终结点时，工作区会使用此资源提供程序。

有关注册资源提供程序的信息，请参阅解决资源提供程序注册错误。

移动工作区

警告

不支持将 Azure 机器学习工作区移动到另一个订阅，或将拥有的订阅移到新租户。这样做可能会导致错误。

删除 Azure 容器注册表

Azure 机器学习工作区使用 Azure 容器注册表 (ACR) 执行某些操作。首次需要 ACR 实例时，它会自动创建一个。

警告

为工作区创建 Azure 容器注册表后，请不要删除它。删除 Azure 容器注册表会破坏 Azure 机器学习工作区。

后续步骤

浏览完整的 Azure 机器学习 REST API 参考。
使用 Jupyter 笔记本探索 Azure 机器学习。

Compartir a través de