\nThe documentation pages in this section describe\nthe RESTful APIs included with Cascade Profiler and Cascade Express\nproducts. It is assumed that the reader has practical knowledge of\nRESTful APIs, so the documentation does not go into detail about what\nREST is and how to use it. Instead the documentation focuses on what\ndata can be accessed and how to access it.\n<\/p>\n\n
\nThe primary focus of the current version of the API is on providing\naccess to reporting data. The following information can be accessed\nvia the API:\n<\/p>\n
\nDetails about REST resources can be found in the Resources<\/b>\nsection. This overview continues with how to run reports and retrieve\ndata from them.\n<\/p>\n\nRunning a report<\/h2>\n\n
\nThe steps for running a report are described below. An easy way to\nlearn how to run reports and get data is to use the Demo\nReports<\/b> section of this documentation. In that section a number of\nexample reports are listed. If you click on any of the examples, the\nreport will run along with a listing on the right side of the screen\nfor each step in the process. It displays the REST resource, HTTP\nmethod, headers and body for both the request and response.\n<\/p>\n\n
\nFollow these steps to run a report:\n<\/p>\n\n
\nA criteria structure in either JSON or XML is submitted to the server\nusing the HTTP POST method. The resource to which the criteria\nstructure is posted is\ncalled \/profiler\/1.0\/reporting\/reports<\/b>. The details are\ndescribed in the Resources<\/b> section of this documentation.\n<\/p>\n\n
\nA key part of the report criteria is the ID of the template that\nshould be used to run the report. A special system template ID 184\nthat provides a high degree of flexibility is used in demo reports in\nthis documentation. Additionally, any template that is saved via the\nuser interface of the product can be used to run a report. In order to\nsave a template, the ID of that template must be passed in the report\ncriteria structure instead of 184. A template can be configured via\nthe user interface, saved via the product and then used in the REST\nAPI to generate reports and retrieve them in a rendered form or in raw\ndata form. Once a template is saved, its ID can be obtained\nvia the \/api\/profiler\/1.0\/reporting\/templates<\/b> REST resource.\n<\/p>\n\n2. Poll report status until the report completes.<\/h3>\n\n
\nIt may take a while for a report to complete. While the report is\nrunning, the client must poll for report status to know when the\nreport completes. When the call to create a new report succeeds, it\nreturns the URL for the newly created report. That URL may look\nsimilar to \/profiler\/1.0\/reporting\/reports\/1000<\/i>, which is the ID of\nthe new report.\n<\/p>\n\n
\nThe general way to describe this in REST documentation is\n\/profiler\/1.0\/reporting\/reports\/{id}<\/b> so this documentation uses\nthat syntax throughout. Note that the client does not need to know\nthat {id}<\/b> is really an ID of a report. Instead the client should\ntreat a given report, for example\n\/profiler\/1.0\/reporting\/reports\/1000, as a REST resource without\nparsing the parts of the URL.\n<\/p>\n\n
\nThe status of a report can be obtained by executing a GET method on\nthe report URL. The client should wait while the report is running and\nuntil the status turns to state.\n<\/p>\n\n
\nOnce the report completes, the client can retrieve its data or the\nrendered version of the report in a number of formats.\n<\/p>\n\n
\nThe following resources can be used to retrieve a rendered version of the report:\n
\nIf the client is a script that needs access to raw data, the\n\/profiler\/1.0\/reporting\/reports\/{id}\/queries<\/b> resource can be\nused with the GET method to obtain the list of elements (queries)\nfirst. The data shown in a typical report on the user interface may\ncome from more than one query, which is why the report structure needs\nto be determined first. However, the system template 184 described\nabove will have only one query and is easy to use for simple scripts.\n<\/p>\n\n
\nEach query resource provides metadata about the query, such as\nthe list of columns with descriptions of what the columns are. \n<\/p>\n\n
\nOnce the query is chosen, the\n\/profiler\/1.0\/reporting\/reports\/{id}\/queries\/{id}<\/b> resource can be used\nto get the report data.\n<\/p>\n\n
\nThe simple overview provided above cannot substitute for full\ndocumentation and it is not intended to do so. Please refer to Demo\nReports<\/b> section to see how reports are run. Look at the Coding\nExamples<\/b> under General Information<\/b> and\nexplore Resources<\/b> section of this documentation for more\ninformation.\n<\/p>\n\nAuthentication<\/h2>\n\n
\nAll REST requests must be authenticated. The Authentication<\/b>\nsection of the Common 1.0 API describes which authentication methods\nare presently supported. There are also examples that show how to use\neach of the different authentication methods.\n<\/p>\n\nRunning a report: Sample PHP script<\/h2>\n\n
Run a report to get bytes and packets for the top 20 hosts using the application WEB. Use BASIC Authentication.<\/p>\n\n 184,\n 'criteria' => Array('time_frame' => array('start' => $start,\n 'end' => $end),\n 'traffic_expression' => 'app WEB',\n 'query' => array('realm' => 'traffic_summary',\n 'group_by' => 'hos',\n 'sort_column' => 33,\n 'columns' => array(6, 33, 34))));\n \n $json = json_encode($struct);\n $columns = $struct['criteria']['query']['columns'];\n \n \/\/ Post to run the report\n $url = 'https:\/\/' . HOST . '\/api\/profiler\/1.0\/reporting\/reports.json';\n echo \"Run report:\\nPOST {$url}\\n{$json}\\n\\n\";\n $info = array();\n do_POST($url, $json, $info);\n if ($info['http_code'] != 201) {\n echo \"Unable to run report!\\n\";\n exit(1);\n }\n $location = get_header($info['headers'], 'Location');\n echo \"Generated: {$location}\\n\\n\";\n $status_url = 'https:\/\/' . HOST . '' . $location . '.json';\n \n \/\/ Wait for it to complete\n echo \"Please wait\\n\";\n while (true) {\n $info = array();\n $output = do_GET($status_url, $info);\n $s = json_decode($output, 1);\n print \" Percent completed {$s['percent']}, seconds remaining {$s['remaining_seconds']}...\\n\";\n if ($s['status'] == 'completed') {\n echo \"Completed\\n\\n\";\n break;\n }\n sleep(1);\n }\n \n \/\/ Get all quesries (In this exampe it is only one)\n $queries_url = 'https:\/\/' . HOST . '' . $location . '\/queries.json';\n $output = do_GET($queries_url, $info);\n $queries = json_decode($output, 1);\n \n \/\/ Print the data from all queries\n foreach ($queries as $q) {\n $query_id = $q['id'];\n $data_url = 'https:\/\/' . HOST . '' . $location . '\/queries\/' . $query_id . '.json?offset=0&limit=20&columns=' . join(',', $columns);\n $info = array();\n $output = do_GET($data_url, $info);\n $data = json_decode($output, 1);\n \n $h = array();\n foreach ($columns as $c)\n $h[] = find_column_name_by_id($q['columns'], $c);\n \n echo_csv($h, $data['data']);\n echo \"\\n\";\n }\n \n ?>\n
Run a report to get bytes and RTT for the top hosts.<\/p>\n\n import pprint\n \n from steelscript.netprofiler.core import NetProfiler\n \n from steelscript.common.service import UserAuth\n from steelscript.netprofiler.core.filters import TimeFilter\n from steelscript.netprofiler.core.report import TrafficSummaryReport\n \n # connection information\n username = '$username'\n password = '$password'\n auth = UserAuth(username, password)\n host = '$host'\n \n # create a new NetProfiler instance\n p = NetProfiler(host, auth=auth)\n \n # setup basic info for our report\n columns = [p.columns.key.host_ip,\n p.columns.value.avg_bytes,\n p.columns.value.network_rtt]\n sort_column = p.columns.value.avg_bytes\n timefilter = TimeFilter.parse_range(\"last 5 m\")\n \n # initialize a new report, and run it\n report = TrafficSummaryReport(p)\n report.run('hos', columns, timefilter=timefilter, sort_col=sort_column)\n \n # grab the data, and legend (it should be what we passed in for most cases)\n data = report.get_data()\n legend = report.get_legend()\n \n # once we have what we need, delete the report from the NetProfiler\n report.delete()\n \n # print out the top ten hosts!\n pprint.pprint(data[:10])\n
Run a report to get bytes and packets for the top 20 hosts using the application WEB. Use BASIC Authentication.<\/p>\n\n #!\/usr\/bin\/perl\n use strict;\n use warnings;\n \n use LWP::UserAgent;\n use HTTP::Request;\n use List::MoreUtils qw(firstidx);\n use JSON qw( encode_json decode_json );\n \n use constant HOST => '127.0.0.1';\n use constant LOGIN => 'admin';\n use constant PASSWORD => 'admin';\n \n our $ua = LWP::UserAgent->new;\n $ua->agent(\"ProfilerScript\/0.1\");\n \n our $API_BASE = \"https:\/\/127.0.0.1\";\n \n sub _request($) \n {\n my $req = shift;\n \n $req->header('Accept' => 'application\/json');\n $req->authorization_basic(LOGIN, PASSWORD);\n \n my $res = $ua->request($req);\n \n return {\n code => $res->code,\n status => $res->status_line,\n headers => $res->headers(),\n data => decode_json($res->content)\n };\n }\n \n sub GET($) \n {\n my $req = HTTP::Request->new(GET => $API_BASE . shift);\n return _request($req);\n }\n \n sub POST($$) \n {\n my $req = HTTP::Request->new(POST => $API_BASE . shift);\n $req->content_type('application\/json');\n $req->content(encode_json(shift));\n \n return _request($req);\n }\n \n my $end = time();\n my $start = $end - 5 * 60;\n \n my $struct = { \n template_id => 184, \n criteria => { \n time_frame => { \n start => $start, \n end => $end \n }, \n traffic_expression => \"app WEB\", \n query => { \n realm => \"traffic_summary\", \n group_by => \"hos\", \n sort_column => 33, \n columns => [6, 33, 34] \n } \n } \n };\n \n print \"Running report... \";\n \n my $response = POST('\/api\/profiler\/1.0\/reporting\/reports', $struct);\n die \"Unable to run report. $response->{data}->{error_text}\" unless $response->{code} == 201;\n \n my $loc = $response->{headers}->header('Location');\n \n while (1) \n {\n $response = GET($loc);\n printf \"\\rRunning report, %3d%% done, %d seconds remaining... \", \n $response->{data}->{percent}, \n $response->{data}->{remaining_seconds};\n \n last if $response->{data}->{status} eq 'completed';\n sleep(1);\n };\n \n print \"\\nLoading data...\\n\";\n \n $response = GET($loc . '\/queries');\n die \"Unable to load queries. $response->{data}->{error_text}\" unless $response->{code} == 200;\n \n foreach my $query (@{$response->{data}})\n {\n my @columns = @{$struct->{criteria}->{query}->{columns}};\n my $columns = join ',', @columns;\n \n my $data_response = GET(\"$loc\/queries\/$query->{id}?offset=0&limit=20&columns=$columns\");\n die \"Unable to load data. $response->{data}->{error_text}\" unless $response->{code} == 200;\n \n my @indices = map { my $id = $_; firstidx { $_->{id} == $id } @{$query->{columns}} } @columns;\n \n print join \",\", map { qq~\"$query->{columns}->[$_]->{name}\"~; } @indices;\n print \"\\n\";\n \n foreach my $row (@{$data_response->{data}->{data}}) {\n print join \",\", @$row;\n print \"\\n\";\n }\n }\n
Run a report to get bytes and packets for the top 20 hosts using the application WEB. Use BASIC Authentication.<\/p>\n\n
Program.cs:<\/b><\/p>\n\n using System;\n using System.Collections.Generic;\n using System.Net;\n using System.Runtime.Serialization.Json;\n using System.Text;\n using System.IO;\n using System.Net.Security;\n using System.Security.Cryptography.X509Certificates;\n using System.Linq;\n using System.Threading;\n using System.Web.Script.Serialization;\n \n namespace CascadeRestClient\n {\n public class ReportUpdate\n {\n public string status { get; set; }\n public string user_id { get; set; }\n public string name { get; set; }\n public string percent { get; set; }\n public string id { get; set; }\n public string remaining_seconds { get; set; }\n public string run_time { get; set; }\n public string saved { get; set; }\n public string template_id { get; set; }\n public string size { get; set; }\n }\n \n public class Column\n {\n public string strid { get; set; }\n public string metric { get; set; }\n public string rate { get; set; }\n public string statistic { get; set; }\n public int id { get; set; }\n public string unit { get; set; }\n public string category { get; set; }\n public string severity { get; set; }\n public string area { get; set; }\n public bool @internal { get; set; }\n public string role { get; set; }\n public string cli_srv { get; set; }\n public string type { get; set; }\n public bool available { get; set; }\n public string direction { get; set; }\n public string comparison { get; set; }\n public bool sortable { get; set; }\n public string name { get; set; }\n public string comparison_parameter { get; set; }\n public bool has_others { get; set; }\n public bool context { get; set; }\n public string name_type { get; set; }\n }\n \n public class QueryResult\n {\n public string direction { get; set; }\n public string actual_log { get; set; }\n public int actual_t0 { get; set; }\n public bool sort_desc { get; set; }\n public string area { get; set; }\n public string metric { get; set; }\n public int sort_col { get; set; }\n public string parent_id { get; set; }\n public string rate { get; set; }\n public string group_by { get; set; }\n public string role { get; set; }\n public List<Column> columns { get; set; }\n public string statistic { get; set; }\n public string type { get; set; }\n public string id { get; set; }\n public string unit { get; set; }\n public int actual_t1 { get; set; }\n }\n \n public class QueryData\n {\n public List<List<string>> data { get; set; }\n public int data_size { get; set; }\n public List<string> totals { get; set; }\n }\n \n class Program\n {\n static string BASIC_AUTH = \"admin:admin\";\n \n \/\/ callback used to validate the self-gen certificate in an SSL conversation\n private static bool ValidateRemoteCertificate(object sender, X509Certificate cert, X509Chain chain, SslPolicyErrors policyErrors)\n {\n return true;\n \/*\n X509Certificate2 certv2 = new X509Certificate2(cert);\n if (certv2.GetNameInfo(X509NameType.SimpleName,true) == \"www.riverbed.com\")\n return true;\n \n return false;\n *\/\n }\n \n static void Main(string[] args)\n {\n if (args.Length == 0 || string.IsNullOrWhiteSpace(args[0]))\n {\n Console.WriteLine(\"Usage: CascadeRestClient hostname\");\n return;\n }\n try\n {\n \/\/Code to allow run with self-signed certificates\n \/\/ validate cert by calling a function\n ServicePointManager.ServerCertificateValidationCallback += new RemoteCertificateValidationCallback(ValidateRemoteCertificate);\n \n \/\/Starting to run rest \n string rootUrl = \"https:\/\/\" + args[0];\n string requestUrl = rootUrl + \"\/api\/profiler\/1.0\/reporting\/reports.json\";\n string location;\n \n int start = (int)((DateTime.Now - new DateTime(1970, 1, 1).ToLocalTime()).TotalSeconds) - 8*60; \/\/8 minutes before in unix time\n int end = start + 5*60; \/\/3 minutes before in unix time\n \n var jsondata = new\n {\n template_id = 184,\n criteria = new\n {\n time_frame = new\n {\n start = start,\n end = end\n },\n \n traffic_expression = \"app WEB\",\n query = new\n {\n realm = \"traffic_summary\",\n group_by = \"hos\",\n sort_column = 33,\n columns = new List<int> { 6, 33, 34 }\n }\n }\n };\n \n \/\/Serialize anomymous type to json\n JavaScriptSerializer serializer = new JavaScriptSerializer();\n string postData = serializer.Serialize(jsondata);\n \n Console.WriteLine(\"Run report:\");\n Console.WriteLine(\"POST \" + requestUrl);\n Console.WriteLine(postData + Environment.NewLine);\n \n \/\/ Post to run the report\n var runReportResponse = MakeRequest<ReportUpdate>(requestUrl, WebRequestMethods.Http.Post, out location, postData);\n Console.WriteLine(\"Generated \" + location + Environment.NewLine);\n requestUrl = rootUrl + location;\n Console.WriteLine(\"Please wait\");\n while (runReportResponse.status != \"completed\")\n {\n runReportResponse = MakeRequest<ReportUpdate>(requestUrl + \".json\", WebRequestMethods.Http.Get, out location);\n Console.WriteLine(string.Format(\"Percent completed {0}, seconds remaining {1}\",runReportResponse.percent, runReportResponse.remaining_seconds));\n Thread.Sleep(1000);\n }\n Console.WriteLine(\"Completed\"+ Environment.NewLine);\n \n \/\/ Get all quesries (In this example it is only one)\n var getQueriesResponse = MakeRequest<List<QueryResult>>(requestUrl +\"\/queries.json\", WebRequestMethods.Http.Get, out location);\n string columns = jsondata.criteria.query.columns.Select(c=>c.ToString()).Aggregate((i, j) => i + \",\" + j);\n \/\/ Print the data from all queries\n foreach (var query in getQueriesResponse) {\n var qr = MakeRequest<QueryData>(requestUrl + \"\/queries\/\" + query.id + \".json?offset=0&limit=20&columns=\" + columns,\n WebRequestMethods.Http.Get, out location);\n string columnList = jsondata.criteria.query.columns.Select(c=>query.columns.Where(col => col.id == c).First().name)\n .Aggregate((l,r) => l + \",\" + r);\n Console.WriteLine(columnList);\n \n foreach (var dr in qr.data)\n {\n Console.WriteLine(dr.Aggregate((i, j) => i + ',' + j));\n }\n }\n }\n catch (Exception e)\n {\n Console.WriteLine(e.Message);\n }\n }\n \n \n private static string Base64Encode(string toEncode)\n {\n byte[] toEncodeAsBytes\n = System.Text.ASCIIEncoding.ASCII.GetBytes(toEncode);\n return System.Convert.ToBase64String(toEncodeAsBytes);\n }\n \n \/\/\/ <summary>\n \/\/\/ Make request\n \/\/\/ <\/summary>\n \/\/\/ <typeparam name=\"T\">return type<\/typeparam>\n \/\/\/ <param name=\"requestUrl\">url for request<\/param>\n \/\/\/ <param name=\"action\">Http Verb, Get, Post etc<\/param>\n \/\/\/ <param name=\"location\">location returned from response header <\/param>\n \/\/\/ <param name=\"requestData\">Data posted<\/param>\n \/\/\/ <returns><\/returns>\n private static T MakeRequest<T>(string requestUrl, string action, out string location, string requestData = null) where T : class\n {\n HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;\n request.Headers.Add(\"Authorization: Basic \" + Base64Encode(BASIC_AUTH));\n request.ContentType = \"application\/json\";\n request.Method = action;\n if (requestData == null)\n {\n request.ContentLength = 0;\n }\n else\n {\n ASCIIEncoding encoding = new ASCIIEncoding();\n byte[] byte1 = encoding.GetBytes(requestData);\n request.ContentLength = byte1.Length;\n using (Stream newStream = request.GetRequestStream())\n {\n newStream.Write(byte1, 0, byte1.Length);\n }\n }\n \n using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)\n {\n if (response.StatusCode != HttpStatusCode.OK && response.StatusCode != HttpStatusCode.Created)\n throw new Exception(String.Format(\n \"Unable to run report! StatusCode={0}, Description={1}\",\n response.StatusCode,\n response.StatusDescription));\n location = response.Headers[HttpResponseHeader.Location];\n DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(T));\n object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());\n return objResponse as T;\n }\n }\n }\n }\n\n
CascadeRestClient.csproj:<\/b><\/p>\n <?xml version=\"1.0\" encoding=\"utf-8\"?>\n <Project ToolsVersion=\"4.0\" DefaultTargets=\"Build\" xmlns=\"http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003\">\n <PropertyGroup>\n <Configuration Condition=\" '$(Configuration)' == '' \">Debug<\/Configuration>\n <Platform Condition=\" '$(Platform)' == '' \">x86<\/Platform>\n <ProductVersion>8.0.30703<\/ProductVersion>\n <SchemaVersion>2.0<\/SchemaVersion>\n <ProjectGuid>{4ED69347-523B-46AB-B259-47EF60D4F13A}<\/ProjectGuid>\n <OutputType>Exe<\/OutputType>\n <AppDesignerFolder>Properties<\/AppDesignerFolder>\n <RootNamespace>CascadeRestClient<\/RootNamespace>\n <AssemblyName>CascadeRestClient<\/AssemblyName>\n <TargetFrameworkVersion>v4.0<\/TargetFrameworkVersion>\n <TargetFrameworkProfile>\n <\/TargetFrameworkProfile>\n <FileAlignment>512<\/FileAlignment>\n <\/PropertyGroup>\n <PropertyGroup Condition=\" '$(Configuration)|$(Platform)' == 'Debug|x86' \">\n <PlatformTarget>x86<\/PlatformTarget>\n <DebugSymbols>true<\/DebugSymbols>\n <DebugType>full<\/DebugType>\n <Optimize>false<\/Optimize>\n <OutputPath>bin\\Debug\\<\/OutputPath>\n <DefineConstants>DEBUG;TRACE<\/DefineConstants>\n <ErrorReport>prompt<\/ErrorReport>\n <WarningLevel>4<\/WarningLevel>\n <\/PropertyGroup>\n <PropertyGroup Condition=\" '$(Configuration)|$(Platform)' == 'Release|x86' \">\n <PlatformTarget>x86<\/PlatformTarget>\n <DebugType>pdbonly<\/DebugType>\n <Optimize>true<\/Optimize>\n <OutputPath>bin\\Release\\<\/OutputPath>\n <DefineConstants>TRACE<\/DefineConstants>\n <ErrorReport>prompt<\/ErrorReport>\n <WarningLevel>4<\/WarningLevel>\n <\/PropertyGroup>\n <ItemGroup>\n <Reference Include=\"System\" \/>\n <Reference Include=\"System.Core\" \/>\n <Reference Include=\"System.Runtime.Serialization\" \/>\n <Reference Include=\"System.Web.Extensions\">\n <HintPath>..\\..\\..\\..\\..\\..\\..\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.0\\System.Web.Extensions.dll<\/HintPath>\n <\/Reference>\n <Reference Include=\"System.Xml.Linq\" \/>\n <Reference Include=\"System.Data.DataSetExtensions\" \/>\n <Reference Include=\"Microsoft.CSharp\" \/>\n <Reference Include=\"System.Data\" \/>\n <Reference Include=\"System.Xml\" \/>\n <\/ItemGroup>\n <ItemGroup>\n <Compile Include=\"Program.cs\" \/>\n <Compile Include=\"Properties\\AssemblyInfo.cs\" \/>\n <\/ItemGroup>\n <Import Project=\"$(MSBuildToolsPath)\\Microsoft.CSharp.targets\" \/>\n <!-- To modify your build process, add your task inside one of the targets below and uncomment it. \n Other similar extension points exist, see Microsoft.Common.targets.\n <Target Name=\"BeforeBuild\">\n <\/Target>\n <Target Name=\"AfterBuild\">\n <\/Target>\n -->\n <\/Project>\n"}