Skip to main content
Cisco SD-WAN
Support
Product Documentation
Viptela Documentation

Overview of Bulk API Operations

RESTful bulk API calls allow you to issue a single RESTful API command to collect information about multiple vEdge routers in the overlay network. The information is returned in batches.

You can perform two types of bulk API operations:

  • State—These operations return status information about the Viptela devices, such as the number and state of OMP and BFD sessions.
  • Statistics—These operations return statistics from the Viptela devices, such as the number of transmitted and received data packets.

This article provides an overview of the state and statistics bulk API operations.

State Bulk API Operations

State bulk API operations collection state and status information for all Viptela devices in the overlay network.

To collect state information in a bulk API operation, issue a call to the following URL:

https://vManage-ip-address:8443/dataservice/data/device/state/data-type?count=number

data-type is the parameter to collect state information about. It can be one of the following. Note that the parameters are case-sensitive.

Data Type Parameter Description
BFDSessions BFD sessions
BGPNeighbor BGP neighbors
Bridge Bridge interfaces
ControlConnection Active control connections
ControlLocalProperty Basic configuration parameters and local device properties related to the control plane
ControlWanInterface WAN interface control connection information
HardwareAlarms Active hardware alarms
HardwareEnvironment Status information about router components, including temperature
HardwareInventory Inventory of router hardware components, including serial numbers
Interface Interface information
OMPPeer Active OMP peering sessions
SystemStatus Logging, reboot, and configuration history
System Summary of general system-wide parameters

After the ?, specify the following parameter:

  • count—(Mandatory) Number of devices to query. This number corresponds to the number of records returned in the batch. number can be from 1 through 10000.

A state bulk API call returns data and batch (page) information in the following format:

{
  "header": {
    "generatedOn": timestamp,
    "viewKeys": {
      "uniqueKey": [
        "vdevice-dataKey"
      ],
      "preferenceKey": "output-format"
    },
    "columns": [],
    "fields": []
  },
  "data": [],
  "pageInfo": {
    "startId": "batch:start-device-identifier",
    "endId": "batch:end-device-identifier",
    "moreEntries": (false | true),
    "count": number
  }
}

The output of a bulk API state call contains the following sections:

  • header—Timestamp marking when the data was collected, unique operation identifier, and formatting options for the collected data.
  • data—State data itself.
  • pageInfo—Information about the batch (page) itself:
    • startId—Batch number and the identifier of the first device in the batch. The startId and endId for a single call have the same batch number. For each call, the batch number is unique.
    • endId—Batch number and the identifier of the last device in the batch.
    • moreEntries—Flag that indicates whether more data is available for given state type. If no more data is available, this field returns false. If more data is available, this field returns true.
    • count—Number of records returned in the batch.

If moreEntries is true, retrieve the next batch of data by issuing a call with the following URL:

https://vManage-ip-address:8443/dataservice/data/device/state/data-type?startId=batch:start-device-identifier&count=number

startId identifies the first device to include in this next batch. To continue from the previous batch, specify the endId value from the returned pageInfo. For example, if the returned endId value is 203:10719, specify this as the startID in the URL. The returned data from the second batch then starts with device 10720. (For the second batch, the batch number is different, because the data returned in each call are identified by a unique batch number.)

count is the number of devices to query, and it corresponds to the number of records returned in the batch. number can be from 1 through 10000.

Statistics Bulk API Operations

Statistics bulk API operations collection statistics for all Viptela devices in the overlay network.

To collect statistics information in a bulk API operation, issue a call to the following URL:

https://vManage-ip-address:8443/dataservice/data/device/statistics/data-type?endDate=yyyy-MM-ddThh:mm:ss&startDate=yyyy-MM-ddThh:mm:ss&count=number&timeZone=timezone

data-type is the parameter to collect statistics about. It can be one of the following. Note that the parameters are case-sensitive.

Parameter Description
alarm Hardware alarm statistics
approutestasstatistics Statistics about all traffic characteristics for all data plane tunnels
auditlog Record of configuration changes
bridgeinterfacestatistics Bridge interface statistics
bridgemacstatistics Bridge MAC statistics
cflowdstatistics Cflowd packet statistics
cloudxstatistics Cloud Express statistics
deviceconfiguration Device configuration statistics
deviceevent Events that have occurred on the device
devicesystemstatusstatistics Device memory and CPU statistics
dpistatistics Statistics for DPI flows on a vEdge router
flowlogstatistics Cflowd logging statistics
interfacestatistics Interface statistics
wlanclientinfostatistics Wireless LAN client statistics

After the ?, specify the following parameters:

  • endDate=yyyy-MM-ddThh:mm:ss—(Mandatory) End of time range to gather statistics.
  • startDate=yyyy-MM-ddThh:mm:ss—(Mandatory) Beginning of time range to gather statistics.
  • count—(Optional) Number of devices to query, and it corresponds to the number of records returned in the batch. number can be from 1 through 10000. The default is 1000.
  • timeZone=timezone—(Optional) Timezone for the start and end dates. Use the three-letter timezone.

A statistics bulk API call returns data and batch (page) information in the following format:

{
  "header": {
    "generatedOn": timestamp,
    "viewKeys": {
      "uniqueKey": [],
      "preferenceKey": "output-format"
    },
    "columns": [
      
    ],
    "fields": [
      
    ]  
  },
  "data": [
    
  ],
  "pageInfo": {
    "startTime": "start-time",
    "endTime": "end-time",
    "scrollId": "scroll-identifier",
    "hasMoreData": (false | true),
    "count": number,
    "totalCount": number
  }
}

The output of a bulk API statistics call contains the following sections:

  • header—Timestamp marking when the data was collected, unique operation identifier, and formatting options for the collected data.
  • data—Statistics data itself.
  • pageInfo—Information about the batch (page) itself:
    • startTime—Time, in UNIX time format, when first statistic in the batch was collected.
    • endTime—Time, in UNIX time format, when the last statistic in the batch was collected.
    • scrollId—Identifier of the current bulk session. It acts as a pointer to the next data entry. The scroll identifier expires after 10 minutes.
    • hasMoreData—Flag that indicates whether more data is available for given state type. If no more data is available, this field returns false. If more data is available, this field returns true.
    • count—Number of records returned in the batch.
    • totalCount—Total number of data records available.

If hasMoreData is true, retrieve the next batch of data by issuing a call with the following URL:

https://vManage-ip-address:8443/dataservice/data/device/statistics/data-type?scrollId=scroll-identifier
  • Was this article helpful?