NetWorker: REST API – Troubleshooting- und Selektierungshandbuch

Auf YouTube ansehen

Erste Schritte

Die REST (Application Programming Interface) Application Programming Interface (API) bietet programmatischen Zugriff auf den NetWorker-Data-Protection-Service. Mithilfe der REST API können NetWorker-Nutzer Clientanwendungen zur Automatisierung von NetWorker-Vorgängen erstellen. NetWorker REST API wird als Teil der NetWorker-Serverinstallation im selben Apache Tomcat-Container wie die NetWorker-Authentifizierungsservices installiert. Die Authentifizierung erfolgt mit denselben Zugangsdaten, die auch für die NetWorker Management Console verwendet werden.  

REST API ermöglicht die Interaktion mit Ressourcen, die durch URI-Adressen (Uniform Resource Identifier) identifiziert werden. Er verwendet HTTP-Verben (HEAD, GET, PUT, POST, DELETE), um zustandslos mit dem Uniform Resource Identifier (URI) zu interagieren. Der Server enthält keinen Clientstatus, jede Meldung ist selbstbeschreibend.

Dieses Dokument behandelt die Interaktion mit NetWorker-Ressourcen mithilfe von nutzergeschriebenen REST API-Aufrufen. Nicht zu verwechseln mit den REST API-Aufrufen, die von Back-end-NetWorker-Vorgängen verwendet werden.
 

Herstellen einer Verbindung zu NetWorker:

Es gibt verschiedene REST-API-Clienttechnologien, die zum Ausführen der Befehle für die Verbindung mit NetWorker verwendet werden können. Einschließlich curl Befehle (Linux), PowerShell curl.exe (Windows) und REST API-Client-Browsererweiterungen. 

Es sind drei Header für die Verbindung erforderlich:   

• Content-Type: application/json
• Akzeptieren: application/json
• Authorization: Basic mit Base-64-kodiertem Nutzernamen und Kennwort

In Umgebungen, in denen mehrere NetWorker-Datenzonen über einen einzigen NetWorker-AUTHC-Server authentifiziert werden, ist ein zusätzlicher Header erforderlich:

• X-NW-AUTHC-BASE-URL:AUTHC_HOSTNAME_OR_IP:AUTHC_PORT

Die NetWorker-REST-API wird im folgenden Basis-URI verfügbar gemacht:

https://[nw-server-hostname]:9090/nwrestapi/v3

Es gibt verschiedene Versionen von APIs. Seit der Implementierung der REST API wurden Verbesserungen eingeführt. Änderungen an diesen Endpunkten werden ausführlich beschrieben unter: https://developer.dell.com/apis/2378/versions/v3/docs/GettingStarted.md

Das vollständige JSON-Schema ist verfügbar unter:

https://[nw-server-hostname]:9090/nwrestapi/v3/schemas/swagger.json

REST API-Funktionen

Einige Beispiele:

GET:

Listen Sie alle Clients auf.                                            

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients

Nur ein Client, mit nur drei Feldern (hostname, saveSets und protectionGroups)      

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?fl=hostname,saveSets,protectionGroups&q=hostname:nwserver121

Listen Sie die Schutzgruppen auf, in denen sich ein Client befindet.     

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?fl=protectionGroups&q=hostname:nwserver121

Zeigen Sie aktuelle Warnmeldungen an.                                     

https://[nw-server-hostname]:9090/nwrestapi/v3/global/alerts

Zeigen Sie kürzlich fehlgeschlagene Jobs an.                               

https://[nw-server-hostname]:9090/nwrestapi/v3/global/jobs?q=completionStatus:"Failed"&fl=clientHostname,startTime,name,message

Listen Sie die Workflows in einer Policy auf (in diesem Beispiel WinFS genannt).                   

https://[nw-server-hostname]:9090/nwrestapi/v3/global/protectionpolicies/WinFS/workflows

Listet nur die Eigenschaften einer Saveset-Instanz auf (wie durch Clienthostname und Saveset definiert).      

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?q=hostname:vm-lego-231 and saveSets:"/etc"

BEREITSTELLEN:

Starten Sie eine Workflowaktion.                                 

https://[nw-server-hostname]:9090/nwrestapi/v3/global/protectionpolicies/Angela/workflows/WinFS/op/backup
                                                      JSON Body: 
                                                      {
                                                       }

Erstellen Sie eine neue Clientinstanz (mit Standardwerten für alle Eigenschaften außer den vier aufgeführten).           

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients  
                                                     JSON Body 
                                                     {    
            "hostname": "vm-lego-231",
            "backupType": "Filesystem",
            "saveSets": [ "/etc" ],
            "protectionGroups" : [ "LinuxFS" ]
                                                          

Beispiele für die Befehlszeile:

Linux:

Für Systeme mit python installiert:

curl -k -u Administrator:'ADMINISTRATOR_PASSWORD' https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT | python -m json.tool

curl -k -u Administrator:'ADMINISTRATOR_PASSWORD' https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT | jq

[root@nsr ~]# curl -k -u Administrator https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01 | jq
Enter host password for user 'Administrator':
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2820    0  2820    0     0  72307      0 --:--:-- --:--:-- --:--:-- 72307
{
  "accessWeight": 1,
  "accesses": "66",
  "activeSessions": [],
  "autoMediaManagement": false,
  "autoRecoverDtf": "None",
  "cdi": "NotUsed",
  "cleaningRequired": false,
  "consecutiveErrors": "0",
  "currentNSRMMDCount": "1",
  "dataDomainFibreChannel": false,
  "dataDomainRetentionLockMode": "None",
  "deviceAccessInfo": "ddve01.amer.lan:/nsr/VMBackupDevice01",
  "deviceBlockSize": "HandlerDefault",
  "dltWormCapable": false,
  "idleDeviceTimeout": 0,
  "jukeboxDevice": "No",
  "links": [
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/opstatus",
      "title": "Volume operation status"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/label",
      "title": "Label volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/mount",
      "title": "Mount volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/unmount",
      "title": "Unmount volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/verifylabel",
      "title": "Verify volume label"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/erase",
      "title": "Erase the device"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/volumes/4267924096",
      "title": "Volume"
    }
  ],
  "longVolumeId": "703cdc60-00000005-fe635a80-66635a80-00045000-592bbe56",
  "maxConsecutiveErrors": 20,
  "maxNsrmmdCount": 4,
  "maxSession": 60,
  "mediaFamily": "Disk",
  "mediaType": "Data Domain",
  "message": "mounted Data Domain disk VMBackupPool.001",
  "mountedVolume": "VMBackupPool.001",
  "name": "ddve01.amer.lan_VMBackupDevice01",
  "ndmp": false,
  "operationParameters": [],
  "password": "*******",
  "pathId": "53f9269d-00000010-e2f994bd-66635a7e-00035000-592bbe56",
  "readOnly": false,
  "remoteUser": "ddboost",
  "reserveRelease": "None",
  "resourceId": {
    "id": "178.0.90.20.0.0.0.0.196.80.99.102.192.168.9.150",
    "sequence": 256
  },
  "saveLockout": 0,
  "saveMountTimeout": 30,
  "secureMultiTenancy": false,
  "sharedDevices": "Done",
  "statistics": [
    "elapsed = 17310",
    "errors = 0",
    "last rate = 0",
    "max clients = 0",
    "file marks = 0",
    "rewinds = 0",
    "files skipped = 0",
    "records skipped = 0",
    "current file = 0",
    "current record = 0",
    "seek files = 0",
    "seek records = 0",
    "estimated kb = 0",
    "amount kb = 0",
    "file amount kb = 0",
    "sessions = 0"
  ],
  "status": "Enabled",
  "suspectedDevice": false,
  "tapeAlertsCritical": [],
  "tapeAlertsInformation": [],
  "tapeAlertsWarning": [],
  "targetSession": 20,
  "unlabeledVolumeLoaded": false,
  "verifyLabelOnEject": false,
  "volumeBlockSize": "256 KB",
  "volumeCurrentCapacity": "0 KB",
  "volumeErrorNumber": "0",
  "volumeExpiration": "Sun Jun  7 15:07:44 2026",
  "volumeId": "4267924096",
  "volumeLabel": "VMBackupPool.001",
  "volumePool": "VMBackupPool",
  "warnOnSuspectVolumesInPercent": 80,
  "wormCapable": false,
  "wormCartridgePresent": false,
  "writeEnabled": true
}
[root@nsr ~]#

Windows (PowerShell):

curl.exe -k -u Administrator:'ADMISTRATOR_PASSWORD' "https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT" | ConvertFrom-Json | ConvertTo-Json -Depth 50

Beispiel:

PS C:\Users\Administrator.NETWORKER> curl.exe -k -u Administrator:'!Password1' "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup" | ConvertFrom-Json | ConvertTo-Json -Depth 50
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2824    0  2824    0     0  20311      0 --:--:-- --:--:-- --:--:-- 21074
{
    "accessWeight":  1,
    "accesses":  "45",
    "activeSessions":  [

                       ],
    "autoMediaManagement":  false,
    "autoRecoverDtf":  "None",
    "cdi":  "NotUsed",
    "cleaningRequired":  false,
    "consecutiveErrors":  "0",
    "currentNSRMMDCount":  "1",
    "dataDomainFibreChannel":  false,
    "dataDomainRetentionLockMode":  "None",
    "deviceAccessInfo":  "dd3300-ff28:/win-srvr02/Backup",
    "deviceBlockSize":  "HandlerDefault",
    "dltWormCapable":  false,
    "idleDeviceTimeout":  0,
    "jukeboxDevice":  "No",
    "links":  [
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/opstatus",
                      "title":  "Volume operation status"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/label",
                      "title":  "Label volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/mount",
                      "title":  "Mount volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/unmount",
                      "title":  "Unmount volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/verifylabel",
                      "title":  "Verify volume label"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/erase",
                      "title":  "Erase the device"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/volumes/3963713",
                      "title":  "Volume"
                  }
              ],
    "longVolumeId":  "0aea479c-00000005-003c7b41-693c7b41-00025000-e6b5bb56",
    "maxConsecutiveErrors":  20,
    "maxNsrmmdCount":  4,
    "maxSession":  60,
    "mediaFamily":  "Disk",
    "mediaType":  "Data Domain",
    "message":  "writing, done",
    "mountedVolume":  "win_srvr02.networker.lan.dddefault.001",
    "name":  "dd3300-ff28_Backup",
    "ndmp":  false,
    "operationParameters":  [

                            ],
    "password":  "*******",
    "pathId":  "a30a7858-00000010-5ded760e-693c7b41-00015000-e6b5bb56",
    "readOnly":  false,
    "remoteUser":  "loudekboost",
    "reserveRelease":  "None",
    "resourceId":  {
                       "id":  "176.0.164.7.0.0.0.0.69.121.60.105.192.168.0.22",
                       "sequence":  100
                   },
    "saveLockout":  0,
    "saveMountTimeout":  30,
    "secureMultiTenancy":  false,
    "sharedDevices":  "Done",
    "statistics":  [
                       "elapsed = 228514",
                       "errors = 0",
                       "last rate = 0",
                       "max clients = 0",
                       "file marks = 0",
                       "rewinds = 0",
                       "files skipped = 0",
                       "records skipped = 0",
                       "current file = 0",
                       "current record = 0",
                       "seek files = 0",
                       "seek records = 0",
                       "estimated kb = 0",
                       "amount kb = 0",
                       "file amount kb = 52206",
                       "sessions = 0"
                   ],
    "status":  "Enabled",
    "suspectedDevice":  false,
    "tapeAlertsCritical":  [

                           ],
    "tapeAlertsInformation":  [

                              ],
    "tapeAlertsWarning":  [

                          ],
    "targetSession":  20,
    "unlabeledVolumeLoaded":  false,
    "verifyLabelOnEject":  false,
    "volumeBlockSize":  "256 KB",
    "volumeCurrentCapacity":  "0 KB",
    "volumeErrorNumber":  "0",
    "volumeExpiration":  "Sun Dec 12 15:29:53 2027",
    "volumeId":  "3963713",
    "volumeLabel":  "win_srvr02.networker.lan.dddefault.001",
    "volumePool":  "Data Domain Default",
    "warnOnSuspectVolumesInPercent":  80,
    "wormCapable":  false,
    "wormCartridgePresent":  false,
    "writeEnabled":  true
}

Erforderliche Informationen für den Support

Umgebung:

• NetWorker-Servername
• NetWorker-Version und Build-Nummer
• Typ und Version des Betriebssystems des NetWorker-Serverhosts

Linux:

hostname
strings /usr/sbin/nsrd | grep -i "(#)"
cat /etc/*release
uname -a

Windows:

nsrwatch

Problemdetails:

• Erläutern Sie, welcher REST API-Vorgang durchgeführt wird (GET, POST, PUT, DELETE), den verwendeten URI und alle JSON-Textinhalte (falls zutreffend). 
• REST API-Antwortcode und etwaige bereitgestellte Fehlermeldungen.
• Ist die erste Verbindung und Autorisierung zwischen dem REST API-Client und NetWorker erfolgreich?

Protokollerfassung:

• Gerenderte daemon.raw Protokolldatei vom NetWorker-Server:
  • Linux: /nsr/logs/daemon.raw
  • Windows: C:\Program Files\EMC NetWorker\nsr\logs\daemon.raw
  • NetWorker: Verwenden von nsr_render_log
• REST API-Protokolle vom NetWorker-Server:  /nsr/logs/restapi (Linux) oder EMC NetWorker\nsr\logs\restapi (Windows)
• Informationen zu Authentifizierungsproblemen finden Sie in der standardmäßigen NetWorker-Authentifizierungsanmeldung /nsr/authc/logs (Linux) oder ..\EMC NetWorker\nsr\authc-server\tomcat\logs (Windows)

Debuggen:

Leistung:

Vor der Beurteilung von leistungsbezogenen Problemen mit der REST-API ist es wichtig festzustellen, ob das Problem bei allen REST-API-Funktionen oder bei bestimmten Funktionen auftritt. Beispielsweise können GET-Anforderungen auf globalen Endpunkten wie Clients, Jobs, Volumes usw. eine Menge Daten abrufen. Diese Art von Anfragen kann zu einer hohen Auslastung der Systemressourcen und zu Timeouts führen.
Siehe: NetWorker-REST-API: Zeitweise Timeouts bei HTTP GET-Anforderungen

Wenn Leistungsprobleme auf großen globalen Endpunkten beobachtet werden, wird empfohlen, den "Abfragelistenfilter" (q) oder "Feldlistenfilter" (fl), um die zurückgegebenen Daten auf spezifische benötigte Informationen zu reduzieren. Im obigen Wissensdatenbank-Artikel werden diese Einstellungen ausführlich beschrieben. Zusätzliche Informationen finden Sie im REST API-Entwicklerhandbuch: Dell Technologies Entwickler 

Wenn das Problem mit der REST API-Performance zusammenhängt, können Sie die folgenden Optionen verwenden, um den Ressourcenverbrauch des von API-Aufrufen verwendeten nsrtomc+-Prozesses nachzuverfolgen.

Linux:  

top -b | awk '/nsrtomc+/ {print strftime("%Y-%m-%d-%H:%M:%S", systime()), $0}'

Diese Ausgabe zeigt die standardmäßige obere Ausgabe, jedoch mit für Menschen lesbaren Zeitstempeln. Dies kann verwendet werden, um die CPU- und Speicherauslastung durch den Prozess zu überprüfen und wie lange er in einem bestimmten Zustand blieb, wenn ein REST-Aufruf durchgeführt wurde. Dies kann mit den restapi.log- und AUTHC-Protokollen verglichen werden, um zu sehen, welche Aufrufe wie häufig getätigt wurden.
 

Windows: 

Für Windows-Server müssen Sie etwa "Performance Monitor:

1. Öffnen Sie den Systemmonitor als Administrator.
2. Erweitern Sie im linken Bereich Monitoring Tools und wählen Sie Performance Monitor aus.
3. Klicken Sie mit der rechten Maustaste in den rechten Fensterbereich und wählen Sie Alle Zähler entfernen aus.
4. Klicken Sie mit der rechten Maustaste in den rechten Bereich und wählen Sie Zähler hinzufügen aus.
5. Erweitern Sie unter Available Counters die Option Memory, wählen Sie % Commit Bytes aus und klicken Sie auf Add.
6. Wählen Sie unter Arbeitsspeicher die Option Verfügbare Bytes aus und klicken Sie auf Hinzufügen.
7. Erweitern Sie unter Available Countersdie Option Process und wählen Sie % Processor Time aus. Wählen Sie unter Instances of Selected object den ersten Java-Eintrag aus und klicken Sie auf Add.
8. Erweitern Sie unter Verfügbare Indikatoren die Option Prozessorinformationen, wählen Sie % Prozessordienstprogramm aus und klicken Sie auf Hinzufügen.
9. Die Zähler Added im rechten Fensterbereich sollten Folgendes anzeigen:

10. Klicken Sie auf OK. Klicken Sie mit der rechten Maustaste auf Performance Monitor und klicken Sie auf New-Data> Collector Set.
11. Geben Sie einen Namen ein, z. B.: RESTAPI_MON.
12. Klicken Sie auf dem Bildschirm Speicherort auf Weiter, es sei denn,  Sie geben einen alternativen Ausgabespeicherort an.
13. Wählen Sie Speichern und schließen aus und klicken Sie auf Fertigstellen.
14. Öffnen Sie im linken Fensterbereich unter Benutzerdefinierte Data Collector-Sätze> die Option RESTAPI_MON und wählen Sie Comma Separated als Protokollformat aus. Klicken Sie auf OK.

15. Wählen Sie im linken Fensterbereich unter User Collector Sets den>RESTAPI_MON Datensammlersatz aus und klicken Sie auf Start (Schaltfläche Play)
16. Wenn der Standardausgabespeicherort verwendet wurde, wird die .csv Datei unter C:\PerfLogs\Admin\RESTAPI_MON.
17. Sobald das Problem beobachtet und in der Ausgabedatei aufgezeichnet wurde, können Sie das Monitoring beenden, indem Sie unter User Collector Sets – User Defined auf Stop klicken.