dnas

package module
v0.0.0-...-4d11edc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2020 License: MIT Imports: 10 Imported by: 0

README

DNAS - A simple Cisco DNA Spaces Go Library

GoDoc PkgGoDev Go Report Card published

This repository is intended as a simple to use library for the Go language to interact with the Cisco DNA Spaces API.

DNA Spaces is "an industry leading indoor location & IoT-as-a Service platform" from Cisco. You can find more information on their site and also sign up for a free trial.

In order to use this library, you must have access to DNA Spaces. As of now, there is currently no sandbox for DNA Spaces and so you will either need an existing DNA Spaces tenant or you will need to sign up for a trial.

In addition, you will need Go 1.13 or above.

Installing

You can install the library in the usual way as follows:

$ go get github.com/darrenparkinson/dnas

Usage

In your code, import the library:

import "github.com/darrenparkinson/dnas"

You can then construct a new DNA Spaces client, and use the various services on the client to access different parts of the DNA Spaces API. For example:

d, _ := dnas.NewClient(apikey, region, nil)
floors, err := d.ActiveClientsService.ListFloors(context.Background())

Some API methods have optional parameters that can be passed, for example:

d, _ := dnas.NewClient(apikey, region, nil)
opt := &dnas.ClientParameters{Associated: dnas.Bool(true), DeviceType: dnas.String("CLIENT")}
count, err := d.ActiveClientsService.GetCount(context.Background(), opt)

The services of a client divide the API into logical chunks and correspond to the structure of the DNA Spaces API documentation at https://developer.cisco.com/docs/dna-spaces/#!dna-spaces-location-cloud-api

NOTE: Using the context package, one can easily pass cancelation signals and deadlines to various services of the client for handling a request. In case there is no context available, then context.Background() can be used as a starting point.

Examples

There are some examples of usage in the examples folder. To run these, git clone the repository and run them from the top level folder, e.g.:

$ go run examples/count/main.go
$ go run examples/floors/main.go
$ go run examples/clients/main.go
$ go run examples/history/main.go

Authentication

Authentication is provided by an API Key as outlined in the documentation. You are able to provide the API Key as part of initialisation using NewClient.

Region

Cisco supports two regions with DNA Spaces. You must provide the region you are using to NewClient on initialisation. You can tell which region you are using by the URL you use for DNA Spaces.

URL Region Value
dnaspaces.io io
dnaspaces.eu eu

Helper Functions

Most structs for resources use pointer values. This allows distinguishing between unset fields and those set to a zero value. Some helper functions have been provided to easily create these pointers for string, bool and int values as you saw above and here, for example:

opts := &dnas.ClientParameters{
    Associated: dnas.Bool(true),
    DeviceType: dnas.String("CLIENT"),
}

Pagination

Where pagination is provided, Cisco provides the Page and Limit query parameters as part of the request parameters for a given endpoint. Cisco specifies these as strings, so the helper function dnas.String will be necessary:

clients, err := c.ActiveClientsService.ListClients(ctx, &dnas.ClientParameters{Limit: dnas.String("1"), Page: dnas.String("1")})

By way of an example, you might use the following to work through multiple pages:

count := 1
for {
    ac, err := c.ActiveClientsService.ListClients(ctx, &dnas.ClientParameters{Associated: dnas.Bool(true), DeviceType: dnas.String("CLIENT"), Limit: dnas.String("1"), Page: dnas.String(fmt.Sprint(count))})
    if err != nil {
        log.Fatal(err)
    }
    log.Println(len(ac.Results), ac.Results[0].MacAddress, ac.Results[0].IPAddress)
    count++
    if ac.MorePage == false {
        break
    }
}

Errors

In the documentation, Cisco identifies four returned errors. These are provided as constants so that you may check against them:

Code Error Constant
400 Bad Request ErrBadRequest
401 Unauthorized Request ErrUnauthorized
403 Forbidden ErrForbidden
500 Internal Error ErrInternalError

All other errors are returned as ErrUnknown

As an example:

count, err := c.ActiveClientsService.GetCount(ctx, &dnas.ClientParameters{})
if errors.Is(err, dnas.ErrUnauthorized) {
	log.Fatal("Sorry, you're not allowed to do that.")
}

In addition, the error is wrapped in with the original response from Cisco, e.g:

2020/10/13 09:00:00 dnas: internal error: There are 155478 records in request time range, more than the limit 50000. Please reduce the time range.

Roadmap

Currently this library only implements some of the functionality. It is intended that this API will support all endpoints as they are required. Feel free to log issues if there are specific endpoints you'd like, or see Contributing.

The following oulines the available endpoints and their status in relation to implementation in this library. As you can see, still a way to go.

Map Service

Method Endpoint Status Function
POST /map Not Implemented
GET /map/hierarchy Implemented GetHierarchy
GET /map/elements/{elementId} Implemented GetMapElement
DELETE /map/elements/{elementId} Not Implemented
GET /map/images/floor/{imageName} Not Implemented

For Map Hierarchy, the InclusionExclusionRegion can have a variable number of vertices and additonal items, so this has been specified as a []map[string]interface{}. Clearly this isn't ideal, so if anyone has any better way to do this, I'd be glad to hear it. In the meantime though, you'd have to access them something like this:

fmt.Println(h.Map[0].RelationshipData.Children[0].RelationshipData.Children[0].Details.InclusionExclusionRegion[0]["type"])
fmt.Println(h.Map[0].RelationshipData.Children[0].RelationshipData.Children[0].Details.InclusionExclusionRegion[0]["vertices"])

Active Clients Service

Method Endpoint Status Function
GET /clients Implemented ListClients
GET /clients/count Implemented GetCount
GET /clients/floors Implemented ListFloors

Access Points Service

Method Endpoint Status Function
GET /accessPoints Implemented ListAccessPoints
GET /accessPoints/count Implemented GetCount

Note that GetCount accepts a status in order to return the count of access points for that given status. For this purpose, the dnas.AccessPointStatus constant can be used and is one of: All, Active, Inactive, Missing, e.g:

ac, err := c.AccessPointsService.GetCount(ctx, dnas.Inactive)
if err != nil {
    log.Fatal(err)
}
log.Printf("Inactive Access Points: %d\n", ac.Count)

Also note that ListAccessPoints only supports listing "missing" access points at this time as per the Cisco documentation

Clients History Service

Method Endpoint Status Function
GET /history Implemented GetHistory
GET /history/records/count Implemented GetCount
GET /history/clients Implemented ListClients
GET /history/clients/{deviceId} Implemented GetClient

Note that GetHistory uses the /history api endpoint which returns CSV data that is converted to a struct. Please note the restrictions on that API:

Retrieve small amount clients history to csv format. If startTime and endTime is not given, the time period is last 24 hours. If records amount is more than 50K, the user receives error response and indicate the time range needs to be reduced.

This error response will be delivered as an ErrInternalError with the supplied message from Cisco. You can check this with:

records, err := c.HistoryService.GetHistory(ctx, &dnas.HistoryParameters{StartTime: dnas.String("1602576000000"), EndTime: dnas.String("1602662400000")})
if errors.Is(err, dnas.ErrInternalError) {
	...
}

Note that you can also use Go "time" to provide the times:

fromTime := time.Now().Add(time.Hour*-2).UnixNano() / int64(time.Millisecond)
toTime := time.Now().UnixNano() / int64(time.Millisecond)
history, err := c.HistoryService.GetHistory(ctx,
    &dnas.HistoryParameters{
		StartTime: dnas.String(strconv.FormatInt(fromTime, 10)),
        EndTime:   dnas.String(strconv.FormatInt(toTime, 10)),
    })

An example of using history count:

h, _ := c.HistoryService.GetCount(ctx, &dnas.HistoryCountParameters{FloorID: dnas.String("123467890abcdef")})
log.Printf("%+v\n", h)

List client history for the last 24 hours (note: this only provides a list of mac addresses):

h, _ := c.HistoryService.ListClients(ctx, &dnas.HistoryClientsParameters{Ssid: dnas.String("YourSSID")})
log.Printf("%+v\n", h)

Notifications Service

Method Endpoint Status
GET /notifications Not Implemented
POST /notifications Not Implemented
PUT /notifications Not Implemented
GET /notifications/{subscriptionId} Not Implemented
DELETE /notifications/{subscriptionId} Not Implemented
GET /notifications/{subscriptionId}/statistics Not Implemented

Contributing

Since all endpoints would ideally be covered, contributions are always welcome. Adding new methods should be relatively straightforward.

Versioning

In general dnas follows semver for tagging releases of the package. As yet, it is still in development and has not had a tag added, but will in due course. Since it is still in development, you may expect some changes.

License

This library is distributed under the MIT license found in the LICENSE file.

Documentation

Overview

Package dnas provides a library for the Cisco DNA Spaces API

Index

Constants

View Source 
const (
	ErrBadRequest    = Err("dnas: bad request")
	ErrUnauthorized  = Err("dnas: unauthorized request")
	ErrForbidden     = Err("dnas: forbidden")
	ErrInternalError = Err("dnas: internal error")
	ErrUnknown       = Err("dnas: unexpected error occurred")
)

Error Constants Cisco documents these as the only error responses they will emit.

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

Bool is a helper routine that allocates a new bool value to store v and returns a pointer to it.

func Int 

func Int(v int) *int

Int is a helper routine that allocates a new int value to store v and returns a pointer to it.

func Int64 

func Int64(v int64) *int64

Int64 is a helper routine that allocates a new int64 value to store v and returns a pointer to it.

func String 

func String(v string) *string

String is a helper routine that allocates a new string value to store v and returns a pointer to it.

Types

type AccessPointStatus 

type AccessPointStatus string

AccessPointStatus represents the status passed to get the access point count for a given status 

const (
	All      AccessPointStatus = "all"
	Active   AccessPointStatus = "active"
	Inactive AccessPointStatus = "inactive"
	Missing  AccessPointStatus = "missing"
)

Fields for AccessPointStatus

type AccessPointsCountResponse 

type AccessPointsCountResponse struct {
	// Count of access points for a given status
	Count int64 `json:"count"`
}

AccessPointsCountResponse provides the count for the active, inactive, missing or all the access points from GetCount()

type AccessPointsResponse 

type AccessPointsResponse []struct {
	// ap mac
	ApMac string `json:"apMac,omitempty"`

	// The message count received.
	Count int64 `json:"count,omitempty"`

	// The message rate in 15 min.
	M15Rate float64 `json:"m15Rate,omitempty"`

	// The message rate in 1 min.
	M1Rate float64 `json:"m1Rate,omitempty"`

	// The message rate in 5 min.
	M5Rate float64 `json:"m5Rate,omitempty"`
}

AccessPointsResponse provides a list of missing access points returned by ListAccessPoints

type AccessPointsService 

type AccessPointsService struct {
	// contains filtered or unexported fields
}

AccessPointsService represents the Access Points API group

func (*AccessPointsService) GetCount 

func (s *AccessPointsService) GetCount(ctx context.Context, status AccessPointStatus) (AccessPointsCountResponse, error)

GetCount retrieves the count of the active, inactive, missing or all the access points. If no parameters are given, the count of all active access points is returned. Status may be missing, active, inactive or all

func (*AccessPointsService) ListAccessPoints 

func (s *AccessPointsService) ListAccessPoints(ctx context.Context) (AccessPointsResponse, error)

ListAccessPoints retrieves a list of missing access points. The only valid status is "missing" and is therefore not provided as an option.

type ActiveClientsService 

type ActiveClientsService struct {
	// contains filtered or unexported fields
}

ActiveClientsService represents the Active Clients API group

func (*ActiveClientsService) GetCount 

func (s *ActiveClientsService) GetCount(ctx context.Context, opts *ClientParameters) (ClientCountResponse, error)

GetCount retrieves the active clients count. The API supports searching by a variety of parameters. If no parameters are given, the count of all active clients are returned.

func (*ActiveClientsService) ListClients 

func (s *ActiveClientsService) ListClients(ctx context.Context, opts *ClientParameters) (LocationDeviceResults, error)

ListClients returns active clients. If no parameters are given, all active clients are returned with pagination. The default page number is 1, default number of items per page is 1000.

func (*ActiveClientsService) ListFloors 

func (s *ActiveClientsService) ListFloors(ctx context.Context) (ClientFloorsResponse, error)

ListFloors provides a list of all the floors unique identifiers which have associated clients.

type Client 

type Client struct {
	// BaseURL for DNA Spaces API.  Set to v1 and the relevant region using `dnas.New()`, or set directly.
	BaseURL string

	//HTTP Client to use for making requests, allowing the user to supply their own if required.
	HTTPClient *http.Client

	//API Key for DNA Spaces.  See [the documentation on how to generate one](https://developer.cisco.com/docs/dna-spaces/#!getting-started).
	APIKey string

	AccessPointsService  *AccessPointsService
	ActiveClientsService *ActiveClientsService
	HistoryService       *HistoryService
	NotificationsService *NotificationsService
	MapService           *MapService
}

Client represents connectivity to the DNA Spaces API

func NewClient 

func NewClient(apikey string, region string, client *http.Client) (*Client, error)

NewClient is a helper function that returns an new dnas client given a region (io or eu) and API Key. Optionally you can provide your own http client or use nil to use the default.

type ClientCountResponse 

type ClientCountResponse struct {
	Results struct {
		Total int64 `json:"total"`
	} `json:"results"`
	Querystring LocationDeviceQuery `json:"querystring,omitempty"`
	Success     bool                `json:"success"`
}

ClientCountResponse provides the count for the active devices from GetCount()

type ClientFloorsResponse 

type ClientFloorsResponse struct {
	Results []struct {
		// The total number of associated devices on this floor
		Count int64 `json:"count,omitempty"`

		// The floors unique identifier
		FloorID string `json:"floorId,omitempty"`
	} `json:"results"`

	Success bool `json:"success,omitempty"`
}

ClientFloorsResponse holds the results from ListFloors()

type ClientParameters 

type ClientParameters struct {
	// ApMacAddress The mac address of the Access Point (AP).  Available for associated clients only.
	ApMacAddress *string `url:"apMacAddress,omitempty"`

	// Associated true|false.  Whether or not a device has connected to a network.
	Associated *bool `url:"associated,omitempty"`

	// BuildingID Unique identifier for a building from the map import process
	BuildingID *string `url:"buildingID,omitempty"`

	// CampusID Unique identifier for a campus from the map import process
	CampusID *string `url:"campusID,omitempty"`

	// DeviceID The device unique identifier, for example the device macAddress.
	DeviceID *string `url:"deviceID,omitempty"`

	// DeviceType CLIENT, TAG, ROGUE_AP, ROGUE_CLIENT or INTERFERER
	DeviceType *string `url:"deviceType,omitempty"`

	// FloorID Unique identifier for a floor from the map import process
	FloorID *string `url:"floorID,omitempty"`

	// Format Indicate if using geojson, value is "geojson" if so.
	Format *string `url:"format,omitempty"`

	// IPAddress IP address of the connected device.  Available for associated clients only.
	IPAddress *string `url:"iPAddress,omitempty"`

	// Limit The maximum number of items that may be returned for a single request. For active client, the default value is 1000; For client location history, the default value is 2000. Sorry it's a string, but that's what we got!
	Limit *string `url:"limit,omitempty"`

	// Manufacturer Manufacturer of the device.
	Manufacturer *string `url:"manufacturer,omitempty"`

	// MapElementID Indicate the map element unique identifier.
	MapElementID *string `url:"mapElementID,omitempty"`

	// MapElementLevel Indicate the map element level, valid value is "campus", "building" and "floor".
	MapElementLevel *string `url:"mapElementLevel,omitempty"`

	// Page The page number requests for. Start from 1 and default value is 1. Sorry it's a string, but that's what we got!
	Page *string `url:"page,omitempty"`

	// RogueApClients When using deviceType=ROGUE_AP, this will return rogue APs that have connected clients.
	RogueApClients *bool `url:"rogueApClients,omitempty"`

	// Ssid Wifi service set identifier (SSID).  Available for associated clients only.
	Ssid *string `url:"ssid,omitempty"`

	// Username The user name of the connected user. Available for associated clients only.
	Username *string `url:"username,omitempty"`
}

ClientParameters represent the options for ListClients and GetCount

type Err 

type Err string

Err implements the error interface so we can have constant errors.

func (Err) Error 

func (e Err) Error() string

type HistoryClientsDeviceParameters 

type HistoryClientsDeviceParameters struct {
	// ApMacAddress The mac address of the Access Point (AP).  Available for associated clients only.
	ApMacAddress *string `url:"apMacAddress,omitempty"`

	// BuildingID Unique identifier for a building from the map import process
	BuildingID *string `url:"buildingId,omitempty"`

	// CampusID Unique identifier for a campus from the map import process
	CampusID *string `url:"campusId,omitempty"`

	// The end time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	EndTime *string `url:"endTime,omitempty"`

	// FloorID Unique identifier for a floor from the map import process
	FloorID *string `url:"floorId,omitempty"`

	// Format Indicate if using geojson, value is "geojson" if so.
	Format *string `url:"format,omitempty"`

	// The radius, it should go with x and y.
	Radius *float64 `url:"radius,omitempty"`

	// Ssid Wifi service set identifier (SSID).  Available for associated clients only.
	Ssid *string `url:"ssid,omitempty"`

	// The start time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	StartTime *string `url:"startTime,omitempty"`

	// The time zone the request is initiated, default is time zone 0(UTC time).
	TimeZone *int64 `url:"timeZone,omitempty"`

	// Username The user name of the connected user. Available for associated clients only.
	Username *string `url:"username,omitempty"`

	// The x coordinate of the radius center.
	X *float64 `url:"x,omitempty"`

	// The y coordinate of the radius center.
	Y *float64 `url:"y,omitempty"`
}

HistoryClientsDeviceParameters represent the options for GetClient()

type HistoryClientsDeviceResponse 

type HistoryClientsDeviceResponse []struct {
	FloorID         string    `json:"floorId"`
	SourceTimestamp int64     `json:"sourceTimestamp"`
	Coordinates     []float64 `json:"coordinates"`
	Associated      bool      `json:"associated"`
	AssociatedApmac string    `json:"associatedApmac"`
}

HistoryClientsDeviceResponse contains the response from GetClient()

type HistoryClientsParameters 

type HistoryClientsParameters struct {
	// ApMacAddress The mac address of the Access Point (AP).  Available for associated clients only.
	ApMacAddress *string `url:"apMacAddress,omitempty"`

	// BuildingID Unique identifier for a building from the map import process
	BuildingID *string `url:"buildingId,omitempty"`

	// CampusID Unique identifier for a campus from the map import process
	CampusID *string `url:"campusId,omitempty"`

	// The end time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	EndTime *string `url:"endTime,omitempty"`

	// FloorID Unique identifier for a floor from the map import process
	FloorID *string `url:"floorId,omitempty"`

	// The radius, it should go with x and y.
	Radius *float64 `url:"radius,omitempty"`

	// Ssid Wifi service set identifier (SSID).  Available for associated clients only.
	Ssid *string `url:"ssid,omitempty"`

	// The start time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	StartTime *string `url:"startTime,omitempty"`

	// The time zone the request is initiated, default is time zone 0(UTC time).
	TimeZone *int64 `url:"timeZone,omitempty"`

	// The x coordinate of the radius center.
	X *float64 `url:"x,omitempty"`

	// The y coordinate of the radius center.
	Y *float64 `url:"y,omitempty"`
}

HistoryClientsParameters represent the options for GetClientsHistory()

type HistoryClientsResponse 

type HistoryClientsResponse []struct {
	MacAddress string `json:"macAddress,omitempty"`
}

HistoryClientsResponse contains the response from ListClients which consists of an array of Mac Addresses

type HistoryCountParameters 

type HistoryCountParameters struct {
	// BuildingID Unique identifier for a building from the map import process
	BuildingID *string `url:"buildingId,omitempty"`

	// CampusID Unique identifier for a campus from the map import process
	CampusID *string `url:"campusId,omitempty"`

	// The end time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	EndTime *string `url:"endTime,omitempty"`

	// FloorID Unique identifier for a floor from the map import process
	FloorID *string `url:"floorId,omitempty"`

	// The start time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	StartTime *string `url:"startTime,omitempty"`

	// The time zone the request is initiated, default is time zone 0(UTC time).
	TimeZone *int64 `url:"timeZone,omitempty"`
}

HistoryCountParameters represent the options for GetCount()

type HistoryCountResponse 

type HistoryCountResponse struct {
	// Count of clients given filter
	Count string `json:"count"`
}

HistoryCountResponse provides the count for the active, inactive, missing or all the access points from GetCount()

type HistoryItem 

type HistoryItem struct {
	TenantID                string `json:"tenantid"`
	MacAddress              string `json:"macaddress"`
	DeviceType              string `json:"devicetype"`
	CampusID                string `json:"campusid"`
	BuildingID              string `json:"buildingid"`
	FloorID                 string `json:"floorid"`
	FloorHierarchy          string `json:"floorhierarchy"`
	CoordinateX             string `json:"coordinatex"`
	CoordinateY             string `json:"coordinatey"`
	SourceTimestamp         string `json:"sourcetimestamp"`
	MaxDetectedApMac        string `json:"maxdetectedapmac"`
	MaxDetectedBand         string `json:"maxdetectedband"`
	DetectingControllers    string `json:"detectingcontrollers"`
	FirstActiveAt           string `json:"firstactiveat"`
	LocatedSinceActiveCount string `json:"locatedsinceactivecount"`
	ChangedOn               string `json:"changedon"`
	Manufacturer            string `json:"manufacturer"`
	Associated              string `json:"associated"`
	MaxDetectedRssi         string `json:"maxdetectedrssi"`
	Ssid                    string `json:"ssid"`
	Username                string `json:"username"`
	AssociatedApMac         string `json:"associatedapmac"`
	AssociatedApRssi        string `json:"associatedaprssi"`
	MaxDetectedSlot         string `json:"maxdetectedslot"`
	IPAddress               string `json:"ipaddress"`
	StaticDevice            string `json:"staticdevic"`
	RecordType              string `json:"recordtype"`
	ComputeType             string `json:"computetype"`
	Source                  string `json:"source"`
	MacHashed               string `json:"machashed"`
}

HistoryItem represents a single item in the HistoryResponse from the CSV output of GetHistory() Note that all results are returned as string since they're coming from CSV. This provides flexibility for conversion.

type HistoryParameters 

type HistoryParameters struct {
	// ApMacAddress The mac address of the Access Point (AP).  Available for associated clients only.
	ApMacAddress *string `url:"apMacAddress,omitempty"`

	// BuildingID Unique identifier for a building from the map import process
	BuildingID *string `url:"buildingId,omitempty"`

	// CampusID Unique identifier for a campus from the map import process
	CampusID *string `url:"campusId,omitempty"`

	// DeviceID The device unique identifier, for example the device macAddress.
	DeviceID *string `url:"deviceId,omitempty"`

	// The end time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	EndTime *string `url:"endTime,omitempty"`

	// FloorID Unique identifier for a floor from the map import process
	FloorID *string `url:"floorId,omitempty"`

	// Format Indicate if using geojson, value is "geojson" if so.
	Format *string `url:"format,omitempty"`

	// Ssid Wifi service set identifier (SSID).  Available for associated clients only.
	Ssid *string `url:"ssid,omitempty"`

	// The start time(in epoc time format based on milisecond) of the range of the time zone the request is initiated.
	StartTime *string `url:"startTime,omitempty"`

	// The time zone the request is initiated, default is time zone 0(UTC time).
	TimeZone *int64 `url:"timeZone,omitempty"`

	// Username The user name of the connected user. Available for associated clients only.
	Username *string `url:"username,omitempty"`
}

HistoryParameters represent the options for GetHistory()

type HistoryResponse 

type HistoryResponse struct {
	Results []HistoryItem `json:"results"`
}

HistoryResponse represents the CSV response from GetHistory()

type HistoryService 

type HistoryService struct {
	// contains filtered or unexported fields
}

HistoryService represents the Clients History API group

func (*HistoryService) GetClient 

func (s *HistoryService) GetClient(ctx context.Context, deviceID string, opts *HistoryClientsParameters) (HistoryClientsDeviceResponse, error)

GetClient retrieves the given client history details by using filters. Pagination is provided. The startTime and endTime time peroid is at most 1 day, if not being given, then the last 1 day's history of the client is returned. Default page is 1, 20k items per page (Note - 20k is requested by UI, pending to adjust to smaller page size based on test result).

func (*HistoryService) GetCount 

func (s *HistoryService) GetCount(ctx context.Context, opts *HistoryCountParameters) (HistoryCountResponse, error)

GetCount retrieves the clients history records amount in given time range. If startTime and endTime is not being given, the time range is last 24 hours.

func (*HistoryService) GetHistory 

func (s *HistoryService) GetHistory(ctx context.Context, opts *HistoryParameters) (HistoryResponse, error)

GetHistory retrieves a small amount of clients history to csv format. If startTime and endTime is not given, the time period is last 24 hours. If records amount is more than 50K, the user receives error response and indicates the time range needs to be reduced.

func (*HistoryService) ListClients 

func (s *HistoryService) ListClients(ctx context.Context, opts *HistoryClientsParameters) (HistoryClientsResponse, error)

ListClients retrieves the clients mac address list by using filters. If startTime and endTime are not given, all the clients' mac addresses in the last 1 day are being returned.

type LocationDevice 

type LocationDevice struct {
	// The list of APs.
	ApList []struct {
		ApMacAddress string   `json:"apMacAddress,omitempty"`
		Bands        []string `json:"bands,omitempty"`
		Rssi         int64    `json:"rssi,omitempty"`
	} `json:"apList"`

	// AP Mac Address
	ApMacAddress string `json:"apMacAddress,omitempty"`

	// true|false.  Whether or not a device has connected to a network.
	Associated bool `json:"associated,omitempty"`

	// Band
	Band string `json:"band,omitempty"`

	// unique identifier for a building from the map import process
	BuildingID string `json:"buildingId,omitempty"`

	// unique identifier for a campus from the map import process
	CampusID string `json:"campusId,omitempty"`

	// The UTC time the device state changed.
	// ChangedOn string `json:"changedOn,omitempty"`
	ChangedOn int64 `json:"changedOn,omitempty"`

	// The compute type, possible values are RSSI and AOA.
	ComputeType string `json:"computeType,omitempty"`

	// confidence factor
	ConfidenceFactor int64 `json:"confidenceFactor,omitempty"`

	// The controller IP.
	// Format: ipv4
	Controller string `json:"controller,omitempty"`

	// x and y coordinates of a device.
	Coordinates []float64 `json:"coordinates"`

	// CLIENT, TAG, ROGUE_AP, or ROGUE_CLIENT
	DeviceType string `json:"deviceType,omitempty"`

	// The first time of the device location being detected.
	FirstLocatedAt string `json:"firstLocatedAt,omitempty"`

	// unique identifier for a floor from the map import process\
	FloorID string `json:"floorId,omitempty"`

	// The Geo coordinates of a device.
	GeoCoordinates []float64 `json:"geoCoordinates"`

	// Site hierarchy
	Hierarchy string `json:"hierarchy,omitempty"`

	// IP Address
	IPAddress string `json:"ipAddress,omitempty"`

	// Is MAC Hashed
	IsMacHashed bool `json:"isMacHashed,omitempty"`

	// The last time of the location being detected.
	// Format: date-time
	LastLocationAt string `json:"lastLocationAt,omitempty"`

	// macaddress of the device.
	MacAddress string `json:"macAddress,omitempty"`

	// Manufacturer of the device.
	Manufacturer string `json:"manufacturer,omitempty"`

	// max detected rssi
	MaxDetectedRssi struct {
		ApMacAddress string `json:"apMacAddress,omitempty"`
		Band         string `json:"band,omitempty"`
		Slot         int64  `json:"slot,omitempty"`
		Rssi         int64  `json:"rssi,omitempty"`
		AntennaIndex int64  `json:"antennaIndex,omitempty"`
		LastHeard    int64  `json:"lastHeard,omitempty"`
	} `json:"maxDetectedRssi,omitempty"`

	// The number of detecting APs.
	NumDetectingAps int64 `json:"numDetectingAps,omitempty"`

	// The raw x and y coordinates of a device.
	RawCoordinates []float64 `json:"rawCoordinates"`

	// Source
	Source string `json:"source,omitempty"`

	// SSID
	SSID string `json:"ssid,omitempty"`

	// the tenant unique identifier
	TenantID string `json:"tenantId,omitempty"`

	// Username
	Username string `json:"userName,omitempty"`
}

LocationDevice represents device location data for a single device

type LocationDeviceQuery 

type LocationDeviceQuery struct {
	ApMacAddress    string `url:"apMacAddress,omitempty"`
	Associated      string `url:"associated,omitempty"`
	BuildingID      string `url:"buildingID,omitempty"`
	CampusID        string `url:"campusID,omitempty"`
	DeviceID        string `url:"deviceID,omitempty"`
	DeviceType      string `url:"deviceType,omitempty"`
	FloorID         string `url:"floorID,omitempty"`
	Format          string `url:"format,omitempty"`
	IPAddress       string `url:"iPAddress,omitempty"`
	Limit           string `url:"limit,omitempty"`
	Manufacturer    string `url:"manufacturer,omitempty"`
	MapElementID    string `url:"mapElementID,omitempty"`
	MapElementLevel string `url:"mapElementLevel,omitempty"`
	Page            string `url:"page,omitempty"`
	RogueApClients  string `url:"rogueApClients,omitempty"`
	Ssid            string `url:"ssid,omitempty"`
	Username        string `url:"username,omitempty"`
}

LocationDeviceQuery represents the QueryString values used. It's the same as ClientParameters, but the types are different, typically string for everything. Empty strings are returned for values that are missing.

type LocationDeviceResults 

type LocationDeviceResults struct {
	// True to inidcate there is next page, false otherwise
	MorePage bool `json:"morePage,omitempty"`

	Querystring LocationDeviceQuery `json:"querystring,omitempty"`

	// The list of device location data, include associated AP devices location data as the first item
	// and each device's mac address and coordinates as following items in the list.
	Results []LocationDevice `json:"results"`

	// True in a successful response.
	Success bool `json:"success,omitempty"`
}

LocationDeviceResults provides device location data

type MapElementResponse 

type MapElementResponse struct {
	Success bool    `json:"success,omitempty"`
	Map     MapItem `json:"map"`
}

MapElementResponse is the top level response for GetMapElement

type MapHierarchyResponse 

type MapHierarchyResponse struct {
	// Top level item for Map Items
	Map []MapItem `json:"map"`
}

MapHierarchyResponse is the top level response for GetHierarchy

type MapInclusionExclusionRegionItem 

type MapInclusionExclusionRegionItem struct {

	// Indicate how to handle the vertices on map.
	Type string `json:"type,omitempty"`

	// The number of vertices.
	Vertices int64 `json:"vertices,omitempty"`
}

MapInclusionExclusionRegionItem is supposed to represent an InclusionExclusionRegionItem. This is not currently used, but you could use it to extract InclusionExclusionRegionItems to.

type MapItem 

type MapItem struct {
	Address string `json:"address,omitempty"`

	// The date and time of the level being created.
	// Format: date-time
	CreatedOn string `json:"createdOn,omitempty"`

	// details
	Details MapItemDetails `json:"details,omitempty"`

	// Campus unique identifier.
	ID string `json:"id,omitempty"`

	// imported Id
	ImportedID string `json:"importedId,omitempty"`

	// The level in the hireachy.
	Level string `json:"level,omitempty"`

	// Campus name.
	Name string `json:"name,omitempty"`

	// relationship data
	RelationshipData MapItemRelationshipData `json:"relationshipData,omitempty"`

	SourceType string `json:"sourceType,omitempty"`
}

MapItem represents an individual map element

type MapItemCorner 

type MapItemCorner struct {
	// x
	X float64 `json:"x,omitempty"`
	// y
	Y float64 `json:"y,omitempty"`
	// z
	Z float64 `json:"z,omitempty"`
	// Unit
	Unit string `json:"unit,omitempty"`
}

MapItemCorner is supposed to represent part of an InclusionExclusionRegionItem. This is not currently used, but you could use it to extract InclusionExclusionRegionItems to.

type MapItemDetails 

type MapItemDetails struct {
	CalibrationModelRef string `json:"calibrationModelRef,omitempty"`

	FloorNumber int64 `json:"floorNumber,omitempty"`

	GpsMarkers []string `json:"GpsMarkers,omitempty"`

	// The level's map height.
	Height float64 `json:"height,omitempty"`

	// image
	Image MapResImage `json:"image,omitempty"`

	InclusionExclusionRegion []map[string]interface{} `json:"inclusionExclusionRegion,omitempty"`

	Latitude float64 `json:"latitude,omitempty"`

	// The level's map length.
	Length float64 `json:"length,omitempty"`

	Longitude float64 `json:"longitude,omitempty"`

	Obstacles []string `json:"obstacles,omitempty"`

	OffsetX float64 `json:"offsetX,omitempty"`

	OffsetY float64 `json:"offsetY,omitempty"`

	// The level's map width.
	Width float64 `json:"width,omitempty"`
}

MapItemDetails contains additional detail for a MapItem

type MapItemRelationshipData 

type MapItemRelationshipData struct {

	// ancestor ids
	AncestorIds []string `json:"ancestorIds"`

	// ancestors
	Ancestors []string `json:"ancestors"`

	// children
	Children []MapItem `json:"children"`

	// parent
	Parent interface{} `json:"parent,omitempty"`
}

MapItemRelationshipData contains the relationships with other map items

type MapResImage 

type MapResImage struct {
	Cksum string `json:"cksum,omitempty"`

	// color depth
	ColorDepth int64 `json:"colorDepth,omitempty"`

	// height
	Height int64 `json:"height,omitempty"`

	// Indicate if the source image is compressed(true) or not(false).
	ImageCompressed bool `json:"imageCompressed,omitempty"`

	// The image for the map.
	ImageName string `json:"imageName,omitempty"`

	// max resolution
	MaxResolution int64 `json:"maxResolution,omitempty"`

	// size
	Size int64 `json:"size,omitempty"`

	// source file
	SourceFile string `json:"sourceFile,omitempty"`

	// Indicate if the source image is valid(true) or not(false).
	ValidImageSupplied bool `json:"validImageSupplied,omitempty"`

	// width
	Width int64 `json:"width,omitempty"`

	// zoom level
	ZoomLevel int64 `json:"zoomLevel,omitempty"`
}

MapResImage represents a map item image.

type MapService 

type MapService struct {
	// contains filtered or unexported fields
}

MapService represents the Map API group

func (*MapService) GetHierarchy 

func (s *MapService) GetHierarchy(ctx context.Context) (MapHierarchyResponse, error)

GetHierarchy returns the Map hierarchy and includes campus, buildings and floors.

func (*MapService) GetMapElement 

func (s *MapService) GetMapElement(ctx context.Context, id string) (MapElementResponse, error)

GetMapElement retrieves a map element using it's identifier. The elements are campus, buildings and floors.

type NotificationsService 

type NotificationsService struct {
	// contains filtered or unexported fields
}

NotificationsService represents the Notifications API group

Source Files

View all Source files

Directories

Path Synopsis
examples
clients
Example: clients/main.go This example shows how to initialise the library and retrieve a list of devices.
 Example: clients/main.go This example shows how to initialise the library and retrieve a list of devices.
count
Example: count/main.go This example shows how to initialise the library and retrieve a count of devices.
 Example: count/main.go This example shows how to initialise the library and retrieve a count of devices.
floors
Example: floors/main.go This example shows how to initialise the library and retrieve a list of floors.
 Example: floors/main.go This example shows how to initialise the library and retrieve a list of floors.
history
Example: history/main.go This example shows how to initialise the library and retrieve a history of devices over the last two hours.
 Example: history/main.go This example shows how to initialise the library and retrieve a history of devices over the last two hours.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.