NetScaler SDX

REST Web Services

May 9, 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.

Sie müssen den Benutzernamen und das Kennwort im Anmeldeobjekt angeben. 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
  
  pre codeblock 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. Sie müssen sicherstellen, 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
  
  pre codeblock { "login": { "username":"nsroot", "password":"verysecret" } } 
Nutzlast der Antwort
- Header
  
  pre codeblock HTTP/1.0 201 Created Set-Cookie: NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2

Hinweis: Sie müssen die Sitzungs-ID bei allen weiteren NITRO-Vorgängen 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 im Anmeldeobjekt einen neuen Timeout-Zeitraum (in Sekunden) angeben. Um beispielsweise den Timeout-Zeitraum auf 60 Minuten zu ändern, lautet die Anforderungsnutzlast:

``` pre codeblock { “login”: { “username”:”nsroot”, “password”:”verysecret”, “timeout”:3600 } }

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. Um beispielsweise eine Verbindung zu einer Appliance herzustellen, während Sie eine Citrix ADC-Instanz erstellen:

-  **URL**
-  **HTTP-Methode**
-  **Anfrage**
    -  **Header**

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

-  **Payload**

    ``` pre codeblock
    {
        "ns":
        {
            ...
        }
    }
    <!--NeedCopy--> ```

Antwort.
- Header
  
  pre codeblock HTTP/1.0 201 Created

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

URL
HTTP Methode DELETE
Anfrage
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.login+json

Konfigurations-APIs

Das NITRO-Protokoll kann verwendet werden, um 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 neue Ressource (z. B. eine Citrix ADC-Instanz) auf der SDX-Appliance zu erstellen, geben Sie den Ressourcennamen und andere verwandte Argumente in dem spezifischen Ressourcenobjekt an. Um beispielsweise eine Citrix ADC-Instanz mit dem Namen vpx1 zu erstellen:

URL
HTTP-Methode
Anfrage
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json 
- Payload
  
  pre codeblock { "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" } ] } }

Ressourcendetails und Statistiken abrufen

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 auf der Grundlage eines Filters 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 einer großen Anzahl von 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.

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

Sie geben die Seitenzahl mit dem Pagesize-Abfragezeichenfolgenparameter an und verwenden den Pageno-Abfragezeichenfolgenparameter, 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: Wenn Sie eine Vorstellung von der Anzahl der Ressourcen haben möchten, 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 Citrix ADC-Instanzen zu erhalten, lautet die URL http://<IP>/nitro/v2/config/<resource_type>?count=yes

So rufen Sie die Konfigurationsinformationen für die Citrix ADC-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 Citrix ADC-Instanz mit der ID 123456a in vpx2 zu ändern:

URL
HTTP-Methode
Nutzlast anfragen
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json 
- Payload
  
  pre codeblock { "ns": { "name":"vpx2", "id":"123456a" } }

Eine Ressource löschen

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

URL
HTTP-Methode
Anfrage
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json

Bulk-Vorgänge

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:

Ausgang. 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: Sie müssen das erforderliche Verhalten im Request-Header mithilfe des Parameters X-NITRO-ONERROR konfigurieren.

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

URL.
HTTP-Methode.
Nutzlast anfordern.
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue 
- Payload
  
  pre codeblock { "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" } ] }

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

URL.
HTTP-Methode. POST
Nutzlast anfordern.
- Header
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue 
- Payload
  
  pre codeblock { "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" } ] }

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 Web Services

May 9, 2023

Beitrag von:

May 9, 2023

Beitrag von: