在已啟用 Azure Arc 的伺服器上執行命令的 REST API 要求（預覽）

2025-04-21

在已啟用 Azure Arc 的伺服器上使用 REST API for Run 命令（預覽），您可以在已啟用 Arc 的虛擬機上遠端安全地執行腳本或命令，而不需要透過遠端桌面通訊協定或 SSH 直接連線到它們。

本文提供支援的 REST API 作業和範例案例，可協助您瞭解如何使用 REST API。

先決條件

已啟用 Arc 之伺服器上的連線機器代理程式版本必須是 1.33 或更高版本。
您需要存取權杖才能使用 REST API。請參閱開始使用 REST。

支援的 REST API 作業

您可以使用下列 REST API 作業，在已啟用 Azure Arc 的伺服器上執行執行命令。

作業	說明
建立或更新	建立或更新執行命令的作業。執行運行命令。
刪除	刪除執行命令的作業。如果正在執行，刪除也會停止執行命令。
獲取	取得執行命令的作業。
清單	取得已啟用 Azure Arc 的伺服器所有執行命令的作業。
更新	更新執行命令的作業。停止先前的 [執行] 命令。

備註

每次執行 Run 命令腳本時，輸出和錯誤 Blob 資料都會被覆寫。

範例 REST API 案例

下列要求會逐步引導您使用 [執行] 命令從遠端設定允許存取端點 www.microsoft.com/pkiops/certs的防火牆規則。此範例案例會使用每個可用的 REST 作業。

程式代碼範例會使用下列資訊：

訂用帳戶標識碼 - aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
已啟用 Arc 的伺服器名稱 - 2012DatacenterServer1
資源群組 - ContosoRG
伺服器的作系統 - Windows Server 2012 / R2 伺服器

步驟 1：使用執行命令建立端點存取

使用 PUT 作業建立提供端點存取的執行命令指令碼，以提供已啟用 Arc 的目標伺服器上 www.microsoft.com/pkiops/certs 端點的存取權。

您可以提供內嵌指令碼，也可以連結至指令碼檔案。

若要提供內嵌指令碼：

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

{
  "location": "eastus2",
  "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.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt"
  }
}

若要連結至文稿檔案：

備註

此範例假設您已準備名為 newnetfirewallrule.ps1的檔案，其中包含內嵌腳本，並將腳本上傳至 Blob 記憶體。

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

{
  "location": "eastus2",
  "properties": {
    "source": {
      "scriptUri": "https://mystorageaccount.blob.core.windows.net/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.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt"
  }
}

scriptUri是記憶體 Blob 的共用存取簽章（SAS） URI，而且必須提供 Blob 的讀取許可權。 SAS URI 建議到期時間為24小時。您可以在 Azure 入口網站上使用 Blob 選項來產生 SAS URI，或使用 New-AzStorageBlobSASToken 來產生 SAS 令牌。如果使用 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 令牌。

若要深入瞭解共用存取簽章，請參閱使用共用存取簽章授與對 Azure 記憶體資源的有限存取權。

步驟 2：確認執行命令詳細數據

確認您已使用 GET 操作正確配置執行指令。

GET https://management.azure.com/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.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoRG/providers/Microsoft.HybridCompute/machines/2012DatacenterServer1/runCommands/EndpointAccessCommand?api-version=2024-11-10-preview

{
  "location": "eastus2",
  "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.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt"
  }
}

步驟 4：列出執行命令

刪除端點存取的執行命令之前，請確定已啟用 Arc 的伺服器沒有其他執行命令。您可以使用 LIST 作業來取得已開啟 Arc 之伺服器上的所有執行命令：

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

步驟 5：刪除執行命令

當您不再需要執行命令擴充功能時，您可以使用下列 DELETE 作業加以刪除：

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

共用方式為

在已啟用 Azure Arc 的伺服器上執行命令的 REST API 要求 （預覽）