NetWorker: Przewodnik rozwiązywania problemów i weryfikacji interfejsu API REST

Obejrzyj w serwisie YouTube

Rozpoczęcie pracy

Interfejs programowania aplikacji (API) Representational State Transfer (REST) zapewnia programowy dostęp do usługi ochrony danych NetWorker. Korzystając z interfejsu API REST, użytkownicy NetWorker mogą tworzyć aplikacje klienckie w celu automatyzacji operacji NetWorker. Interfejs API REST NetWorker jest instalowany w ramach instalacji serwera NetWorker w tym samym kontenerze Apache Tomcat, co usługi uwierzytelniania NetWorker. Uwierzytelnianie odbywa się przy użyciu tych samych poświadczeń, które są używane w konsoli NetWorker Management Console.  

Interfejs API REST umożliwia interakcję z zasobami identyfikowanymi przez adresy Uniform Resource Identifier (URI). Używa czasowników HTTP (HEAD, GET, PUT, POST, DELETE) do interakcji z identyfikatorem Uniform Resource Identifier (URI) w sposób bezstanowy. Serwer nie zawiera stanu klienta, a każdy komunikat jest opisowy sam przez się.

Ten dokument dotyczy interakcji z zasobami NetWorker przy użyciu wywołań interfejsu API REST napisanych przez użytkownika. Nie mylić z wywołaniami interfejsu API REST, które są używane przez operacje NetWorker zaplecza.
 

Nawiązywanie połączenia z NetWorker:

Istnieje kilka różnych technologii klienta interfejsu API REST, których można użyć do uruchamiania poleceń w celu nawiązania połączenia z NetWorker; Tym curl polecenia (Linux), PowerShell curl.exe (Windows) i rozszerzenia przeglądarki klienta interfejsu API REST. 

Do nawiązania połączenia potrzebne są trzy nagłówki:   

• Typ zawartości: application/json
• Zaakceptować: application/json
• Authorization: Podstawowy z nazwą użytkownika i hasłem zakodowanym w formacie Base 64

W środowiskach, w których istnieje wiele stref danych NetWorker uwierzytelnianych za pośrednictwem jednego serwera NetWorker AUTHC, wymagany jest dodatkowy nagłówek:

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

Interfejs API REST NetWorker jest uwidoczniony w następującym podstawowym identyfikatorze URI:

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

Istnieją różne wersje interfejsów API. Od czasu początkowego wdrożenia interfejsu API REST wprowadzono udoskonalenia. Zmiany tych punktów końcowych zostały opisane w: https://developer.dell.com/apis/2378/versions/v3/docs/GettingStarted.md

Pełny schemat JSON jest dostępny pod adresem:

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

Funkcje interfejsu API REST

Kilka przykładów:

POBIERZ:

Wyświetl listę wszystkich klientów.                                            

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

Tylko jeden klient, pokazujący tylko trzy pola (nazwa hosta, saveSets i protectionGroups)      

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

Wyświetl listę grup ochrony, do których należy jeden klient.     

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

Pokaż bieżące alerty.                                     

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

Pokaż ostatnie zadania, które zakończyły się niepowodzeniem.                               

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

Wyświetl listę przepływów pracy w jednej zasadzie (w tym przykładzie o nazwie WinFS ).                   

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

Wyświetla listę właściwości tylko jednej instancji zestawu zapisu (zdefiniowanej przez nazwę hosta klienta i zestaw zapisu).      

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

POST:

Rozpocznij akcję przepływu pracy.                                 

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

Utwórz nową instancję klienta (z wartościami domyślnymi dla wszystkich właściwości z wyjątkiem czterech wymienionych).           

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

Przykłady wiersza poleceń:

Linux:

W przypadku systemów, które mają python :

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

Przykład:

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
}

Informacje wymagane do uzyskania pomocy technicznej

Środowisko:

• Nazwa serwera NetWorker
• Wersja i numer kompilacji NetWorker
• Typ i wersja systemu operacyjnego hosta serwera NetWorker

Linux:

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

Windows:

nsrwatch

Szczegóły problemu:

• Wyjaśnij, która operacja interfejsu API REST jest wykonywana (GET, POST, PUT, DELETE), używany identyfikator URI, zawartość treści JSON (jeśli dotyczy). 
• Kod odpowiedzi interfejsu API REST i wszelkie wyświetlone komunikaty o błędach.
• Czy początkowe połączenie i autoryzacja między klientem interfejsu API REST a NetWorker zakończyły się pomyślnie?

Kolekcja dzienników:

• Wyrenderowany plik dziennika daemon.raw z serwera NetWorker:
  • Linux: /nsr/logs/daemon.raw
  • Windows: C:\Program Files\EMC NetWorker\nsr\logs\daemon.raw
  • NetWorker: korzystanie z nsr_render_log
• Dzienniki interfejsu API REST z serwera NetWorker:  /nsr/logs/restapi (Linux) lub EMC NetWorker\nsr\logs\restapi (Windows)
• W przypadku problemów z uwierzytelnianiem zapoznaj się ze standardowym logowaniem uwierzytelniania NetWorker /nsr/authc/logs (Linux) lub ..\EMC NetWorker\nsr\authc-server\tomcat\logs (Windows)

Debugowania:

Wydajności:

Przed oceną problemów związanych z wydajnością interfejsu API REST ważne jest, aby ustalić, czy problem występuje we wszystkich funkcjach interfejsu API REST, czy w określonych funkcjach. Na przykład żądania GET na globalnych punktach końcowych, takich jak klienci, zadania, woluminy itd., mogą pobierać dużo danych. Tego typu żądania mogą powodować wysokie wykorzystanie zasobów systemowych i przekroczenie limitu czasu.
Zobacz: Interfejs API REST NetWorker: Żądania HTTP GET sporadycznie przekraczają limit czasu

W przypadku wystąpienia problemów z wydajnością na dużych globalnych punktach końcowych zaleca się użycie "filtru listy zapytań" (q) lub "filtr listy pól" (fl), aby ograniczyć zwracane dane do konkretnych potrzebnych informacji. Powyższa baza wiedzy zawiera szczegółowe informacje na temat tych ustawień, a dodatkowe informacje są dostępne w przewodniku dla deweloperów interfejsu API REST: Deweloper Dell Technologies 

Jeśli problem jest związany z wydajnością interfejsu API REST, możesz użyć następujących opcji, aby śledzić zużycie zasobów przez proces nsrtomc+ używany przez wywołania interfejsu API.

Linux:  

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

To wyjście pokazuje standardowe górne wyjście, ale ze znacznikami czasu czytelnymi dla człowieka. Może to służyć do przeglądania użycia procesora CPU i pamięci przez proces oraz tego, jak długo pozostawał w określonym stanie, gdy wykonano wywołanie REST. Można to porównać z dziennikami restapi.log i AUTHC, aby zobaczyć, które wywołania zostały wykonane i jak często.
 

Windows: 

W przypadku serwerów z systemem Windows należy zainstalować coś w rodzaju "Monitor wydajności:

1. Otwórz Monitor wydajności jako administrator.
2. W lewym okienku rozwiń Narzędzia monitorowania i wybierz Monitor wydajności.
3. Kliknij prawym przyciskiem myszy w prawym okienku i wybierz polecenie Usuń wszystkie liczniki.
4. Kliknij prawym przyciskiem myszy w prawym okienku i wybierz polecenie Dodaj liczniki.
5. W obszarze Dostępne liczniki rozwiń pozycję Pamięć, wybierz pozycję % zatwierdzonych bajtów i kliknij przycisk Dodaj.
6. W obszarze Pamięć  wybierz opcję Dostępne bajty i kliknij przycisk Dodaj.
7. W obszarze Dostępne liczniki rozwiń pozycję Proces i wybierz opcję % czasu procesora, a następnie w obszarze Wystąpienia wybranego obiektu wybierz pierwszy wpis Java kliknij przycisk Dodaj.
8. W obszarze Dostępne liczniki rozwiń Informacje o procesorze i wybierz opcję % Narzędzie procesora, kliknij przycisk Dodaj.
9. Dodano liczniki w prawym okienku powinny zawierać:

10. Kliknij przycisk OK. Kliknij prawym przyciskiem myszy pozycję Monitor wydajności, a następnie kliknij opcję Nowy zestaw modułów> zbierających dane.
11. Podaj nazwę, na przykład: RESTAPI_MON.
12. Na ekranie lokalizacji kliknij przycisk Dalej,chyba  że zdecydujesz się określić alternatywną lokalizację wyjściową.
13. Wybierz opcję Zapisz i zamknij , a następnie kliknij przycisk Zakończ.
14. W lewym okienku w obszarze Zestawy modułów> zbierających dane — zdefiniowane przez użytkownika otwórz plik RESTAPI_MON i wybierz opcję Rozdzielane przecinkami dla formatu dziennika, kliknij przycisk OK.

15. W lewym okienku w obszarze Zestawy> modułów zbierających dane — zdefiniowane przez użytkownika wybierz zestaw RESTAPI_MON zbierania danych i kliknij przycisk Start (przycisk Odtwórz)
16. Jeśli użyto domyślnej lokalizacji wyjściowej, plik .csv pojawi się w obszarze C:\PerfLogs\Admin\RESTAPI_MON.
17. Po zaobserwowaniu problemu i zarejestrowaniu go w pliku wyjściowym można zatrzymać monitorowanie, klikając opcję Zatrzymaj w obszarze Zestawy modułów zbierających dane — zdefiniowane przez użytkownika.