This documentation supports the 21.3 (12.3) version of BMC Discovery.

discovery.restfulGet

discovery.restfulGet(target, protocol, path[, headers, port, use_http, address])

This function performs a GET request on the target using the specified RESTful protocol and returns a node containing information about the discovered system.

The function takes the following parameters:

  • target — the device or data source against which the request is performed.
  • protocol — specifies the RESTful protocol, which is used to select the appropriate credential and to handle device-specific behavior. The following protocols are supported:
    • Generic protocols
      • No authentication — ""
      • HTTP basic authentication — basic_auth
      • HTTP digest authentication — digest_auth
      • OAuth2 authentication. The OAuth2 authentication method used is a client credentials grant, as described on the IETF Tools website — oauth2
      • Authentication by using an API key — api_key_auth
    • Device or vendor-specific protocols
      • ArubaOS REST API with token-based authentication — arubaos_auth
      • AVI Vantage Web API — avi_auth
      • BeyondTrust Remote Support Web API — beyond_trust_auth
      • Ceph API — ceph_auth
      • Cisco APIC REST API — apic_auth
      • Citrix NetScaler NITRO REST API — netscaler_auth
      • Cohesity REST API — cohesity_auth
      • Control-M Web API — controlm_auth
      • Dell Compellent SCSeries Web API — dell_compellent_auth
      • Dell EMC Data Domain REST API — datadomain_auth
      • Dell EMC ECS Web API — emc_ecs_auth
      • Dell EMC Powerflex REST API (version 4) — powerflex_v4_auth
      • Dell EMC PowerScale REST API — dell_emc_powerscale_auth
      • Dell EMC PowerVault Web API — dell_emc_powervault_auth
      • Dell EMC ScaleIO / VxFlex / PowerFlex REST API — scaleio_auth
      • F5 REST API with token-based authentication — f5_auth
      • Fortinet FortiADC REST API — forti_adc_auth
      • HDI REST API — hdi_auth
      • HP Moonshot Web API — hp_moonshot_auth
      • HPE OneView device authentication — hpe_oneview_auth
      • Huawei OceanStor REST API — huawei_oceanstor_auth
      • IBM DS8000 REST API — ibm_ds8000_auth
      • IBM Spectrum Control REST API — ibm_spectrum_control_auth
      • IBM TS Tape Library REST API — ibm_ts_auth
      • NetApp StorageGRID REST API — netapp_storagegrid_auth
      • NexentaStor REST API — nexentastor_auth
      • Nimble Storage Web API — nimble_auth
      • Nutanix HCI REST API — nutanix_auth
      • Pure Storage FlashArray REST API — pure_storage_auth
      • Pure Storage FlashBlade REST API — pure_storage_fb_auth
      • SANnav REST API — sannav_auth
      • Tintri REST API — tintri_auth
      • Ubiquiti REST API — ubiquiti_auth
      • VMware Skyline Collector API — skyline_auth
  • path — a string specifying the URL path on the target, for example /api/about. The IP address and access method are automatically added according to the credential and the target endpoint.
  • headers — an optional dictionary of HTTP headers to be sent with the request. You can use this to implement custom protocols that require certain HTTP headers to be present. For requests using the VPLEX protocol, the username and password fields are automatically added. It is not possible to override automatically added values.
  • port — an optional integer. Port on which HTTP server listens. The default value is 80 if use_http is True; otherwise, 443 is used.
  • use_http — boolean, optional. Whether to use HTTP instead of HTTPS. Default value is False (HTTPS).
  • address —  the particular IP address to connect to. If the address is not specified, the call uses the address of the target device that is being scanned.

The function returns a DiscoveryAPIResult node containing the following:

  • response_status — the response status.
  • response_reason — the response reason.
  • response_headers — a table of header entries. Sensitive fields are removed.
  • response_body — the body of the response. When data is successfully retrieved, and if the response_body is a JSON-encoded string, it can be decoded by using the json-decode function.

The following example shows a simple HTTP GET request using no authentication and basic handling of the JSON-encoded response:

// GET request, no authentication, HTTP on default port. Response is JSON encoded
result := discovery.restfulGet(process, '', '/api/about', use_http:=true);
        
if result then
   if result.response_status = 200 then
       if result.response_body then
        
           decoded := json.decode(result.response_body);  
            
           if decoded then
               product_version := decoded["version"];
               log.debug("Found product version from REST API: %product_version%");
           else
              log.debug("Failed to json decode /api/about response. Raw response: %result.response_body%");
           end if;
       else
           log.debug("/api/about returned no response body");
       end if;           
   else
       log.debug("/api/about returned %result.response_status%");
   end if;           
else
   log.debug("Failed to query /api/about");            
end if;

The following examples show a variety of GET requests using generic protocols and a request to the Nimble Storage Web API using the nimble_auth protocol:

// GET request, Basic Authentication, HTTP on a custom port
result := discovery.restfulGet(process, "basic_auth", "/basic/foo", port:=8800, use_http:=true);

// GET request, Digest Authentication, HTTPS on a custom port
result := discovery.restfulGet(process, "digest_auth", "/digest/xml", port:=8443);

// GET request, OAuth2 Authentication, HTTPS on default port
result := discovery.restfulGet(process, 'oauth2', '/api/v1.1/admin/baseline');

// GET request, OAuth2 Authentication, headers, HTTPS on default port
headers := table();
headers['header_param'] :="header_value";

result := discovery.restfulGet(process, "oauth2", "/api/v1.1/vault/credentials", headers);

// GET request, API key Authentication, HTTPS on default port, specifying
results := discovery.restfulGet(ds,
                               "api_key_auth",
                               "api/?type=op&cmd=<show><interface>all</interface></show>&target=%device.serial%");

// GET request, Nimble Authentication, HTTPS on a custom port
result := discovery.restfulGet(storage_device, 'nimble_auth', '/v1/arrays', port:=5392);


If the request fails, the function returns none.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*