You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Disclaimer

This page is originally from a git repository where its content can be managed and presented in a more dynamical way. This is a snapshot as of today ( ). There will be no frequent updates or alike. New content comes with a new documentation platform – some day!

Use Case 1: user and items thing

Use case 1.1: Which item is associated with which user?

input:

  • user email or
  • user firstname and lastname

Per API: Search for all items of contact x, i) by (system) email address, ii) by contact names.

  1. get /sensors/device/getItemsOfContact/{contactEmail} OR
  2. get /sensors/contacts/getContactsByName/{firstName}/{lastName} --> email address will be output, then go on with step 1

Use case 1.2: Which items have the user x with a certain role?

input:

  • input from 1.1
  • user role
  1. von use case 1.1
    1. get /sensors/device/getItemsOfContact/{contactEmail} OR
    2. get /sensors/contacts/getContactsByName/{firstName}/{lastName} --> email address as output then go to step 1
  2. get /sensors/contacts/getAllContactRoles --> pick out which ID is related to which role type (e.g. Data scientist="id": 29]
  3. filter (role) ID-based
    • PI==True --> put to list
    • PI==False --> go on
    • ...

Use Case 2: write a certain event (e.g. info about calibration) to item xy

  • [ ] PY
  • [ ] R

input:

  • item URN
  • user credentials
  • event infos

  1. get /sensors/item/getItemByUrn/{urn} --> filter for "id"

  2. create a usable token post [input] /sensors/contacts/login (input is a json holding username and password) --> response --> save token

  3. get /sensors/events/getAllEventTypes --> filter for event type id for input in #5.5

  4. create json for other input for #5

  5. put /sensors/events/putEvent/{deviceID} + INPUT {

    1. "startDate": "2020-01-01T14:10:00",
    2. "endDate": "2020-01-01T14:10:00",
    3. "label": "Test",
    4. "description": "string",
    5. "eventType": 0,
    6. "longitude": 0,
    7. "latitude": 0,
    8. "elevationInMeter": 0,
    9. all children <- not part of the json body
    10. create version <- not part of the json body [TRUE/FALSE]

}

Use Case 3: create a list of all items of a platform that measure parameter xyz

Precondition: only valid for current configuration. If the item was object to modifications (mounts) the results may differ.

input:

  • top most item
  • paramter type (e.g. salinity)
  1. get https://sensor.awi.de/rest/sensors/item/getChildrenOfItem/{itemID}
  2. get https://sensor.awi.de/rest/sensors/sensorOutputs/getAllSensorOutputTypes -> filter by i.e. regex "temp" (water temperature, technical temperature, etc. ...)
  3. get https://sensor.awi.de/rest/sensors/sensorOutputs/getDeviceSensorOutputs/{itemID}

TODO: solve outputType is matching exactly but the response is not unique.... doh!

Use Case 4: adding/removing/modifying a parameter to item xyz

input:

  • parental item ID
  • some user added info, such as name and comment
  • parameter id (derived from dict)
  • unit id (derived from dict)
  • (own) user credentials
  1. token
  2. get https://sandbox.sensor.awi.de/rest/sensors/sensorOutputs/getAllSensorOutputTypes -> filter
  3. get https://sandbox.sensor.awi.de/rest/sensors/unitsOfMeasurement/getAllUnitsOfMeasurement -> filter
  4. (if necessary) get https://sandbox.sensor.awi.de/rest/sensors/item/getItemByUrn/{URN} -> derive ID

add

  1. put https://sandbox.sensor.awi.de/rest/sensors/sensorOutputs/putSensorOutput/{itemID} + INPUT {

    1. "name": "this is the long name, it can have blanks",
    2. "type_vocableID": 0,
    3. "itemID": 0,
    4. "unitOfMeasureID": 0,
    5. "shortName": "shortname_of_the_item",
    6. "comment": "optional comment"

}

modify

Possibly a look in the available output types/units is useful in advance, if these things shall be modified.

  1. get sensorOutputs/getDeviceSensorOutputs/{itemID} -> use reply to fill new json

  2. put sensorOutputs/modifySensorOutput/{outputID}/{itemID} + INPUT {

    1. "name": "this is the long name, it can have blanks",
    2. "type_vocableID": 0,
    3. "itemID": 0,
    4. "unitOfMeasureID": 0,
    5. "shortName": "shortname_of_the_item",
    6. "comment": "optional comment, but it is changed"

}

remove

  1. delete sensorOutputs/deleteSensorOutputFromDevice/{outputID}/{itemID} -> done

Use Case 5: create a list for my item that holds necessary infos, such as 'parameter name', 'parameter type', 'unit' and comments', for a PANGAEA data publication.

input:

  • item id
  1. getting all outputs from certain item: /sensors/sensorOutputs/getDeviceSensorOutputs/{deviceID} --> scrape all IDs to a list
  2. iterate over list from 1. and obtain each parameter via /sensors/sensorOutputs/getSensorOutput/{parameterID} --> collect infos on
    • (short) name of parameter
    • parameter type
    • standardized/controlled vocabulary for parameter type (at best a NERC link)
    • unit
    • unit in ucum format
    • description of parameter
    • (user) comment on parameter
  3. compile 2. to a dataframe
  4. write to hd

Use Case 6: adding/removing a user with a certain role to an item

input:

  • (own) user credentials
  • contact role of a user to be added/removed
  • id of a user to be added/removed
  1. post https://sensor.awi.de/rest/sensors/contacts/login
  2. get https://sensor.awi.de/rest/sensors/contacts/getAllContactRoles
  3. get https://sensor.awi.de/rest/sensors/item/getItemByUrn/
  4. user id:
    1. direct input
    2. derived from mail
    3. from first and last name

add

  1. put https://sensor.awi.de/rest/sensors/contacts/putExistingContactToDevice/{itemID}/{userID}/{contactRoleID}

remove

  1. delete https://sensor.awi.de/rest/sensors/contacts/deleteContactFromDevice/{itemID}/{userID}/{contactRoleID}

Use Case 7: show all items (e.g. ctd) that measure a certain parameter type

  • [ ] R
  • [ ] PY

input:

Use Case 8: Which item types are available and how are they described

This procedures applies also to sensors/events/getAllEventTypes, sensors/sensorOutputs/getAllSensorOutputTypes, sensors/unitsOfMeasurement/getAllUnitsOfMeasurement, sensors/measurementProperties/getAllMeasurementPropertyTypes, and several more.

input:

  • nothing required
  1. get https://sensor.awi.de/rest/sensors/item/getAllItemCategories
  2. combine all necessary information

Use Case 9: explore relevant, human-readable metadata fields of an item

input:

  1. get https://sensor.awi.de/rest/sensors/item/getDetailedItem/{itemID}?includeChildren=true

compile parameter list

approach 1

  1. map entries, such as output type, unit, etc. -> create lists
  2. iterate and align information

approach 2

  1. create id list of output items

  2. get https://sensor.awi.de/rest/sensors/sensorOutputs/getSensorOutput/{sensorOutputID} -> create lists

  3. export

make a list of all subitems

  1. extract information of choice

For a complete list of all subitems (of all subitems of all subitems), make use of a while loop as in use case no. 3.

As altnerative approach the endpoint https://sensor.awi.de/rest/sensors/item/getChildrenOfItem/{itemID} could be facilitated as well.

Use Case 10: create a new item

input:

  • (own) user credentials
  • item type
  • status type
  • some infos about the item to be created
  1. post https://sensor.awi.de/rest/sensors/contacts/login --> generate auth token
  2. get https://sensor.awi.de/rest/sensors/item/getAllItemCategories --> item type ID
  3. get https://sensor.awi.de/rest/sensors/item/getAllItemStatuses --> status code ID
  4. put https://sandbox.sensor.awi.de/rest/sensors/item/createItem?parentItemID={parentItemID} --> create item

Use Case 11: reassign items

input:

  • (own) user credentials
  • unmount and mount dates
  • target item ID
  • source item ID
  1. post https://sensor.awi.de/rest/sensors/contacts/login --> generate auth token
  2. put https://sensor.awi.de/rest/sensors/itemReassignment/assignItemToItem/{itemID} + --> content json-body
use case 1 
''' 
basic documentation of sensor.awi.de REST-API can be found here: https://sensor.awi.de/api/
'''
## necessary libraries

import json
import requests
import datetime

## PROD
#sensorURL<- "https://sensor.awi.de/rest/sensors/"
## SANDBOX
sensorURL <- "https://sandbox.sensor.awi.de/rest/sensors/"

## + ================================ | xxx | ================================ + ##
''' 
USE CASE 1: We are looking for a list of items that have a certain user in their contact list.
1.1.a We know the contact email address (as in sensor.awi.de) of the user.
'''
## + ================================ | xxx | ================================ + ##

email = 'marcel.nicolaus@awi.de'

## create link for API call
link = sensorURL + "device/getItemsOfContact/" + email


## calling api
answer = requests.get(link)
## the content itself, read as a json object
fullList = json.loads(answer.content)

## status of request (see httpstatuses.com/)
answer.status_code

## since the result can be 0 items, 1 item, and >1 items , we filter the item ids according the number of items and write to a list
if len(fullList) == 0:
    itemList = []
elif len(fullList) == 1:
    itemList = [fullList[0]['id']]
else:
    itemList = [i['id'] for i in fullList]

## there we go:
print(itemList)

## + ================================ | xxx | ================================ + ##
''' 
USE CASE 1: We are looking for a list of items that have a certain user in their contact list.
1.1.b We know the last name (and if necessary the first name) of the user. Aim: get a single email address.
'''
## + ================================ | xxx | ================================ + ##

## creation of the API call 
link = sensorURL + 'contacts/getAllSystemContacts'

## CASE: unique last name or no contact found

## variables
lastName = 'Gerchow'

## calling api
answer = requests.get(link)
x = json.loads(answer.content)

## loop over entire list
for a in x:
    if a['lastName'] == lastName:
        print(a['email'])



## CASE: non-unique last name or no contact

## variables
lastName = 'Nicolaus'
firstName = 'Rita'

## calling api
answer = requests.get(link)
x = json.loads(answer.content)

## loop over entire list
for a in x:
    if a['lastName'] == lastName and a['firstName'] == firstName:
        print(a['email'])

## + ================================ | xxx | ================================ + ##
''' 
USE CASE 1: We are looking for a list of items that have a certain user in their contact list.
1.2. We have info from 1.1 but need that user only with a certain contact role (e.g. 'Principal Investigator').
'''
## + ================================ | xxx | ================================ + ##

## which user should be searched?
## remember 'email' from 1.1?
#email = 'sandra.tippenhauer@awi.de'

## what role should be filtered?
inputRole = 'Principal Investigator'
inputRole = 'Editor'

## create empty lists
lstID, lstURN = [], []

## recycling of itemList from 1.1
for item in itemList:
    link = sensorURL + "contacts/getDeviceContacts/" + str(item)
    answer = requests.get(link)
    x = json.loads(answer.content)
    
    ## create dictionaries to map uuids to vocables
    dictRoles = {}
    dictAccounts = {}
    for i in x:
        if isinstance(i['contact'], dict):
            dictAccounts[i['contact']['@uuid']] = i['contact']['email']
        if isinstance(i['vocable'], dict):
            dictRoles[i['vocable']['@uuid']] = i['vocable']['generalName']
    
    ## extracting from item
    user, role = [], []
    for i in x:
        if isinstance(i['vocable'], dict):
            role.append(i['vocable']['@uuid'])
        elif isinstance(i['vocable'], str):
            role.append(i['vocable'])
        else:
            pass
        ## 
        if isinstance(i['contact'], dict):
            user.append(i['contact']['@uuid'])
        elif isinstance(i['contact'], str):
            user.append(i['contact'])
        else:
            pass
    
    ## merging info from item and mapping dict
    for i in range(len(user)): ## <-- could improve!!!
        if dictRoles[role[i]] == inputRole and dictAccounts[user[i]] == email:
            lstID.append(item)
            lstURN.append(x[0]['item']['urn'])

## neat output as some sort of report ...
print(json.dumps({'user':email,
                  'timeOfQuery':datetime.datetime.isoformat(datetime.datetime.utcnow()),
                  'role':inputRole,
                  'urn':lstURN,
                  'id':lstID})
)

## ... or just as a single list if item IDs
print(lstID)

## eof
  • No labels