Befehl über die API ausführen

Zuletzt aktualisiert am 30. März 2026

Sobald alles eingerichtet ist, können Sie die Run Command-Funktion nutzen.

Diese Seite enthält Informationen zu folgenden Themen:

Wie Sie einen Befehl remote auf Ihrem Server ausführen
Wie Sie Skripte mit Argumenten in Ihrer API-Anfrage verwenden
Welche Limits für den Skriptinhalt gelten
Welche Arten von Skripten auf Linux ausgeführt werden können
Wie Sie Ihre eigenen benutzerdefinierten Skripte in Ihren Server einschleusen, wodurch Sie die volle Kontrolle über den Server haben, ohne angemeldet sein zu müssen

Voraussetzungen

Swagger-API-Definition für die STACKIT Run Commands Service-API.
Sie haben den Server Agent installiert.
Der Run Command-Dienst wurde aktiviert.
Informationen über verfügbare Befehlsvorlagen: Befehlsvorlagen über die API abrufen.

Verwendung von Run Command

Nachdem Sie Ihren Befehl aus den Befehlsvorlagen (Command Templates) ausgewählt haben, senden Sie diesen Befehl über eine POST-Anfrage an die API. Sie müssen in Ihren API-Anfragen die folgenden Informationen angeben:

projectId
serverId
commandTemplateName
parameters (wenn Sie Argumente verwenden möchten)

In den folgenden Beispielen führen wir verschiedene Run Commands mit und ohne Argumente aus.

Run Command ohne Argumente

Dieser Befehl zeigt die aktuelle Speicherauslastung auf Ihrem Server an (CommandTemplate: ShowMemoryUsage):

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
 "commandTemplateName": "ShowMemoryUsage"
}

Swagger-API-Definition für die STACKIT Run Commands Service-API: PostCommand

Run Command mit (einer Liste von) Argumenten

Dieser Befehl setzt das Passwort zurück oder erstellt einen Benutzer auf Ihrem Server (CommandTemplate: „ResetPassword“). Der Benutzername und das Passwort werden als Argumente übergeben. Beachten Sie, dass das Passwort im Klartext eingegeben werden muss.

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "ResetPassword",
  "parameters": {
    "username": "testuser",
    "password": "p4s5w0rd"
  }
}

Swagger-API-Definition für die STACKIT Run Commands Service-API: PostCommand.

Dieser Befehl startet eine Liste von Diensten („BITS“ und „BallonService“) auf Ihrem Server neu (CommandTemplate: „ManageServices“).
In diesem Beispiel können Sie auch andere Aktionsparameter verwenden, um Ihre Dienste zu verwalten, wie z. B. start, stop, suspend, enable, disable, remove etc.
Die verfügbaren Parameter für jede Befehlsvorlage können zwischen Windows und Linux variieren. Detaillierte Informationen finden Sie in der Liste der Befehlsvorlagen.

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "ManageServices",
  "parameters": {
    "action": "restart",
    "services": "BITS,BalloonService"
  }
}

Swagger-API-Definition für die STACKIT Run Commands Service-API: PostCommand.

Nach dem Senden des Befehls

Sobald Sie die API-Anfrage gesendet haben, wird der Befehl so schnell wie möglich vom STACKIT Server Agent auf Ihrem Server ausgeführt und die API gibt die Befehls-ID („id“) dieses in der Warteschlange befindlichen Jobs aus. Notieren Sie sich diese Befehls-ID, da Sie diese später benötigen, um auf den entsprechenden Run Command zu verweisen, z. B. wenn Sie dessen Status auswerten möchten.

Beispielantwort der POST-Anfrage für den Run Command ResetPassword mit dem Wert der Befehls-ID:

{
  "id": 775
}

Wie Sie den Status Ihres letzten Run Commands überprüfen und die Ergebnisse auswerten können, wird hier beschrieben: Befehlsergebnisse über die API prüfen.

Eigenes Skript über Run Command ausführen

Sie können Ihre eigenen benutzerdefinierten Skripte ausführen. Gehen Sie dazu wie folgt vor:

Verwenden Sie den commandTemplateName RunShellScript (Linux) oder RunPowerShellScript (Windows).
Konvertieren Sie das Skript in einen String, d. h. wandeln Sie es in einen JSON-String um.
Geben Sie in Ihren API-Anfragen die folgenden Informationen an:
- projectId
- serverId
- commandTemplateName „RunShellScript“ oder „RunPowerShellScript“
- parameters "script" (Ihr als String formatierter Skriptinhalt)
- parameters "argument" (wenn Sie Argumente verwenden möchten)

Die maximal zulässige Eingabegröße Ihres Skriptinhalts beträgt 10.000 Zeichen.

Linux (Skript in String konvertieren)

Sie können das Verarbeitungstool jq verwenden, das in den meisten Distributionen verfügbar ist. Die folgende Methode konvertiert den Inhalt einer bereitgestellten Skriptdatei ihr_skript in einen String und speichert die Ausgabe in der Datei ihr_skript_stringified.

Speichern Sie das untenstehende Skript als stringify_skript.sh und machen Sie es ausführbar:

#!/bin/bash

### Prüfen, ob ein Dateiname als Argument angegeben wurde
if [ $# -eq 0 ]; then
  echo "Verwendung: $0 <skript_dateiname>"
  exit 1
fi

### Prüfen, ob die Datei existiert
if [ ! -f "$1" ]; then
  echo "Datei nicht gefunden: $1"
  exit 1
fi

### Inhalt der Datei lesen und Sonderzeichen maskieren
script_contents=$(cat "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/`/\`/g')

### Skriptinhalt in doppelte Anführungszeichen setzen
script_string="\"$script_contents\""

echo $script_string

chmod +x stringify_skript.sh

Sie können Ihr Skript nun mit dem folgenden Befehl ausführen:

./stringify_skript.sh ihre_skript_datei > ihre_skript_datei_stringified

Ersetzen Sie ihre_skript_datei durch den Dateinamen des Skripts, das Sie in einen String konvertieren möchten. Dieses Konvertierungsskript gibt die String-Version Ihres Skripts in die Datei ihre_skript_datei_stringified aus.

Windows (Skript mit PowerShell in String konvertieren)

Öffnen Sie eine PowerShell ISE-Sitzung und fügen Sie das folgende Skript ein:

$InputContent = "C:\temp\input_content.txt"
$OutputContent = "C:\temp\output_content.txt"
$GetInput = Get-Content -Path $InputContent | Out-String
$ScriptJSON = $GetInput | ConvertTo-Json -Compress
$ScriptJSON | Out-File -FilePath $OutputContent

Erstellen Sie eine neue .txt-Datei mit dem Namen input_content.txt, die Sie z. B. in C:\temp ablegen können.
Fügen Sie den Inhalt, den Sie konvertieren möchten, in die Datei input_content.txt ein und speichern Sie diese.
Führen Sie das Skript aus.

Ähnlich wie beim oben beschriebenen Ansatz konvertiert dies den Inhalt der Datei input_content.txt in ein JSON-Array, komprimiert es und schreibt das Ergebnis in die Datei output_content.txt.

Verwendung von Online-Tools

Es gibt Online-Tools, die jede Eingabe in einen String konvertieren können.

Beispiele für benutzerdefinierte Skripte

Benutzerdefiniertes, als String formatiertes PowerShell-Skript mit Argumenten für einen Windows-Server:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunPowerShellScript",
  "parameters": {
    "script": "#ps1\nWrite-Host $Args[0] -NoNewline\nWrite-Host \",\"-NoNewline\nWrite-Host $Args[1]",
    "arguments": "Hello World"
  }
}

Benutzerdefiniertes, als String formatiertes Shell-Skript mit Argumenten für einen Linux-Server:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "echo \"Dies ist mein benutzerdefiniertes Skript mit den Argumenten $1 und $2\"",
    "arguments": "Hello World"
  }
}

Arten von Shell-Skripten, die auf Linux ausgeführt werden können

Für Linux gibt es verschiedene Möglichkeiten, ein Shell-Skript auszuführen, je nachdem, ob ein Argument und/oder ein Shebang-Header vorhanden ist.

Skript mit Shebang-Header und mit Argumenten wird als Bash-Skript ausgeführt

Beispielskript:

#!/bin/bash
### Eine einfache Nachricht mit Argumenten anzeigen
echo "Hallo, $1! Dies ist ein einfaches Bash-Skript, in dem $2 Argumente verwendet werden."

Anfrage-Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "#!/bin/bash\n# Eine einfache Nachricht mit Argumenten anzeigen\necho \"Hallo, $1! Dies ist ein einfaches Bash-Skript, in dem $2 Argumente verwendet werden.\"",
    "arguments": "Testuser,two"
  }
}

Antwort der Befehls-ID (Befehlsergebnisse über die API prüfen):

{
  "id": 828,
  "startedAt": "2024-02-15T15:20:22Z",
  "finishedAt": "2024-02-15T15:20:35Z",
  "output": "Hallo, Testuser! Dies ist ein einfaches Bash-Skript, in dem two Argumente verwendet werden.\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "#!/bin/bash\n# Eine einfache Nachricht mit Argumenten anzeigen\necho \"Hallo, $1! Dies ist ein einfaches Bash-Skript, in dem $2 Argumente verwendet werden.\""
}

Skript mit Shebang-Header und ohne Argumente wird mit dem Pfad des angegebenen Shebang-Interpreters ausgeführt

Bitte stellen Sie sicher, dass der Pfad zum Interpreter im Shebang korrekt ist, wenn Sie das Skript über Run Command ausführen. Um beispielsweise ein Python-Skript wie im folgenden Beispiel auszuführen, muss Python ordnungsgemäß auf dem Server installiert sein, bevor Sie das Skript ausführen.

Beispielskript:

#!/bin/python3
### Eine einfache Nachricht anzeigen
print("Hallo Welt! Dies ist ein einfaches Python-Skript, das ohne Argumente ausgeführt wird.")

Anfrage-Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "#!/bin/python3\n# Eine einfache Nachricht anzeigen\nprint(\"Hallo Welt! Dies ist ein einfaches Python-Skript, das ohne Argumente ausgeführt wird.\")"
  }
}

Antwort der Befehls-ID (Befehlsergebnisse über die API prüfen):

{
  "id": 829,
  "startedAt": "2024-02-16T09:18:31Z",
  "finishedAt": "2024-02-16T09:18:50Z",
  "output": "Hallo Welt! Dies ist ein einfaches Python-Skript, das ohne Argumente ausgeführt wird.\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "#!/bin/python3\n# Eine einfache Nachricht anzeigen\nprint(\"Hallo Welt! Dies ist ein einfaches Python-Skript, das ohne Argumente ausgeführt wird.\")"
}

Skript ohne Shebang (und mit oder ohne Argumente) wird als Bash-Skript ausgeführt

Beispielskript:

echo "Hallo Welt, dieses Skript wird als Bash-Skript ausgeführt."

Anfrage-Body:

POST https://run-command.api.eu01.stackit.cloud/v1/projects/{{projectId}}/servers/{{serverId}}/commands

{
  "commandTemplateName": "RunShellScript",
  "parameters": {
    "script": "echo \"Hallo Welt, dieses Skript wird als Bash-Skript ausgeführt.\""
  }
}

Antwort der Befehls-ID (Befehlsergebnisse über die API prüfen):

{
  "id": 830,
  "startedAt": "2024-02-15T15:29:35Z",
  "finishedAt": "2024-02-15T15:49:53Z",
  "output": "Hallo Welt, dieses Skript wird als Bash-Skript ausgeführt.\n",
  "exitCode": 0,
  "status": "completed",
  "commandTemplateId": "RunShellScript",
  "commandTemplateTitle": "Run Shell Script",
  "script": "echo \"Hallo Welt, dieses Skript wird als Bash-Skript ausgeführt.\""
}