Viele verschiedene Programme können REST-Befehle ausführen. Um den Befehl auszuführen, rufen Sie eine Methode auf einer REST-Ressource auf und übergeben Sie die Parameter oder eine Anforderung im JSON-Format.
Anmerkung: Die Verwendung von REST-Befehlen erfordert dieselben Berechtigungen wie für die Nutzung der Webschnittstelle. Informationen über Berechtigungen finden Sie unter
Rollen und Berechtigungen.
Beispiel: Ausführen einfacher REST-Befehle mit curl
Das Linux-Programm
curl ist eine einfache Methode zum Ausführen von REST-Befehlen. Um einen REST-Befehl auszuführen, setzen Sie die URL einer der REST-Ressourcen zusammen, geben Sie die zu verwendende Methode an und fügen Sie Parameter hinzu. Der folgende
curl-Befehl ruft eine Liste aller aktiven Komponenten ab. Der Befehl ruft die
GET-Methode der
component-Ressource auf und übergibt den Wert
true für den Parameter
active:
curl -k -u admin:admin
https://hostname:port/cli/component?active=true
-X GET
Anmerkung: Sie müssen diesen Befehl in einer Zeile eingeben. Hier ist er nur zur besseren Lesbarkeit auf mehrere Zeilen aufgeteilt.
Anmerkung: In diesem Beispiel wird die Option
-k verwendet, um eine unsichere Verbindung mit dem Server herzustellen. Hinweise zum Einrichten der Authentifizierung finden Sie unter
Authentifizierung für REST-Befehle.
Verwenden Sie den Hostnamen und den Port Ihres Servers für die Variablen
hostname und
port.
Beispiel: Wenn der Hostname
ucdeploy.example.org und der Port der Standardwert 8443 ist, kann der
curl-Befehl so aussehen:
curl -k -u admin:admin
https://ucdeploy.example.org:8443/cli/component?active=true
-X GET
Die Antwort für diesen Befehl ist eine JSONArray-Liste aller aktiven Komponenten auf dem Server. Ein Beispiel für diese Antwort sehen Sie in
Get information about all components on the server.
Übergeben von Parametern an REST-Befehle
Viele REST-Befehle haben einen oder mehr Parameter. Um diese Parameter zu übergeben, fügen Sie sie der URL hinzu. Beispiel: Die
GET-Methode des Befehls
version/getLink übernimmt drei Parameter: den Namen oder die ID der Anwendung, den Namen oder die ID der Version und den Namen des Links. Um einen Link für die
JPetStore-APP-Komponente zu erhalten, könnte der Befehl wie folgt aussehen:
curl -k -u admin:admin
"https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/
version/getLink?component=JPetStore-APP
&version=1.0
&linkName=IBM%20web%20site"
In diesem Fall, werden die einzelnen Paare aus Parameter und Wert nach einem Fragezeichen (
?) an die URL angehängt.
Ein Et-Zeichen (
&) trennt die Paare. Da
curl ein Linux-Befehl ist und das Et-Zeichen in der Linux-Befehlszeile eine besondere Bedeutung hat, wird die URL einschließlich der Parameter in Anführungszeichen gesetzt.
Anmerkung: Alle Parameterwerte müssen URL-codiert sein. Das vorherige Beispiel übergibt den Wert IBM web site als Wert für den linkName-Parameter.
Um diesen Parameter als Teil dieser URL einzugeben, müssen die Leerzeichen auf den URL-codierten Wert %20 geändert werden.
Übergeben von JSON-Zeichenfolgen an Befehle
Bei komplexeren Befehlen müssen Sie eine JSON-Zeichenfolge oder eine Datei anstelle der Parameter oder zusätzlich zu ihnen senden.
Beispiel: Die
PUT-Methode der Ressource
application/create erstellt eine Anwendung.
Um diesen Befehl zu verwenden, müssen Sie eine JSON-Zeichenfolge übergeben, die den Namen, die Beschreibung und einige Eigenschaften der neuen Anwendung enthält. Die JSON-Zeichenfolge für diesen Befehl muss diese Vorlage einhalten:
{
"description": "Beschreibung",
"enforceCompleteSnapshots": "'true' festlegen, um eine
explizite Version für jede Komponente anzufordern",
"name": "Anwendungsname oder -ID",
"notificationScheme": "Benachrichtigungsschema"
}
Diese Vorlage ist in den Referenzinformationen für den Befehl aufgelistet. Siehe
Create an application from a JSON file.
Beispiel: Die folgende JSON-Zeichenfolge repräsentiert eine Anwendung mit dem Namen
Meine Anwendung:
{
"description": "Meine neue Anwendung",
"enforceCompleteSnapshots": "false",
"name": "Meine Anwendung",
"notificationScheme": "Standard-Benachrichtigungsschema"
}
Um diese JSON-Zeichenfolge an die Ressource
application/create zu übergeben, können Sie entweder die Zeichenfolge in einer Datei speichern oder sie in einen Befehl einschließen.
Beispiel: Wenn Sie die Zeichenfolge in einer Datei mit dem Namen
newApplication.json speichern, sieht der Befehl wie folgt aus:
curl -k -u admin:admin
https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create
-X PUT -d @newApplication.json
Sie können die Zeichenfolge auch direkt an den Befehl übergeben, wie im folgenden Beispiel gezeigt wird:
curl -k -u admin:admin
https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create
-X PUT
-d {"description":"Meine neue Anwendung",
"enforceCompleteSnapshots":"false",
"name":"Meine Anwendung 67",
"notificationScheme":"Standard-Benachrichtigungsschema"}
Zusammenstellen von JSON-Zeichenfolgen
Es gibt zwei Hauptmethoden, die Vorlage der JSON-Zeichenfolge für einen Befehl zu erhalten. Die Vorlagen werden in den Referenzinformationen für jeden Befehl aufgelistet. Sie können auch den äquivalenten Befehlszeilenclient-Befehl mit der Option -t ausführen.
Wenn Sie den CLI-Befehl mit dieser Option ausführen, wird die JSON-Vorlage ausgedruckt.
Da die Serverschnittstelle die REST-API verwendet, können Sie sich auch wie üblich beim Server anmelden und die Anforderungen überwachen, die die Webanwendung generiert. Sie können diese Anforderungen mit Web-Browser-Erweiterungen oder externen Programmen überwachen. Um beispielsweise die JSON-Zeichenfolge für die PUT-Methode der Ressource resource/create anzusehen, erstellen Sie eine Ressource auf dem Webserver wie üblich und sehen sich dann die JSON-Zeichenfolge in der Browseranforderung an, wie in der nachstehenden Abbildung gezeigt. Die JSON-Zeichenfolge für den REST-Befehl gleicht dieser Zeichenfolge.
Antworten
Nach einem erfolgreichen Befehl geben die meisten Befehle entweder einen einfachen Zeichenfolgenwert oder eine JSON-Zeichenfolge zurück.
Zusätzlich zum Ergebnis des Befehls geben die Befehle auch Standard-HTTP-Statuscodes zurück. Die folgende Liste enthält die häufigsten Statuscodes, die von REST-Befehlen zurückgegeben werden.
- 200
- Der Befehl war erfolgreich.
- 400
- Sie sind nicht berechtigt diesen Befehl auszuführen.
- Sie haben einen erforderlichen Parameter nicht angegeben.
- Der Ressourcenpfad in der URL ist falsch.
- 404
- Das von Ihnen abgerufene Objekt ist nicht vorhanden.
- 405
- Der HTTP-Methodenname ist falsch.
- 415
- Der Inhaltstyp im Anforderungsheader ist falsch.
- 500
- Der Server hat einen Fehler gemeldet.