-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4 from CPES-Power-and-Energy-Systems/github
sync: github to main
- Loading branch information
Showing
5 changed files
with
72 additions
and
161 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| name: automerge | ||
| on: | ||
| pull_request: | ||
| types: | ||
| - labeled | ||
| - unlabeled | ||
| - synchronize | ||
| - opened | ||
| - edited | ||
| - ready_for_review | ||
| - reopened | ||
| - unlocked | ||
| pull_request_review: | ||
| types: | ||
| - submitted | ||
| check_suite: | ||
| types: | ||
| - completed | ||
| status: {} | ||
| jobs: | ||
| automerge: | ||
| permissions: write-all | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - id: automerge | ||
| name: automerge | ||
| uses: "pascalgn/[email protected]" | ||
| env: | ||
| GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" | ||
| MERGE_FILTER_AUTHOR: "github-actions" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,6 +7,7 @@ on: | |
|
|
||
| jobs: | ||
| sync: | ||
| permissions: write-all | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,90 +1,65 @@ | ||
| # TSG-Client | ||
| # INESC TEC Client for TNO Security Gateway (TSG) Dataspace Components (TSG-Client) | ||
|
|
||
| []() | ||
| []() | ||
| [](https://www.python.org/downloads/release/python-390/) | ||
| [](https://opensource.org/licenses/Apache-2.0) | ||
| []() | ||
| []() | ||
| [](https://www.python.org/downloads/release/python-390/) | ||
|
|
||
| This document provides detailed instructions for setting up the INESC TEC Client for TNO Security Gateway (TSG-Client) environment. | ||
| Please follow these steps carefully to ensure successful configuration and deployment. | ||
|
|
||
|
|
||
| This document provides detailed instructions for setting up the TSG-Client environment. Please follow these steps carefully to ensure successful configuration and deployment. | ||
| > **_NOTE:_** This library assumes that you have a running instance of the TSG Core Connector and OpenAPI Data APP. For this, please follow the [Official TSG Documentation](https://tno-tsg.gitlab.io/). | ||
|
|
||
| ## Overview | ||
| TSG Client is a Python library for interacting with the TNO Security Gateway (TSG). It provides a simple and easy-to-use interface for tasks such as: | ||
|
|
||
| - Connecting to TSG connectors | ||
| TSG Client is a Python library for interacting with the TNO Security Gateway (TSG). | ||
| It is current version, it is a simple REST API client that interacts with [TSG Core Connector APIs](https://tno-tsg.gitlab.io/docs/core-container/api/) and [TSG OpenAPI Data APP](https://gitlab.com/tno-tsg/data-apps/openapi). | ||
| It provides a simple and easy-to-use interface for tasks such as: | ||
|
|
||
| - Connecting to a TSG core container (via API KEY) | ||
| - Retrieving connector self-descriptions | ||
| - Working with catalogs and artifacts | ||
| - Requesting and consuming data artifacts | ||
| - Knowing what connectors are in the dataspace | ||
| - Take advantage of the OpenAPI functionalities | ||
| - Parsing / filtering connector catalogs and artifacts, retrieved from self-descriptions | ||
| - Requesting and consuming data artifacts (via dataspace) | ||
| - Queries to the dataspace Metadata Broker to list registered connectors and respective self-descriptions | ||
| - Perform requests via OpenAPI Data APP | ||
|
|
||
|
|
||
| ## Installation steps | ||
| > **_WARNING:_** This library is under active development and is not yet recommended for production use at this time. | ||
| ### Install essential tools | ||
| > **_IMPORTANT:_** This development is an internal initiative from INESC TEC within [ENERSHARE](https://enershare.eu/), and it is not officially maintained/supported by TNO team. | ||
| ## Documentation & Examples | ||
|
|
||
| - **Install GIT:** | ||
| - Download and install GIT from [Git Download Page](https://git-scm.com/downloads) | ||
| A detailed documentation is available in the [docs](docs/) directory. | ||
| Python examples (and respective description) are available in the [examples](examples/) directory. | ||
|
|
||
| - **Python**: Install Python (tested using Python 3.9) | ||
|
|
||
| - **Install Python requirements:** | ||
| - Open a terminal and execute the following command: | ||
| ```bash | ||
| pip install -r requirements.txt | ||
| ``` | ||
| ## Installation | ||
|
|
||
| ### Clone the project and setup the environment | ||
| ### Base Requirements | ||
|
|
||
| Open a terminal and execute the following commands: | ||
| * [Python 3.9+](https://www.python.org/downloads/) | ||
|
|
||
| ```bash | ||
| git clone https://gitlab.inesctec.pt/cpes/european-projects/enershare/tsg-client.git | ||
| cd tsg-client | ||
| ``` | ||
| ### Installation steps | ||
|
|
||
| ### OR Install the Library | ||
| To install the TSG-Client, please follow the steps below: | ||
|
|
||
| Open a project and execute the following commands: | ||
| 1. Clone the repository. | ||
|
|
||
| ```bash | ||
| pip install git+https://gitlab.inesctec.pt/cpes/european-projects/enershare/tsg-client.git | ||
| $ git clone https://github.com/CPES-Power-and-Energy-Systems/tsg-client.git | ||
| ``` | ||
|
|
||
| ### Set up environment variables | ||
|
|
||
| Create a `.env` file with the following contents: | ||
| 4. Run the following command to install the package: | ||
|
|
||
| ```bash | ||
| cp dotenv .env | ||
| $ python setup.py install | ||
| ``` | ||
|
|
||
| ### Edit the .env file and replace the following placeholders with your specific values: | ||
|
|
||
| Open the `.env` file in a text editor and modify the following variables with your actual information: | ||
|
|
||
| - **API_KEY**: Replace with your TSG API key. | ||
| - **CONNECTOR_ID**: Replace with the connector ID for your TSG instance. | ||
| - **ACCESS_URL**: Replace with the access URL for your TSG connector. | ||
| - **AGENT_ID**: Replace with the agent ID associated with your TSG connector. | ||
|
|
||
| - **EXTERNAL_CONNECTOR_ID**: Replace with the external connector ID. | ||
| - **EXTERNAL_ACCESS_URL**: Replace with the access URL for the external connector. | ||
| - **EXTERNAL_AGENT_ID**: Replace with the agent ID associated with the external connector. | ||
|
|
||
| Make sure to save the changes after updating the values. | ||
|
|
||
| ## Adding new dependencies | ||
|
|
||
| ## Additional Information | ||
|
|
||
| The TSG-Client is a REST API that interacts with the connector of the dataspace of TNO, deployed following a specific tutorial. The available requests are currently being tested in `main.py`. The script demonstrates interactions with TSG OpenApi Data APP and inter-connector API. | ||
|
|
||
|
|
||
| ## Adding dependencies | ||
|
|
||
| To add a new dependency, please add it to the `requirements.in` file and run the following command: | ||
| In case of new developments, if you plan to a add a new dependency, please add it to the `requirements.in` file and run the following command: | ||
|
|
||
| ```bash | ||
| pip-compile requirements.in | ||
|
|
@@ -93,110 +68,15 @@ pip-compile requirements.in | |
| This will generate a new `requirements.txt` file with the new dependency added. | ||
|
|
||
| ## Usage | ||
| To get started, check out the examples in the [examples](./examples) directory. These examples demonstrate how to instanciate the `TSGController` and use the multiple functionalities of TSG Client. | ||
|
|
||
| To use the TSG Client, you first need to create a `TSGController` instance: | ||
|
|
||
| ```bash | ||
| from tsg_client.controllers import TSGController | ||
| config = { | ||
| "API_KEY": "<YOUR_API_KEY>", | ||
| "CONNECTOR_ID": "<YOUR_CONNECTOR_ID>", | ||
| "ACCESS_URL": "<YOUR_ACCESS_URL>", | ||
| "AGENT_ID": "<YOUR_AGENT_ID>", | ||
| } | ||
| conn = TSGController(**config) | ||
| ``` | ||
| ## Contacts: | ||
|
|
||
| 1. Connect to a TSG connector: | ||
|
|
||
| ```bash | ||
| conn.connect() | ||
| ``` | ||
|
|
||
| 2. Get connector self-description: | ||
|
|
||
| ```bash | ||
| self_description = conn.get_connector_self_selfdescription() | ||
| print(self_description) | ||
| ``` | ||
|
|
||
| 3. Get external connector self-description: | ||
|
|
||
| ```bash | ||
| access_url = "https://<external_connector_url>/selfdescription" | ||
| connector_id = "<external_connector_id>" | ||
| agent_id = "<agent_id>" | ||
| description = conn.get_connector_selfdescription( | ||
| access_url=access_url, | ||
| connector_id=connector_id, | ||
| agent_id=agent_id | ||
| ) | ||
| print(description) | ||
| ``` | ||
| 4. Work with catalogs and artifacts: | ||
|
|
||
| ```bash | ||
| # Parse resource catalogs | ||
| catalogs = conn.parse_resource_catalogs(self_description=description) | ||
| print(catalogs) | ||
| # Parse catalog artifacts | ||
| artifacts = conn.parse_catalog_artifacts(self_description=description) | ||
| print(artifacts) | ||
| ``` | ||
|
|
||
| 5. Request and consume data artifacts: | ||
| ```bash | ||
| # Request contract agreement | ||
| artifact_id = artifacts[0]['id'] | ||
| artifact_access_url = artifacts[0]['access_url'] | ||
| artifact_contract_offer = artifacts[0]['contract_offer'] | ||
| contract_agreement_id = conn.request_agreement( | ||
| connector_id=external_connector['CONNECTOR_ID'], | ||
| artifact_access_url=artifact_access_url, | ||
| artifact_contract_offer=artifact_contract_offer | ||
| ) | ||
| print(contract_agreement_id) | ||
| # Request data artifact | ||
| artifact_path = "<artifact_path>" | ||
| artifact_description = "<description>" | ||
| artifact_title = "<title>" | ||
| data_artifact = conn.publish_data_artifact(artifact=artifact_path, | ||
| contract_offer=artifacts[0]['contract_offer'], | ||
| description=artifact_description, | ||
| title=artifact_title) | ||
| print(data_artifact) | ||
| ``` | ||
|
|
||
| 6. Request the OpenAPI specifications from an external connector: | ||
| ```bash | ||
| open_api_specs = conn.get_openapi_specs(description, "0.9.2") | ||
| print(open_api_specs) | ||
| ``` | ||
|
|
||
| 7. Execute an request through the OpenAPI to an external connector: | ||
| Note: To enable this functionality, it is required that the OpenAPI is deployed on the used connector. | ||
| ```bash | ||
| openapi_request = conn.openapi_request( | ||
| "https://backend-01.enershare.inesctec.pt/router", | ||
| "urn:playground:tsg:connectors:cpes01", | ||
| "1.0.0", | ||
| "test-service") | ||
| print(openapi_request) | ||
| ``` | ||
|
|
||
| ### Contact Information | ||
|
|
||
| If you encounter any issues or have questions, please feel free to reach out to the support team: | ||
| If you have any questions regarding this project, please contact the following people: | ||
|
|
||
| Developers (SW source code / methodology questions): | ||
| - **Carolina Catorze:** [[email protected]](mailto:[email protected]) | ||
| - **Vasco Maia:** [[email protected]](mailto:[email protected]) | ||
| - **Vasco Guedes:** [[email protected]](mailto:[email protected]) | ||
| - **José Luís Rodrigues:** [[email protected]](mailto:[email protected]) | ||
| - **José Ricardo Andrade:** [[email protected]](mailto:[email protected]) | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,5 +5,5 @@ Contacts | |
| If you encounter any issues or have questions, please feel free to reach out to the support team: | ||
|
|
||
| - **Carolina Catorze:** [[email protected]](mailto:[email protected]) | ||
| - **Vasco Maia:** [[email protected]](mailto:[email protected]) | ||
| - **Vasco Guedes:** [[email protected]](mailto:[email protected]) | ||
| - **José Ricardo Andrade:** [[email protected]](mailto:[email protected]) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,7 +15,7 @@ def load_requirements(file_name): | |
| packages=['tsg_client', 'tsg_client.controllers', 'tsg_client.utils'], | ||
| url='', | ||
| license='', | ||
| author='Carolina Catorze, Vasco Maia, José Luis Rodrigues, José Ricardo Andrade', | ||
| author='Carolina Catorze, Vasco Guedes, José Luis Rodrigues, José Ricardo Andrade', | ||
| author_email=""" | ||
| - [email protected] | ||
| - [email protected] | ||
|
|
||