在已启用 Azure Arc 的服务器上运行命令的 REST API 请求（预览版）

2025-05-22

在已启用 Azure Arc 的服务器上使用 REST API for Run 命令（预览版），可以在已启用 Arc 的虚拟机上远程安全地执行脚本或命令，而无需通过远程桌面协议或 SSH 直接连接到它们。

本文提供了支持的 REST API作和示例方案，可帮助你了解如何使用 REST API。

先决条件

已启用 Arc 的服务器上的 Connected Machine 代理版本必须为 1.33 或更高版本。
需要使用访问令牌才能使用 REST API。请参阅 REST 入门。

支持的 REST API 操作

可以使用以下 REST API 来在已启用 Azure Arc 的服务器上执行运行命令。

操作	DESCRIPTION
创建或更新	创建或更新运行命令的操作。运行 Run 命令。
删除	删除运行命令的操作。如果它正在运行，则删除操作也会停止该运行命令。
获取	用于获取某个运行命令的操作。
列表	用于获取已启用 Azure Arc 的服务器的所有运行命令的操作。
更新	用于更新运行命令的操作。中止上一个运行命令。

注释

每次执行运行命令脚本时，输出和错误 blob 都会被覆盖。

REST API 方案示例

以下请求将引导你完成使用“运行”命令远程配置允许访问终结点 www.microsoft.com/pkiops/certs的防火墙规则。示例方案使用每个可用的 REST操作。

代码示例使用以下信息：

订阅 ID - aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
已启用 Arc 的服务器名称 - 2012DatacenterServer1
资源组 - ContosoRG
服务器的作系统 - Windows Server 2012/R2 服务器

步骤 1：通过运行指令创建终结点访问权限

首先创建一个运行命令脚本，这样就能使用 PUT 操作对已启用 Arc 的目标服务器上的 www.microsoft.com/pkiops/certs 终结点进行访问。

可以直接提供脚本或者链接到脚本文件。

若要以行形式提供脚本，请执行以下命令：

PUT https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

{
  "location": "chinaeast2",
  "properties": {
    "source": {
      "script": "New-NetFirewallRule -DisplayName $ruleName -Direction Outbound -Action Allow -RemoteAddress $endpoint -RemotePort $port -Protocol $protocol"
    },
    "parameters": [
      {
        "name": "ruleName",
        "value": "Allow access to www.microsoft.com/pkiops/certs"
      },
      {
        "name": "endpoint",
        "value": "www.microsoft.com/pkiops/certs"
      },
      {
        "name": "port",
        "value": 433
      },
      {
        "name": "protocol",
        "value": "TCP"
      }

    ],
    "asyncExecution": false,
    "runAsUser": "contoso-user1",
    "runAsPassword": "Contoso123!"
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/mycontainer/MyScriptError.txt"
  }
}

链接到脚本文件:

注释

此示例假定你已准备好一个名为 newnetfirewallrule.ps1（包含内联脚本）的文件，并将该脚本上传到 Blob 存储。

PUT https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

{
  "location": "chinaeast2",
  "properties": {
    "source": {
      "scriptUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/myscriptoutputcontainer/newnetfirewallrule.ps1"
    },
    "parameters": [
      {
        "name": "ruleName",
        "value": " Allow access to www.microsoft.com/pkiops/certs"
      },
      {
        "name": "endpoint",
        "value": "www.microsoft.com/pkiops/certs"
      },
      {
        "name": "port",
        "value": 433
      },
      {
        "name": "protocol",
        "value": "TCP"
      }

    ],
    "asyncExecution": false,
    "runAsUser": "contoso-user1",
    "runAsPassword": "Contoso123!"
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/mycontainer/MyScriptError.txt"
  }
}

scriptUri这是存储 Blob 的共享访问签名（SAS）URI，它必须提供对 Blob 的读取访问权限。建议 SAS URI 的到期时间为 24 小时。可以使用 Blob 选项或 SAS 令牌 New-AzStorageBlobSASToken在 Azure 门户中生成 SAS URI。如果使用New-AzStorageBlobSASToken生成 SAS 令牌，则 SAS URI 格式为：base blob URL + "?" + 从New-AzStorageBlobSASToken获得的 SAS 令牌。
输出和错误 Blob 必须是 AppendBlob 类型，其 SAS URI 必须提供对 Blob 的读取、追加、创建和写入访问权限。 SAS URI 建议过期时间为 24 小时。可以在 Azure 门户中利用 Blob 的选项生成 SAS URI，或者使用 New-AzStorageBlobSASToken 获取 SAS 令牌。

若要了解有关共享访问签名的详细信息，请参阅使用共享访问签名（SAS）授予对 Azure 存储资源的有限访问权限。

步骤 2：验证运行命令详细信息

验证是否已正确使用 GET 操作配置了 Run 命令。

GET https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

步骤 3：更新运行命令

可以使用 PATCH 操作用新的参数更新现有的 Run 命令。以下示例开放对另一个终结点（即 *.waconazure.com,）的访问，该终结点用于连接到 Windows Admin Center。

PATCH https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

{
  "location": "chinaeast2",
  "properties": {
    "source": {
      "script": "New-NetFirewallRule -DisplayName $ruleName -Direction Outbound -Action Allow -RemoteAddress $endpoint -RemotePort $port -Protocol $protocol"
    },
    "parameters": [
      {
        "name": "ruleName",
        "value": "Allow access to WAC endpoint"
      },
      {
        "name": "endpoint",
        "value": "*.waconazure.com"
      },
      {
        "name": "port",
        "value": 433
      },
      {
        "name": "protocol",
        "value": "TCP"
      }
    ],
    "asyncExecution": false,
    "runAsUser": "contoso-user1",
    "runAsPassword": "Contoso123!",
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.chinacloudapi.cn/mycontainer/MyScriptError.txt"
  }
}

步骤 4：列出运行命令

在删除用于终结点访问的 Run 命令之前，请确保已启用 Arc 的服务器没有其他 Run 命令。你可以使用 LIST 操作在已启用 Arc 的服务器上获取所有运行命令。

LIST https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands?api-version=2024-11-10-preview

步骤 5：删除运行命令

不再需要 Run 命令扩展时，可以使用以下 DELETE 操作将其删除：

DELETE https://management.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

通过