Skip to content

Commit de35416

Browse files
kan-fukan-fu
committed
doc: update API_Guide for data product delivery (cancel, restart, status), and get sensor category codes
1 parent f1af6fe commit de35416

File tree

3 files changed

+159
-8
lines changed

3 files changed

+159
-8
lines changed

‎doc/source/API_Guide.md

+34-7
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,17 @@ Check [here](https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms) for mo
1212

1313
The [ONC](#onc.onc.ONC) class provides a wrapper for Oceans 3.0 API requests.
1414
All the client library's functionality is provided as methods of this class.
15+
Each [Oceans 3.0 public API](https://data.oceannetworks.ca/OpenAPI) has a corresponding public method in this class.
16+
In addition, the ONC class provides some useful helper methods that involve multiple APIs to simplify the workflow.
1517

1618
Create an ONC object to access this library's functionalities.
1719

20+
```python
21+
from onc import ONC
22+
23+
onc = ONC("YOUR_TOKEN_HERE")
24+
```
25+
1826
## Discovery methods
1927

2028
Discovery methods can be used to search for available locations, deployments, device categories, devices, properties, and data products.
@@ -65,12 +73,20 @@ If the data product requested doesn't exist in our archive, it will be generated
6573

6674
:::
6775

68-
| Method | Description | API Endpoint |
69-
| :-----------------------------------------------------: | :--------------------------------------------: | :------------------------------------------------------------------------------------------------------: |
70-
| [orderDataProduct](#onc.onc.ONC.orderDataProduct) | Request, run, and download <br> a data product | |
71-
| [requestDataProduct](#onc.onc.ONC.requestDataProduct) | Request a data product | [/dataProductDelivery/request](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/request) |
72-
| [runDataProduct](#onc.onc.ONC.runDataProduct) | Run a requested data product | [/dataProductDelivery/run](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/run) |
73-
| [downloadDataProduct](#onc.onc.ONC.downloadDataProduct) | Download a data product | [/dataProductDelivery/download](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/download) |
76+
| Method | Description | API Endpoint |
77+
| :-----------------------------------------------------: | :-------------------------------------------: | :------------------------------------------------------------------------------------------------------: |
78+
| [requestDataProduct](#onc.onc.ONC.requestDataProduct) | Request a data product | [/dataProductDelivery/request](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/request) |
79+
| [checkDataProduct](#onc.onc.ONC.checkDataProduct) | Check status of a <br> requested data product | [/dataProductDelivery/status](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/status) |
80+
| [runDataProduct](#onc.onc.ONC.runDataProduct) | Run a requested data product | [/dataProductDelivery/run](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/run) |
81+
| [cancelDataProduct](#onc.onc.ONC.cancelDataProduct) | Cancel a running data product | [/dataProductDelivery/cancel](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/cancel) |
82+
| [restartDataProduct](#onc.onc.ONC.restartDataProduct) | Restart a cancelled data product | [/dataProductDelivery/restart](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/restart) |
83+
| [downloadDataProduct](#onc.onc.ONC.downloadDataProduct) | Download a data product | [/dataProductDelivery/download](https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/download) |
84+
85+
Helper methods are listed below.
86+
87+
| Method | Description |
88+
| :-----------------------------------------------: | :---------------------------------------: |
89+
| [orderDataProduct](#onc.onc.ONC.orderDataProduct) | Request, run, and download a data product |
7490

7591
## Near real-time data access methods
7692

@@ -103,6 +119,12 @@ Use the _allPages_ parameter to automatically download all pages required for yo
103119
| [getDirectRawByLocation](#onc.onc.ONC.getDirectRawByLocation) | Returns raw data <br> from a specific location and device category | [/rawdata/location](https://data.oceannetworks.ca/OpenAPI#get-/rawdata/location) |
104120
| [getDirectRawByDevice](#onc.onc.ONC.getDirectRawByDevice) | Returns raw data from a specific device | [/rawdata/device](https://data.oceannetworks.ca/OpenAPI#get-/rawdata/device) |
105121

122+
Helper methods are listed below.
123+
124+
| Method | Description |
125+
| :-----------------------------------------------------------: | :-----------------------------------------------------------------------------------: |
126+
| [getSensorCategoryCodes](#onc.onc.ONC.getSensorCategoryCodes) | Returns a list of sensor category codes <br> prior to querying the scalardata service |
127+
106128
## Archive file download methods
107129

108130
These methods allow users to directly download previously generated data product files from our archive.
@@ -131,4 +153,9 @@ Due to security regulations, some very recent files (e.g. hydrophone.wav files i
131153
| [getListByLocation](#onc.onc.ONC.getListByLocation) | Returns a list of available archive files <br> from a specific location and device category | [/archivefile/location](https://data.oceannetworks.ca/OpenAPI#get-/archivefile/location) |
132154
| [getListByDevice](#onc.onc.ONC.getListByDevice) | Returns a list of available archive files <br> from a specific device | [/archivefile/device](https://data.oceannetworks.ca/OpenAPI#get-/archivefile/device) |
133155
| [getFile](#onc.onc.ONC.getFile) | Download an archive file | [/archivefile/download](https://data.oceannetworks.ca/OpenAPI#get-/archivefile/download) |
134-
| [getDirectFiles](#onc.onc.ONC.getDirectFiles) | Download a list of archived files <br> that match the filters provided | |
156+
157+
Helper methods are listed below.
158+
159+
| Method | Description |
160+
| :-------------------------------------------: | :---------------------------------------------------------------: |
161+
| [getDirectFiles](#onc.onc.ONC.getDirectFiles) | Download a list of archived files that match the filters provided |

‎src/onc/modules/_OncDelivery.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ def runDataProduct(self, dpRequestId: int, waitComplete: bool):
9191
status = ""
9292
log = _PollLog(True)
9393
print(
94-
f"To cancel the running data product, run 'onc.cancelDataProduct({dpRequestId})'"
94+
f"To cancel the running data product, run 'onc.cancelDataProduct({dpRequestId})'" # noqa: E501
9595
)
9696
url = f"{self._config('baseUrl')}api/dataProductDelivery"
9797
runResult = {"runIds": [], "fileCount": 0, "runTime": 0, "requestCount": 0}

‎src/onc/onc.py

+124
Original file line numberDiff line numberDiff line change
@@ -783,15 +783,77 @@ def requestDataProduct(self, filters: dict):
783783
return self.delivery.requestDataProduct(filters)
784784

785785
def checkDataProduct(self, dpRequestId: int):
786+
"""
787+
Check status of a requested data product.
788+
789+
The API endpoint is ``/dataProductDelivery/status``.
790+
791+
See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/status
792+
for usage.
793+
794+
Parameters
795+
----------
796+
dpRequestId : int
797+
A dpRequestId returned from calling ``requestDataProduct``.
798+
799+
Returns
800+
-------
801+
dict
802+
API response.
803+
"""
786804
return self.delivery.checkDataProduct(dpRequestId)
787805

788806
def runDataProduct(self, dpRequestId: int, waitComplete: bool = True):
789807
return self.delivery.runDataProduct(dpRequestId, waitComplete)
790808

791809
def cancelDataProduct(self, dpRequestId: int):
810+
"""
811+
Cancel a running data product.
812+
813+
The API endpoint is ``/dataProductDelivery/cancel``.
814+
815+
See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/cancel
816+
for usage.
817+
818+
Parameters
819+
----------
820+
dpRequestId : int
821+
A dpRequestId returned from calling ``requestDataProduct``.
822+
823+
Returns
824+
-------
825+
list of dict
826+
API response. Each status returned in the list is a dict with the following structure.
827+
828+
- dpRunId: int
829+
- status: str
830+
""" # noqa: E501
792831
return self.delivery.cancelDataProduct(dpRequestId)
793832

794833
def restartDataProduct(self, dpRequestId: int, waitComplete: bool = True):
834+
"""
835+
Restart a cancelled data product.
836+
837+
The API endpoint is ``/dataProductDelivery/restart``.
838+
839+
Restart searches cancelled by calling the ``cancelDataProduct`` method.
840+
841+
See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/restart
842+
for usage.
843+
844+
Parameters
845+
----------
846+
dpRequestId : int
847+
A dpRequestId returned from calling ``requestDataProduct``.
848+
849+
Returns
850+
-------
851+
list of dict
852+
API response. Each status returned in the list is a dict with the following structure.
853+
854+
- dpRunId: int
855+
- status: str
856+
""" # noqa: E501
795857
return self.delivery.restartDataProduct(dpRequestId, waitComplete)
796858

797859
def downloadDataProduct(
@@ -825,6 +887,68 @@ def getDirectRawByDevice(self, filters: dict = None, allPages: bool = False):
825887
return self.realTime.getDirectRawByDevice(filters, allPages)
826888

827889
def getSensorCategoryCodes(self, filters: dict):
890+
"""
891+
Return a list of sensor category codes.
892+
893+
A helper method for narrowing down the sensorCategoryCodes that are of interest
894+
prior to the use of the scalardata service.
895+
896+
Parameters
897+
----------
898+
filters : dict
899+
Query string parameters in the API request.
900+
Use the same filters for calling ``getDirectByLocation`` or ``getDirectByDevice``.
901+
902+
Returns
903+
-------
904+
list of dict
905+
API response. Each sensor category code returned in the list is a dict with the following structure.
906+
907+
- outputFormat: str
908+
- sensorCategoryCode: str
909+
- sensorCode: str
910+
- sensorName: str
911+
- unitOfMeasure: str
912+
913+
Examples
914+
--------
915+
>>> params = {
916+
... "locationCode": "NCBC",
917+
... "deviceCategoryCode": "BPR",
918+
... "propertyCode": "seawatertemperature,totalpressure",
919+
... } # doctest: +SKIP
920+
>>> onc.getSensorCategoryCodes(params) # doctest: +SKIP
921+
[
922+
{
923+
"outputFormat": "array",
924+
"sensorCategoryCode": "pressure",
925+
"sensorCode": "Pressure",
926+
"sensorName": "Seafloor Pressure",
927+
"unitOfMeasure": "decibar",
928+
},
929+
{
930+
"outputFormat": "array",
931+
"sensorCategoryCode": "temperature",
932+
"sensorCode": "Temperature",
933+
"sensorName": "Housing Temperature",
934+
"unitOfMeasure": "C",
935+
},
936+
{
937+
"outputFormat": "array",
938+
"sensorCategoryCode": "temperature1",
939+
"sensorCode": "temperature1",
940+
"sensorName": "Temperature",
941+
"unitOfMeasure": "C",
942+
},
943+
{
944+
"outputFormat": "array",
945+
"sensorCategoryCode": "temperature2",
946+
"sensorCode": "temperature2",
947+
"sensorName": "P-Sensor Temperature",
948+
"unitOfMeasure": "C",
949+
},
950+
]
951+
""" # noqa: E501
828952
return self.realTime.getSensorCategoryCodes(filters)
829953

830954
# Archive file methods

0 commit comments

Comments
 (0)