Ausführen von REST-Befehlen

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.

Verwenden einer Web-Browser-Erweiterung zur Überwachung der JSON-Zeichenfolgen, die der Server benutzt

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.

Feedback