Retrieving all the locations on an AQTS server - AquaticInformatics/aquarius-sdk-net GitHub Wiki

The Provisioning API does not have a single GET /locations request which returns all locations in the system (Provisioning does have operations which work with individual locations). Similarly, the Publish API does not have a single request which retrieves everything about all locations (we have found that they perform poorly at large scale systems).

There two approaches to retrieving all the configured locations on an AQTS system.

Single request - Just retrieves basic location information

Use the Publish API to retrieve all the locations on an AQTS server.

A single GET /GetLocationDescriptionList request with all the default request properties will quickly return some summary information about each location in the system. This information includes the location name, location identifier (shown in time-series identifiers), location uniqueId, and location folder.

var locationDescriptions = _client.Publish
    .Get(new LocationDescriptionListServiceRequest())
    .LocationDescriptions;

Often this summary-level information is all that is required by clients to perform their next action.

Multiple requests - Full location information (but slower to receive)

Both the Provisioning and Publish APIs provide operations which return information about a single location, but the information tends to be applicable for different use cases.

• The Provisioning API GET /locations/{UniqueId} request returns details like descriptions, utc offset, latitude/longitude, and extended attribute values.
• The Publish API GET /GetLocationData request includes all the information from Provisioning, plus location datums, location remarks, and location attachments.

The multiple-request approaches start with the GET /GetLocationDescriptionList request and then issues batches of secondary requests, either to the Publish API or the Provisioning API, depending on the needs of the integration.

The IAquariusClient.SendBatchRequests() method can be used to request multiple responses of the same request DTO in an efficient manner.

Reasonable batch sizes are usually 100 or 200 requests per batch, not thousands or tens-of-thousands.

Retrieving all the Publish API info for a system with 5K locations in batches of 100 typically takes around 2-3 minutes.

var locationDescriptions = _client.Publish
    .Get(new LocationDescriptionListServiceRequest())
    .LocationDescriptions;

const int batchSize = 100;

var locationDetails = _client.SendBatchRequests<LocationDataServiceRequest, LocationDataServiceResponse>(
    _client.Publish,
    batchSize,
    locationDescriptions.Select(location => new LocationDataServiceRequest {LocationIdentifier = location.Identifier}));