Citrix ADC SDX 13.0

REST-Webdienste

REST (Representational State Transfer) ist ein Architekturstil, der auf einfachen HTTP-Anforderungen und -Antworten zwischen dem Client und dem Server basiert. REST wird verwendet, um den Status von Objekten auf der Serverseite abzufragen oder zu ändern. In REST wird die Serverseite als eine Gruppe von Entitäten modelliert, bei der jede Entität durch eine eindeutige URL identifiziert wird.

Jede Ressource hat außerdem einen Status, in dem die folgenden Vorgänge ausgeführt werden können:

  • Erstellen. Clients können neue serverseitige Ressourcen auf einer “Container” -Ressource erstellen. Sie können sich Containerressourcen als Ordner und untergeordnete Ressourcen als Dateien oder Unterordner vorstellen. Der aufrufende Client stellt den Status für die zu erstellende Ressource bereit. Der Status kann in der Anforderung mithilfe des XML- oder JSON-Formats angegeben werden. Der Client kann auch die eindeutige URL angeben, die das neue Objekt identifiziert. Alternativ kann der Server eine eindeutige URL auswählen und zurückgeben, die das erstellte Objekt identifiziert. Die HTTP-Methode, die für Erstellungsanforderungen verwendet wird, ist POST.
  • Lies. Clients können den Status einer Ressource abrufen, indem sie ihre URL mit der HTTP-GET-Methode angeben. Die Antwortnachricht enthält den Ressourcenstatus, ausgedrückt im JSON-Format.
  • Aktualisieren. Sie können den Status einer vorhandenen Ressource aktualisieren, indem Sie die URL angeben, mit der dieses Objekt identifiziert wird, und seinen neuen Status in JSON oder XML mithilfe der PUT-HTTP-Methode.
  • Löschen. Sie können eine Ressource zerstören, die auf der Serverseite vorhanden ist, indem Sie die HTTP-Methode DELETE und die URL verwenden, die die zu entfernende Ressource identifiziert.

Zusätzlich zu diesen vier CRUD-Operationen (Erstellen, Lesen, Aktualisieren und Löschen) können Ressourcen andere Vorgänge oder Aktionen unterstützen. Diese Operationen verwenden die HTTP POST-Methode, wobei der Anforderungskörper in JSON den auszuführenden Vorgang und Parameter für diesen Vorgang angibt.

SDX NITRO APIs werden je nach Umfang und Zweck der APIs in System-APIs und Konfigurations-APIs kategorisiert.

System-APIs

Der erste Schritt zur Verwendung von NITRO besteht darin, eine Sitzung mit der SDX-Appliance einzurichten und anschließend die Sitzung mithilfe der Anmeldeinformationen des Administrators zu authentifizieren.

Sie müssen den Benutzernamen und das Kennwort im Anmeldeobjekt angeben. Die erstellte Session-ID muss im Anforderungsheader aller weiteren Vorgänge in der Sitzung angegeben werden.

Hinweis: Sie müssen über ein Benutzerkonto auf dieser Appliance verfügen. Die Konfigurationen, die Sie ausführen können, sind durch die Administratorrolle begrenzt, die Ihrem Konto zugewiesen ist.

So stellen Sie mithilfe des HTTPS-Protokolls eine Verbindung zu einer SDX-Appliance mit der IP-Adresse 10.102.31.16 her:

  • URL https://10.102.31.16/nitro/v2/config/login/
  • HTTP-Methode POST
  • Anfrage
    • Header

       Content-Type:application/vnd.com.citrix.sdx.login+json
       <!--NeedCopy-->
      

      Hinweis: Inhaltstypen wie ‘application/x -www-form-urlencoded’, die in früheren Versionen von NITRO unterstützt wurden, können ebenfalls verwendet werden. Sie müssen sicherstellen, dass die Nutzlast die gleiche ist wie in früheren Versionen verwendet. Die in dieser Dokumentation bereitgestellten Nutzlasten sind nur anwendbar, wenn der Inhaltstyp die Form ‘application/vnd .com.citrix.sdx.login + json’ hat.

    • Nutzlast

       {
           "login":
           {
               "username":"nsroot",
               "password":"verysecret"
           }
       }
       <!--NeedCopy-->
      
  • Antwort-Nutzlast
    • Kopfzeile

       HTTP/1.0 201 Created
       Set-Cookie:
       NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
       <!--NeedCopy-->
      

Hinweis: Sie müssen die Session-ID bei allen weiteren NITRO-Operationen auf der Appliance verwenden.

Hinweis: Standardmäßig läuft die Verbindung zur Appliance nach 30 Minuten Inaktivität ab. Sie können den Timeout-Zeitraum ändern, indem Sie einen neuen Timeout-Zeitraum (in Sekunden) im Anmeldeobjekt angeben. Wenn Sie beispielsweise den Zeitüberschreitungszeitraum auf 60 Minuten ändern möchten, lautet die Anforderungsnutzlast:

{
    "login":
    {
        "username":"nsroot",
        "password":"verysecret",
        "timeout":3600
    }
}
<!--NeedCopy-->

Sie können auch eine Verbindung mit der Appliance herstellen, um einen einzelnen Vorgang auszuführen, indem Sie den Benutzernamen und das Kennwort im Anforderungsheader des Vorgangs angeben. So stellen Sie beispielsweise beim Erstellen einer Citrix ADC-Instanz eine Verbindung zu einer Appliance her:

  • URL
  • HTTP-Methode
  • Anfrage
    • Kopfzeile

       X-NITRO-USER:nsroot
       X-NITRO-PASS:verysecret
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       <!--NeedCopy-->
      
    • Nutzlast

       {
           "ns":
           {
               ...
           }
       }
       <!--NeedCopy-->
      
  • Antwort.
    • Kopfzeile

       HTTP/1.0 201 Created
       <!--NeedCopy-->
      

Verwenden Sie die DELETE-Methode, um die Verbindung zur Appliance zu trennen:

  • URL
  • HTTP-Methode DELETE
  • Anfrage
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.login+json
       <!--NeedCopy-->
      

Konfigurations-APIs

Das NITRO-Protokoll kann verwendet werden, um Ressourcen der SDX-Appliance zu konfigurieren.

Jeder SDX-Ressource ist abhängig von der Art des auszuführenden Vorgangs eine eindeutige URL zugeordnet. URLs für Konfigurationsvorgänge haben das Format:http://<IP>/nitro/v2/config/<resource_type>

Erstellen einer Ressource

Um eine neue Ressource (z. B. eine Citrix ADC-Instanz) auf der SDX-Appliance zu erstellen, geben Sie den Ressourcennamen und andere zugehörige Argumente im jeweiligen Ressourcenobjekt an. So erstellen Sie beispielsweise eine Citrix ADC-Instanz namens vpx1:

  • URL
  • HTTP-Methode
  • Anfrage
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       <!--NeedCopy-->
      
    • Nutzlast

       {
           "ns":
           {
               "name":"vpx1",
               "ip_address":"192.168.100.2",
               "netmask":"255.255.255.0",
               "gateway":"192.168.100.1",
               "image_name":"nsvpx-9.3-45_nc.xva",
               "vm_memory_total":2048,
               "throughput":1000,
               "pps":1000000,
               "license":"Standard",
               "profile_name":"ns_nsroot_profile",
               "username":"admin",
               "password":"admin",
               "network_interfaces":
               [
                   {
                       "port_name":"10/1"
                   },
                   {
                       "port_name":"10/2"
                   }
               ]
           }
       }
       <!--NeedCopy-->
      

Ressourcendetails und -statistiken abrufen

SDX-Ressourcendetails können wie folgt abgerufen werden:

  • Um Details zu einer bestimmten Ressource auf der SDX-Appliance abzurufen, geben Sie die ID der Ressource in der URL an.

  • Um die Eigenschaften von Ressourcen auf der Grundlage eines Filters abzurufen, geben Sie die Filterbedingungen in der URL an.

    Die URL hat die Form:http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>

  • Wenn Ihre Anfrage wahrscheinlich zu einer großen Anzahl von Ressourcen führt, die von der Appliance zurückgegeben werden, können Sie diese Ergebnisse in Abschnitte abrufen, indem Sie sie in “Seiten” aufteilen und Seite für Seite abrufen.

    Angenommen, Sie möchten alle Citrix ADC-Instanzen auf einem SDX abrufen, das 53 davon hat. Anstatt alle 53 in einer großen Antwort abzurufen, können Sie die Ergebnisse so konfigurieren, dass sie in Seiten mit je 10 Citrix ADC-Instanzen (insgesamt 6 Seiten) aufgeteilt werden und sie Seite für Seite vom Server abrufen.

    Sie geben die Seitenanzahl mit dem Parameter pagesize Abfragezeichenfolge an und verwenden den Parameter pageno Abfragezeichenfolge, um die Seitenzahl anzugeben, die Sie abrufen möchten. Die URL hat die Form:http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

    Sie müssen nicht alle Seiten abrufen oder die Seiten in der Reihenfolge abrufen. Jede Anforderung ist unabhängig, und Sie können sogar die Einstellung pagesize zwischen Anforderungen ändern.

    Hinweis: Wenn Sie eine Vorstellung von der Anzahl der Ressourcen haben möchten, die wahrscheinlich von einer Anforderung zurückgegeben werden, können Sie den Parameter count Abfragezeichenfolge verwenden, um nach einer Anzahl der zurückzugebenden Ressourcen und nicht nach den Ressourcen selbst zu fragen. Um die Anzahl der verfügbaren Citrix ADC-Instanzen abzurufen, lautet die http://<IP>/nitro/v2/config/<resource_type>?count=yesURL

So rufen Sie die Konfigurationsinformationen für die Citrix ADC-Instanz mit der ID 123456a ab:

  • URL
  • HTTP-Methode GET

Ressource aktualisieren

Verwenden Sie die PUT-HTTP-Methode, um eine vorhandene SDX-Ressource zu aktualisieren. Geben Sie in der HTTP-Request-Payload den Namen und die anderen Argumente an, die geändert werden müssen. So ändern Sie beispielsweise den Namen der Citrix ADC-Instanz mit der ID 123456a in vpx2:

  • URL
  • HTTP-Methode
  • Nutzlast anfordern
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       <!--NeedCopy-->
      
    • Nutzlast

       {
           "ns":
           {
               "name":"vpx2",
               "id":"123456a"
           }
       }
       <!--NeedCopy-->
      

Löschen einer Ressource

Um eine vorhandene Ressource zu löschen, geben Sie in der URL den Namen der zu löschenden Ressource an. So löschen Sie beispielsweise eine Citrix ADC-Instanz mit der ID 123456a:

  • URL
  • HTTP-Methode
  • Anfrage
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       <!--NeedCopy-->
      

Massenvorgänge

Sie können mehrere Ressourcen gleichzeitig abfragen oder ändern und so den Netzwerkverkehr minimieren. Beispielsweise können Sie mehrere Citrix ADC SDX-Appliances in demselben Vorgang hinzufügen. Sie können auch Ressourcen verschiedener Typen in einer Anfrage hinzufügen.

Um den Fehler einiger Operationen innerhalb des Massenvorgangs zu berücksichtigen, können Sie mit NITRO eines der folgenden Verhaltensweisen konfigurieren:

  • Beenden. Wenn der erste Fehler auftritt, stoppt die Ausführung. Die Befehle, die vor dem Fehler ausgeführt wurden, werden festgeschrieben.
  • Weiter. Alle Befehle in der Liste werden ausgeführt, auch wenn einige Befehle fehlschlagen.

Hinweis: Sie müssen das erforderliche Verhalten im Request-Header mit dem Parameter X-NITRO-ONERROR konfigurieren.

So fügen Sie zwei Citrix ADC-Ressourcen in einem Vorgang hinzu und fahren Sie fort, wenn ein Befehl fehlschlägt:

  • URL.
  • HTTP-Methode.
  • Nutzlast anfordern.
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       X-NITRO-ONERROR:continue
       <!--NeedCopy-->
      
    • Nutzlast

       {
           "ns":
           [
               {
                   "name":"ns_instance1",
                   "ip_address":"10.70.136.5",
                   "netmask":"255.255.255.0",
                   "gateway":"10.70.136.1"
               },
               {
                   "name":"ns_instance2",
                   "ip_address":"10.70.136.8",
                   "netmask":"255.255.255.0",
                   "gateway":"10.70.136.1"
               }
           ]
       }
       <!--NeedCopy-->
      

So fügen Sie mehrere Ressourcen (Citrix ADC und zwei MPS-Benutzer) in einem Vorgang hinzu und fahren Sie fort, wenn ein Befehl fehlschlägt:

  • URL.
  • HTTP-Methode. POST
  • Nutzlast anfordern.
    • Kopfzeile

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       X-NITRO-ONERROR:continue
       <!--NeedCopy-->
      
    • Nutzlast

       {
           "ns":
           [
               {
                   "name":"ns_instance1",
                   "ip_address":"10.70.136.5",
                   "netmask":"255.255.255.0",
                   "gateway":"10.70.136.1"
               },
               {
                   "name":"ns_instance2",
                   "ip_address":"10.70.136.8",
                   "netmask":"255.255.255.0",
                   "gateway":"10.70.136.1"
               }
           ],
            "mpsuser":
           [
               {
                   "name":"admin",
                   "password":"admin",
                   "permission":"superuser"
               },
               {
                   "name":"admin",
                   "password":"admin",
                   "permission":"superuser"
               }
           ]
       }
       <!--NeedCopy-->
      

Ausnahmebehandlung

Das Fehlercode-Feld gibt den Status des Vorgangs an.

  • Ein Fehlercode von 0 gibt an, dass der Vorgang erfolgreich ist.
  • Ein Fehlercode ungleich Null zeigt einen Fehler bei der Verarbeitung der NITRO-Anforderung an.

Das Fehlermeldungsfeld bietet eine kurze Erklärung und die Art des Fehlers.

REST-Webdienste