NetScaler SDX

REST-Webdienste

November 23, 2023

Beitrag von:

REST (Representational State Transfer) ist ein Architekturstil, der auf einfachen HTTP-Anfragen 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 Reihe von Entitäten modelliert, wobei jede Entität durch eine eindeutige URL identifiziert wird.

Jede Ressource hat auch 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 liefert den Status für die zu erstellende Ressource. 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 zum Erstellen von Anforderungen verwendete HTTP-Methode ist POST.
Lesen. Clients können den Status einer Ressource abrufen, indem sie ihre URL mit der Methode HTTP GET angeben. Die Antwortnachricht enthält den Ressourcenstatus, ausgedrückt im JSON-Format.
Aktualisieren. Sie können den Status einer vorhandenen Ressource aktualisieren, indem Sie mithilfe der PUT-HTTP-Methode die URL angeben, die dieses Objekt und seinen neuen Status identifiziert, in JSON oder XML.
Löschen. Sie können eine auf der Serverseite vorhandene Ressource löschen, indem Sie die DELETE HTTP-Methode und die URL verwenden, die die zu entfernende Ressource identifiziert.

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

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

System-APIs

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

Geben Sie den Benutzernamen und das Kennwort im Anmeldeobjekt an. Die erstellte Sitzungskennung 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 durchführen können, sind durch die Ihrem Konto zugewiesene Administratorrolle begrenzt.

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
 
```
  Hinweis: Inhaltstypen wie “application/x-www-form-urlencoded”, die in früheren Versionen von NITRO unterstützt wurden, können ebenfalls verwendet werden. Stellen Sie sicher, dass die Nutzlast mit der in früheren Versionen verwendeten identisch ist. Die in dieser Dokumentation bereitgestellten Nutzdaten sind nur anwendbar, wenn der Inhaltstyp die Form “application/vnd.com.citrix.sdx.login+json” hat.
- Payload
```
 {
     "login":
     {
         "username":"nsroot",
         "password":"verysecret"
     }
 }
 
```

Nutzlast der Antwort

Header

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

Hinweis: Verwenden Sie die Sitzungs-ID bei allen weiteren NITRO-Vorgängen auf der Appliance.

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

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

Sie können auch eine Verbindung zur Appliance herstellen, um einen einzelnen Vorgang durchzuführen, indem Sie den Benutzernamen und das Kennwort im Anforderungsheader des Vorgangs angeben. So stellen Sie beispielsweise eine Verbindung zu einer Appliance her, während Sie eine NetScaler-Instanz erstellen:

URL
HTTP-Methode

Anfrage

Header

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

Payload

 {
     "ns":
     {
         ...
     }
 }
 <!--NeedCopy-->

Antwort.
- Header
```
 HTTP/1.0 201 Created
 
```

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

URL
HTTP Methode DELETE

Anfrage

Header

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

Konfigurations-APIs

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

Jeder SDX-Ressource ist je nach 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 Ressource (z. B. eine NetScaler-Instanz) auf der SDX-Appliance zu erstellen, geben Sie den Ressourcennamen und andere verwandte Argumente in dem spezifischen Ressourcenobjekt an. Um beispielsweise eine NetScaler-Instanz mit dem Namen vpx1 zu erstellen:

URL
HTTP-Methode

Anfrage

Header

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

Payload

 {
     "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-->

Abrufen von Ressourcendetails und Statistiken

SDX-Ressourcendetails können wie folgt abgerufen werden:

Um Details einer bestimmten Ressource auf der SDX-Appliance abzurufen, geben Sie die ID der Ressource in der URL an.
Um die Eigenschaften von Ressourcen basierend auf einem Filter abzurufen, geben Sie die Filterbedingungen in der URL an.

Die URL hat das Formular: http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
Wenn Ihre Anfrage wahrscheinlich zu vielen Ressourcen führt, die von der Appliance zurückgegeben werden, können Sie diese Ergebnisse in Chunks abrufen, indem Sie sie in “Seiten” aufteilen und sie Seite für Seite abrufen.

Nehmen wir beispielsweise an, dass Sie alle NetScaler-Instanzen auf einem SDX abrufen möchten, das 53 davon hat. Anstatt alle 53 in einer großen Antwort abzurufen, konfigurieren Sie die Ergebnisse so, dass sie in Seiten mit jeweils 10 NetScaler-Instanzen aufgeteilt werden (insgesamt 6 Seiten). Rufen Sie sie dann Seite für Seite vom Server ab.

Sie geben die Seitenzahl mit dem Abfragezeichenfolgenparameter für das Seitenformat an und verwenden den Abfragezeichenfolgenparameter für die Seitenzahl, um die Seitenzahl anzugeben, die Sie abrufen möchten. Die URL hat das Formular: http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

Sie müssen nicht alle Seiten abrufen oder die Seiten der Reihe nach abrufen. Jede Anfrage ist unabhängig, und Sie können sogar die Seitengrößeneinstellung zwischen Anforderungen ändern.

Hinweis: Um eine Vorstellung von der Anzahl der Ressourcen zu erhalten, die wahrscheinlich von einer Anforderung zurückgegeben werden, können Sie den Abfragezeichenfolgenparameter “count” verwenden, um eine Anzahl der zurückzugebenden Ressourcen anstelle der Ressourcen selbst anzufordern. Um die Anzahl der verfügbaren NetScaler-Instances zu ermitteln, wäre die URL http://<IP>/nitro/v2/config/<resource_type>?count=yes

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

URL
HTTP-Methode GET

Aktualisieren einer Ressource

Um eine vorhandene SDX-Ressource zu aktualisieren, verwenden Sie die PUT-HTTP-Methode. Geben Sie in der Nutzlast der HTTP-Anforderung den Namen und die anderen Argumente an, die geändert werden müssen. Um beispielsweise den Namen der NetScaler-Instanz mit der ID 123456a in vpx2 zu ändern:

URL
HTTP-Methode

Nutzlast anfragen

Header

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

Payload

 {
     "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. Um beispielsweise eine NetScaler-Instanz mit der ID 123456a zu löschen:

URL
HTTP-Methode

Anfrage

Header

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

Bulk-Operationen

Sie können mehrere Ressourcen gleichzeitig abfragen oder ändern und so den Netzwerkverkehr minimieren. Sie können beispielsweise mehrere NetScaler SDX-Appliances in derselben Operation hinzufügen. Sie können auch Ressourcen verschiedener Typen in einer Anforderung hinzufügen.

Um den Ausfall einiger Vorgänge innerhalb des Bulk-Vorgangs 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.
Fahren Sie fort. Alle Befehle in der Liste werden ausgeführt, auch wenn einige Befehle fehlschlagen.

Hinweis: Konfigurieren Sie das erforderliche Verhalten im Request-Header mithilfe des Parameters X-NITRO-ONERROR.

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

URL.
HTTP-Methode.

Nutzlast anfordern.

Header

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

Payload

 {
     "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-->

Um mehrere Ressourcen (NetScaler und zwei MPS-Benutzer) in einem Vorgang hinzuzufügen und fortzufahren, falls ein Befehl fehlschlägt:

URL.
HTTP-Methode. POST

Nutzlast anfordern.

Header

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

Payload

 {
     "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-->

Behandlung von Ausnahmen

Das Feld errorcode zeigt den Status des Vorgangs an.

Ein Fehlercode von 0 zeigt an, dass der Vorgang erfolgreich war.
Ein Fehlercode ungleich Null weist auf einen Fehler bei der Verarbeitung der NITRO-Anforderung hin.

Das Feld für die Fehlermeldung enthält eine kurze Erklärung und die Art des Fehlers.

Die offizielle Version dieses Inhalts ist auf Englisch. Für den einfachen Einstieg wird Teil des Inhalts der Cloud Software Group Dokumentation maschinell übersetzt. Cloud Software Group hat keine Kontrolle über maschinell übersetzte Inhalte, die Fehler, Ungenauigkeiten oder eine ungeeignete Sprache enthalten können. Es wird keine Garantie, weder ausdrücklich noch stillschweigend, für die Genauigkeit, Zuverlässigkeit, Eignung oder Richtigkeit von Übersetzungen aus dem englischen Original in eine andere Sprache oder für die Konformität Ihres Cloud Software Group Produkts oder Ihres Diensts mit maschinell übersetzten Inhalten gegeben, und jegliche Garantie, die im Rahmen der anwendbaren Endbenutzer-Lizenzvereinbarung oder der Vertragsbedingungen oder einer anderen Vereinbarung mit Cloud Software Group gegeben wird, dass das Produkt oder den Dienst mit der Dokumentation übereinstimmt, gilt nicht in dem Umfang, in dem diese Dokumentation maschinell übersetzt wurde. Cloud Software Group kann nicht für Schäden oder Probleme verantwortlich gemacht werden, die durch die Verwendung maschinell übersetzter Inhalte entstehen können.

REST-Webdienste

November 23, 2023

Beitrag von:

November 23, 2023

Beitrag von: