Köra svarskommandon i livesändning på en enhet
Gäller för:
Viktigt
En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.
Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.
Anteckning
Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.
Tips
För bättre prestanda kan du använda servern närmare din geografiska plats:
- api-us.securitycenter.microsoft.com
- api-eu.securitycenter.microsoft.com
- api-uk.securitycenter.microsoft.com
API-beskrivning
Kör en sekvens av kommandon för livesvar på en enhet
Begränsningar
Prisbegränsningar för detta API är 10 samtal per minut (ytterligare förfrågningar besvaras med HTTP 429).
25 samtidiga sessioner (förfrågningar som överskrider begränsningsgränsen får svaret "429 – För många begäranden").
Om datorn inte är tillgänglig köas sessionen i upp till 3 dagar.
Tidsgränser för RunScript-kommandon efter 10 minuter.
Kommandon för livesvar kan inte läggas till i kö och kan endast köras ett i taget.
Om datorn som du försöker köra det här API-anropet till finns i en RBAC-enhetsgrupp som inte har en tilldelad automatiserad åtgärdsnivå, måste du minst aktivera den lägsta åtgärdsnivån för en viss enhetsgrupp.
Du kan köra flera kommandon med livesvar på ett API-anrop. Men när ett live-svarskommando misslyckas körs inte alla efterföljande åtgärder.
Minimikrav
Innan du kan starta en session på en enhet kontrollerar du att du uppfyller följande krav:
Kontrollera att du kör en version av Windows.
Enheter måste köra någon av följande versioner av Windows
Windows 11
Windows 10
- Version 1909 eller senare
- Version 1903 med KB4515384
- Version 1809 (RS 5) med KB4537818
- Version 1803 (RS 4) med KB4537795
- Version 1709 (RS 3) med KB4537816
Windows Server 2019 – endast tillämpligt för offentlig förhandsversion
Windows Server 2022
Behörigheter
En av följande behörigheter krävs för att anropa detta API. Mer information, inklusive hur du väljer behörigheter, finns i Komma igång.
| Behörighetstyp | Behörighet | Visningsnamn för behörighet |
|---|---|---|
| Program | Machine.LiveResponse | Köra livesvar på en viss dator |
| Delegerat (arbets- eller skolkonto) | Machine.LiveResponse | Köra livesvar på en viss dator |
HTTP-begäran
POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse
Frågerubriker
| Namn | Typ | Beskrivning |
|---|---|---|
| Auktorisering | Sträng | Bearer<token>. Obligatoriskt. |
| Content-Type | sträng | application/json. Obligatoriskt. |
Frågebrödtext
| Parameter | Typ | Beskrivning |
|---|---|---|
| Kommentar | Sträng | Kommentar som ska associeras med åtgärden. |
| Kommandon | Matris | Kommandon som ska köras. Tillåtna värden är PutFile, RunScript och GetFile. |
Kommandon
| Kommandotyp | Parametrar | Beskrivning |
|---|---|---|
| PutFile | Nyckel: Filnamn Värde: <file name> |
Lägger till en fil från biblioteket till enheten. Filer sparas i en arbetsmapp och tas bort när enheten startas om som standard. |
| RunScript | Nyckel: ScriptName Värde: <Script from library> Tangent: Args |
Kör ett skript från biblioteket på en enhet. Parametern Args skickas till skriptet. Tidsgränser efter 10 minuter. |
| GetFile | Nyckel: Sökväg Värde: <File path> |
Samla in en fil från en enhet. Obs! Omslag i sökväg måste komma i väg. |
Svar
Om det lyckas returnerar den här metoden 201 Skapad.
Åtgärd entitet. Om ingen dator med det angivna ID:t hittades – 404 Hittades inte.
Exempel
Exempel på förfrågan
Här är ett exempel på begäran.
POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse
```JSON
{
"Commands":[
{
"type":"RunScript",
"params":[
{
"key":"ScriptName",
"value":"minidump.ps1"
},
{
"key":"Args",
"value":"OfficeClickToRun"
}
]
},
{
"type":"GetFile",
"params":[
{
"key":"Path",
"value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
],
"Comment":"Testing Live Response API"
}
Svarsexempel
Här är ett exempel på svaret.
HTTP/1.1 200 Ok
Innehållstyp: program/json
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
"id": "{machine_action_id}",
"type": "LiveResponse",
"requestor": "analyst@microsoft.com",
"requestorComment": "Testing Live Response API",
"status": "Pending",
"machineId": "{machine_id}",
"computerDnsName": "hostname",
"creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"errorHResult": 0,
"commands": [
{
"index": 0,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "RunScript",
"params": [
{
"key": "ScriptName",
"value": "minidump.ps1"
},{
"key": "Args",
"value": "OfficeClickToRun"
}
]
}
}, {
"index": 1,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "GetFile",
"params": [{
"key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
}
]
}