kepconfig.admin.ua_server

  1# -------------------------------------------------------------------------
  2# Copyright (c), PTC Inc. and/or all its affiliates. All rights reserved.
  3# See License.txt in the project root for
  4# license information.
  5# --------------------------------------------------------------------------
  6
  7r"""`ua_server` exposes an API to allow modifications (add, delete, modify) to 
  8OPC UA Server endpoints within the Kepware Administration through the Kepware Configuration API
  9"""
 10from typing import Union
 11from ..error import KepHTTPError, KepError
 12from ..connection import server
 13from ..utils import _url_parse_object
 14
 15
 16UA_ROOT = '/admin/ua_endpoints'
 17
 18def _create_url(endpoint = None):
 19    '''Creates url object for the "server_users" branch of Kepware's project tree. Used 
 20    to build a part of Kepware Configuration API URL structure
 21
 22    Returns the user specific url when a value is passed as the user name.
 23    '''
 24    
 25    if endpoint == None:
 26        return UA_ROOT
 27    else:
 28        return '{}/{}'.format(UA_ROOT, _url_parse_object(endpoint))
 29
 30def add_endpoint(server: server, DATA: Union[dict, list]) -> Union[bool, list]:
 31    '''Add an `"endpoint"` or multiple `"endpoint"` objects to Kepware UA Server by passing a 
 32    list of endpoints to be added all at once.
 33
 34    :param server: instance of the `server` class
 35    :param DATA: Dict or List of Dicts of the UA Endpoints to add
 36
 37    :return: True - If a "HTTP 201 - Created" is received from Kepware server
 38    :return: If a "HTTP 207 - Multi-Status" is received from Kepware with a list of dict error responses for all 
 39    endpoints added that failed.
 40
 41    :raises KepHTTPError: If urllib provides an HTTPError
 42    :raises KepURLError: If urllib provides an URLError
 43    '''
 44
 45    r = server._config_add(server.url + _create_url(), DATA)
 46    if r.code == 201: return True
 47    elif r.code == 207:
 48        errors = [] 
 49        for item in r.payload:
 50            if item['code'] != 201:
 51                errors.append(item)
 52        return errors
 53    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 54
 55def del_endpoint(server: server, endpoint: str) -> bool:
 56    '''Delete an `"endpoint"` object in Kepware UA Server
 57    
 58    :param server: instance of the `server` class
 59    :param endpoint: name of endpoint to delete
 60    
 61    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 62
 63    :raises KepHTTPError: If urllib provides an HTTPError
 64    :raises KepURLError: If urllib provides an URLError
 65    '''
 66
 67    r = server._config_del(server.url + _create_url(endpoint))
 68    if r.code == 200: return True 
 69    else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 70
 71def modify_endpoint(server: server, DATA: dict, endpoint: str = None) -> bool:
 72    '''Modify a `"endpoint"` object and it's properties in Kepware UA Server. If a `"endpoint"` is not provided as an input,
 73    you need to identify the endpoint in the *'common.ALLTYPES_NAME'* property field in the `"DATA"`. It will 
 74    assume that is the endpoint that is to be modified.
 75
 76    :param server: instance of the `server` class
 77    :param DATA: Dict of the UA endpoint properties to be modified.
 78    :param endpoint: *(optional)* name of endpoint to modify. Only needed if not existing in `"DATA"`
 79    
 80    :return: True - If a "HTTP 200 - OK" is received from Kepware server
 81
 82    :raises KepHTTPError: If urllib provides an HTTPError
 83    :raises KepURLError: If urllib provides an URLError
 84    '''
 85
 86    if endpoint == None:
 87        try:
 88            r = server._config_update(server.url + _create_url(DATA['common.ALLTYPES_NAME']), DATA)
 89            if r.code == 200: return True 
 90            else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 91        except KeyError as err:
 92            err_msg = 'Error: No UA Endpoint identified in DATA | Key Error: {}'.format(err)
 93            raise KepError(err_msg)
 94    else:
 95        r = server._config_update(server.url + _create_url(endpoint), DATA)
 96        if r.code == 200: return True 
 97        else: raise KepHTTPError(r.url, r.code, r.msg, r.hdrs, r.payload)
 98
 99def get_endpoint(server: server, endpoint: str) -> dict:
100    '''Returns the properties of the `"endpoint"` object.
101    
102    :param server: instance of the `server` class
103    :param endpoint: name of endpoint to retrieve
104    
105    :return: Dict of properties for the UA endpoint requested
106
107    :raises KepHTTPError: If urllib provides an HTTPError
108    :raises KepURLError: If urllib provides an URLError
109    '''
110
111    r = server._config_get(server.url + _create_url(endpoint))
112    return r.payload
113
114def get_all_endpoints(server: server, *, options: dict = None) -> list:
115    '''Returns list of all `"endpoint"` objects and their properties.
116    
117    :param server: instance of the `server` class
118    :param options: *(optional)* Dict of parameters to filter, sort or pagenate the list of UA endpoints. Options are 'filter', 
119    'sortOrder', 'sortProperty', 'pageNumber', and 'pageSize.
120    
121    :return: List of properties for all UA endpoints requested
122
123    :raises KepHTTPError: If urllib provides an HTTPError
124    :raises KepURLError: If urllib provides an URLError
125    '''
126
127    r = server._config_get(f'{server.url}{_create_url()}', params= options)
128    return r.payload