API Reference

Getting Started

Follow this tutorial to learn how to quickly start using the Wizata Python toolkit. With this article you will learn how to create your first Python script and how to execute it on Wizata.

Installation

Open your favorite python IDE and create a new project. Make sure you configure your environment to use Python 3.9 version.

Wizata Python toolkit have been tested with Python 3.9. Other versions might not work.

📘

Wizata Python toolkit have been tested with Python 3.9 other versions might not work.

Currently, there are two different versions that can be installed:

  • The default package contains every core module to communicate with the API.
  • The complete package also contains extra modules to create Machine Learning scripts and tests.

To install Wizata python toolkit package, set the requirements or use pip:

# For default package
pip install wizata_dsapi

# For extra modules package
pip install 'wizata_dsapi[all]'

If you are using Windows terminal you may need to use double quotes to install extra modules (pip install "wizata_dsapi[all]"). For Linux/Unix environments, it is a good practice to use simple quotes (pip install 'wizata_dsapi[all]') to protect special characters.

You should match package version with API version. Navigate to DS API root page to see API version on swagger.

e.g. wizata_dsapi==1.0.23.1 or wizata_dsapi[all]==1.0.23.1

You can verify the API version of your installed package using version tag.

import wizata_dsapi
print(wizata_dsapi.__version__)

Installation on MacOS M1 and M2 chip may requires additional steps to set all requirements.

Configuration

To use the toolkit you will need to configure and indicate both Wizata tenant’s URL and authentication credentials. You can pass the keys when creating an API client within the code or use the environment variables (recommended).

The tenant’s URL can be set through the domain information.

WIZATA_DOMAIN=<domain_name_of_ds_api>

You can use two mode of authentication : interactive (browser prompt) or using API Keys.

Interactive mode is recommended when you use a script executed on demand or within a custom app. It will use credentials and user permissions you provide to connect within your browser.

WIZATA_TENANT_ID=<azure_active_directory_tenant_id>
WIZATA_CLIENT_ID=<azure_active_directory_client_id>
WIZATA_SCOPE=<azure_active_directory_api_scope>

import os
import wizata_dsapi

if __name__ == '__main__':
    client = wizata_dsapi.WizataDSAPIClient(
        tenant_id=os.environ.get('WIZATA_TENANT_ID'),
        client_id=os.environ.get('WIZATA_CLIENT_ID'),
        scope=os.environ.get('WIZATA_SCOPE'),
        domain=os.environ.get('WIZATA_DOMAIN')
    )
    client.authenticate()

API Keys mode is recommended if you are using a notebook or a daemon/service app. Permissions are defined as corresponding App User within the platform.

WIZATA_TENANT_ID=<azure_active_directory_tenant_id>
WIZATA_CLIENT_ID=<azure_active_directory_client_id>
WIZATA_CLIENT_SECRET=<secret_key>

By using API Keys you don’t need to create a client and can directly use the API function to access it.

import wizata_dsapi
wizata_dsapi.api().<function>()

In both case we recommend you contact your system administrator to provide you this configuration.

Sample Query

To get started, you can query data to retrieve a pandas.Dataframe.

The DS API client offers many ways to query data. You can use query method/function of wizata_dsapi.api() to query data.

Here’s a sample request, replace hardware IDs and datetime by the one you would like to use.

from datetime import datetime
import wizata_dsapi

my_dataframe = wizata_dsapi.api().query(
    datapoints=["hardware_id_01","hardware_id_02"],
    start=datetime.strptime("2023-01-01", "%Y-%m-%d"),
    end=datetime.strptime("2023-01-02", "%Y-%m-%d"),
    interval=60000
)

🚧

You should consider using interval and time frame suitable for your data. Querying big data frame might impact your environment performance.

Supported Operations

DS API can be used to do many things, within your Python environment you can always use the following command to verify supported operations :

wizata_dsapi.api().info()

This will print current package version, supported operations by entity and other information.

Here’s a non-exhaustive list of DS API capabilities and where to start:

  • Manipulate datapoint and twin within the digital twin.
  • Query data to receive a formatted dataframe with Time-Series information.
  • Creating scripts to be used within experiments and pipelines.
  • Start building your first pipeline within your solution.
  • Execute existing pipelines.