# Use AWS IoT SiteWise APIs on the edge Use APIs AWS IoT SiteWise provides a subset of its APIs, along with edge-specific APIs, enabling seamless interaction with asset models and their associated assets deployed at the edge. These asset models must be configured to run on the edge. For more information, see [Configure an asset model for data processing on SiteWise Edge](edge-processing.md#process-gateway-data-edge) for detailed instructions on this setup process. After you configure these APIs, you can retrieve comprehensive data about your asset models and individual assets. Retrieving asset model, asset, dashboard, portal and project information can help you monitor deployed portals and dashboards, and access asset data collected at the edge level. This provides a central host in your network for interactions with AWS IoT SiteWise without requiring a web API call. **Topics** + [ # All available AWS IoT SiteWise Edge device APIs ](edge-apis-available.md) + [ # Edge-only APIs for use with AWS IoT SiteWise edge devices ](edge-local-apis.md) + [ # Enable CORS on AWS IoT SiteWise Edge APIs ](enable-cors-edge-apis.md) + [ # Configure session timeouts for AWS IoT SiteWise Edge ](edge-apis-session-timeout.md) + [ # Tutorial: List asset models on an AWS IoT SiteWise Edge gateway ](edge-apis-tutorial.md) # All available AWS IoT SiteWise Edge device APIs All available APIs AWS IoT SiteWise provides a variety of APIs to use on edge devices so that you can complete tasks locally on the device. Some of the available edge APIs include retrieving asset models, creating and updating asset properties, and sending data streams to the cloud. By leveraging these APIs, you can build solutions that can operate in environments with intermittent or limited network connectivity. ## Available AWS IoT SiteWise APIs The following AWS IoT SiteWise APIs are available on edge devices: + [ListAssetModels](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssetModels.html) + [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) + [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html) + [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) + [DescribeAssetProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetProperty.html) + [ListAssociatedAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssociatedAssets.html) + [GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html) + [GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html) + [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html) + [ListDashboards](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListDashboards.html) + [ListPortals](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListPortals.html) + [ListProjectAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListProjectAssets.html) + [ListProjects](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListProjects.html) + [DescribeDashboard](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeDashboard.html) + [DescribePortal](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribePortal.html) + [DescribeProject](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeProject.html) ## Available edge-only APIs The following APIs are used locally on devices on the edge: + [Authenticate](edge-local-apis.md#edge-local-apis-authenticate) – Use this API to get the SigV4 temporary credentials that you'll use to make API calls. # Edge-only APIs for use with AWS IoT SiteWise edge devices Edge-only APIs In addition to the AWS IoT SiteWise APIs that are available on the edge, there are edge-specific ones. Those edge-specifc APIs are described below. ## Authenticate Gets the credentials from the SiteWise Edge gateway. You'll need to add local users or connect to your system using LDAP or a Linux user pool. For more information about adding users, see [LDAP](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) or [Linux user pool](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app). ### Request syntax ``` POST /authenticate HTTP/1.1 Content-type: application/json { "username": "string", "password": "string", "authMechanism": "string" } ``` ### URI request Parameters The request does not use any URI parameters. ### Request body The request accepts the following data in JSON format. **username** The username used to validate the request call. Type: String Required: Yes **password** The password of the user requesting credentials. Type: String Required: Yes **authMechanism** The authentication method to validate this user in the host. Type: String Valid values: `ldap`, `linux`, `winnt` Required: Yes ### Response syntax ``` HTTP/1.1 200 Content-type: application/json { "accessKeyId": "string", "secretAccessKey": "string", "sessionToken": "string", "region": "edge" } ``` ### Response elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format. **accessKeyId** The access key ID that identifies the temporary security credentials. Length Constraints: Minimum length of 16. Maximum length of 128. Pattern: `[\w]*` **secretAccessKey** The secret access key that can be used to sign requests. Type: String **sessionToken** The token that users must pass to the service API to use the temporary credentials. Type: String **region** The region you are targeting for API calls. Type: CONSTANT - `edge` ### Errors **IllegalArgumentException** The request was rejected because the provided body document was malformed. The error message describes the specific error. HTTP Status Code: 400 **AccessDeniedException** The user doesn't have valid credentials based on the current Identity Provider. The error message describes the authentication Mechanism. HTTP Status Code: 403 **TooManyRequestsException** The request has reached it's limit of authentication attempts. The error message contains the quantity of time to wait until new attempts of authentication are made. HTTP Status Code: 429 # Enable CORS on AWS IoT SiteWise Edge APIs Enable CORS Enabling CORS (Cross-Origin Resource Sharing) on AWS IoT SiteWise Edge APIs allows web applications to directly communicate with the APIs across different domains. This enables seamless integration, real-time data exchange, and cross-domain data access without intermediary servers or workarounds. CORS settings can be configured to specify allowable origins, ensuring controlled cross-origin access. **Note** CORS is available for version 3.3.1 and later of the This feature is available for version 3.3.1 and later of the `aws.iot.SiteWiseEdgeProcessor` component. For more information, see [AWS IoT SiteWise processor](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. **To enable CORS on SiteWise Edge APIs** 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. In the navigation pane, choose **Edge gateways**. 1. Select the SiteWise Edge gateway for which you want to enable CORS. You can enable CORS on the AWS IoT Greengrass V2 deployment type. 1. In the **Gateway configuration** section, choose the associated **Greengrass core device**. 1. In the **Deployments** tab, under **Greengrass devices**, select the appropriate deployment link. 1. Under **Actions** choose **Revise**, then **Revise deployment**. **Important** Creating a revised CORS enabled configuration replaces the device’s current configuration. 1. In **Step 1, Specify target**, provide an optional **Name** to identify the deployment. 1. In **Step 2, Select components - optional**, you can leave all current selections as-is and choose **Next**. 1. In **Step 3, Configure components - optional**, select **aws.iot.SiteWiseEdgeProcessor**, and choose **Configure component**. 1. In the Configuration update section, under Configuration to merge, enter the following JSON: ``` { "AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN": "*" } ``` **Note** Using `*` as the value for `AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN` allows all origins. For production environments, it's recommended to specify exact origin URLs for better security. 1. Choose **Confirm**. 1. Choose **Next** to proceed through remaining steps until you arrive at **Step5, Review**. 1. Review your configuration changes, then choose **Deploy** to apply the changes to your SiteWise Edge gateway. **Note** Alternatively, you can enable CORS by setting global the environmental variable `AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN` to `*` on your AWS IoT SiteWise gateway. **Note** For authenticated proxy, `userinfo` must be included in the `url` field in the proxy configuration rather than as a separated `username` and `password` fields. After the deployment is complete, CORS is enabled on your SiteWise Edge API, allowing specified origins to make cross-origin requests to the API. # Configure session timeouts for AWS IoT SiteWise Edge Configure session timeouts SiteWise Edge allows you to configure session timeouts for the SiteWise Edge API. This feature enhances security by automatically terminating inactive sessions after a specified time-period. This section guides you through the process of configuring the session timeout using the AWS IoT SiteWise console. **Note** Session timeout configuration is available for version 3.4.0 and later of the `aws.iot.SiteWiseEdgeProcessor` component. For more information, see [AWS IoT SiteWise processor](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. **To configure a session timeout for a SiteWise Edge gateway** 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. In the navigation pane, choose **Edge gateways**. 1. Choose the SiteWise Edge gateway where you want to configure the session timeout. **Note** You can configure the session timeout on the AWS IoT Greengrass V2 deployment type. 1. In the **Gateway configuration** section, choose the associated **Greengrass core device**. 1. In the **Deployments** tab, under **Greengrass devices**, select the appropriate deployment link. 1. Under **Actions** choose **Revise**. Read the warning, and then choose **Revise deployment**. **Important** Creating a revised session timeout configuration replaces the device's current configuration. 1. In **Step 1, Specify target**, provide an optional **Name** to identify the revised deployment, and then choose **Next**. 1. In **Step 2, Select components - optional**, you can leave all current selections as-is and choose **Next**. 1. In **Step 3, Configure components - optional**, select **aws.iot.SiteWiseEdgeProcessor**, and choose **Configure component**. 1. In the **Configuration update** section, under **Configuration to merge**, enter the following JSON: ``` { "AWS_SITEWISE_EDGE_SESSION_TIMEOUT_MINUTES": "240" } ``` 1. Set the value for `AWS_SITEWISE_EDGE_SESSION_TIMEOUT_MINUTES` in minutes. Session timeout values can be from 1 minute to 10080 minutes (7 days). The default value is 240 minutes (4 hours). 1. Choose **Confirm**. 1. Choose **Next** to proceed through remaining steps until you arrive at Step 5, **Review**. 1. Review your configuration changes, then choose **Deploy** to apply the changes to your SiteWise Edge gateway. **Note** Alternatively, you can configure the session timeout by setting the global environmental variable **AWS\$1SITEWISE\$1EDGE\$1SESSION\$1TIMEOUT\$1MINUTES** to your desired value (in minutes) on your SiteWise Edge gateway. After the deployment is complete, the new session timeout configuration is applied to your SiteWise Edge API. # Tutorial: List asset models on an AWS IoT SiteWise Edge gateway Tutorial: Get a list of asset models You can use a subset of the available AWS IoT SiteWise APIs along with edge-specific APIs to interact with asset models and their assets on the edge. This tutorial will walk you through getting temporary credentials to an AWS IoT SiteWise Edge gateway and getting a list of the asset models on the SiteWise Edge gateway. ## Prerequisites In the steps of this tutorial you can use a variety of tools. To use these tools, make sure you have the corresponding prerequisites installed. To complete this tutorial, you need the following: + A deployed and running [AWS IoT SiteWise Edge self-hosted gateway requirements](configure-gateway-ggv2.md) + Access to your SiteWise Edge gateway in the same network over port 443. + [OpenSSL](https://www.openssl.org/) installed + (AWS OpsHub for AWS IoT SiteWise) The [AWS OpsHub for AWS IoT SiteWise application](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) + (curl) [curl](https://ec.haxx.se/install/) installed + (Python) [urllib3](https://urllib3.readthedocs.io/en/stable/index.html) installed + (Python) [Python3](https://www.python.org/downloads/) installed + (Python) [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) installed + (Python) [BotoCore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) installed ## Step 1: Get a SiteWise Edge gateway service signed certificate To establish a TLS connection to the APIs available at the SiteWise Edge gateway, you need a trusted certificate. You can generate this certificate using a OpenSSL or AWS OpsHub for AWS IoT SiteWise. ------ #### [ OpenSSL ] **Note** You need [OpenSSL](https://www.openssl.org/) installed to run this command. Open a terminal and run the following command to get a signed certificate from the SiteWise Edge gateway. Replace `` with the IP of the SiteWise Edge gateway. ``` openssl s_client -connect :443 /dev/null | openssl x509 -outform PEM > GatewayCert.pem ``` ------ #### [ AWS OpsHub for AWS IoT SiteWise ] You can use AWS OpsHub for AWS IoT SiteWise. For more information, see [Manage SiteWise Edge gateways](manage-gateways-ggv2.md). ------ The absolute path to the downloaded SiteWise Edge gateway certificate is used in this tutorial. Run the following command to export the complete path of your certificate, replacing `` with the path to the certificate: ``` export PATH_TO_CERTIFICATE='' ``` ## Step 2: Get your SiteWise Edge gateway hostname **Note** You need [OpenSSL](https://www.openssl.org/) installed to run this command. To complete the tutorial you'll need the hostname of your SiteWise Edge gateway. To get the hostname of your SiteWise Edge gateway, run the following, replacing `` with the IP of the SiteWise Edge gateway: ``` openssl s_client -connect :443 /dev/null | grep -Po 'CN = \K.*'| head -1 ``` Run the following command to export the hostname for use later, replacing `` with the hostname of your SiteWise Edge gateway: ``` export GATEWAY_HOSTNAME='' ``` ## Step 3: Get temporary credentials for your SiteWise Edge gateway Now that you have the signed certificate and the hostname of your SiteWise Edge gateway, you need to get temporary credentials so you can run APIs on the gateway. You can get these credentials through AWS OpsHub for AWS IoT SiteWise or directly from the SiteWise Edge gateway using APIs. **Important** Credentials expire every 4 hours, so you should get the credentials just before using the APIs on your SiteWise Edge gateway. Don't cache credentials for longer than 4 hours. ### Get temporary credentials using AWS OpsHub for AWS IoT SiteWise **Note** You need the [AWS OpsHub for AWS IoT SiteWise application](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) installed. To use AWS OpsHub for AWS IoT SiteWise application to get your temporary credentials do the following: 1. Log into the application. 1. Choose **Settings**. 1. For **Authentication**, choose **Copy credentials**. 1. Expand the option that fits your environment and choose **Copy**. 1. Save the credentials for use later. ### Get temporary credentials using the SiteWise Edge gateway API To use the SiteWise Edge gateway API to get the temporary credentials you can use a Python script or curl, first you'll need to have a user name and password for your SiteWise Edge gateway. The SiteWise Edge gateways use SigV4 authentication and authorization. For more information about adding users, see [LDAP](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) or [Linux user pool](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app). These credentials will be used in the following steps to get the local credentials on your SiteWise Edge gateway that are needed to use the AWS IoT SiteWise APIs. ------ #### [ Python ] **Note** You need [urllib3](https://urllib3.readthedocs.io/en/stable/index.html) and [Python3](https://www.python.org/downloads/) installed. **To get the credentials using Python** 1. Create a file called **get\$1credentials.py** and the copy the following code into it. ``` ''' The following demonstrates how to get the credentials from the SiteWise Edge gateway. You will need to add local users or connect your system to LDAP/AD https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#create-user-pool Example usage: python3 get_credentials.py -e https:// -c -u '' -p '' -m '' ''' import urllib3 import json import urllib.parse import sys import os import getopt """ This function retrieves the AWS IoT SiteWise Edge gateway credentials. """ def get_credentials(endpoint,certificatePath, user, password, method): http = urllib3.PoolManager(cert_reqs='CERT_REQUIRED', ca_certs= certificatePath) encoded_body = json.dumps({ "username": user, "password": password, "authMechanism": method, }) url = urllib.parse.urljoin(endpoint, "/authenticate") response = http.request('POST', url, headers={'Content-Type': 'application/json'}, body=encoded_body) if response.status != 200: raise Exception(f'Failed to authenticate! Response status {response.status}') auth_data = json.loads(response.data.decode('utf-8')) accessKeyId = auth_data["accessKeyId"] secretAccessKey = auth_data["secretAccessKey"] sessionToken = auth_data["sessionToken"] region = "edge" return accessKeyId, secretAccessKey, sessionToken, region def print_help(): print('Usage:') print(f'{os.path.basename(__file__)} -e -c -u -p -m -a ') print('') print('-e, --endpoint edge gateway endpoint. Usually the Edge gateway hostname.') print('-c, --cert_path path to downloaded gateway certificate') print('-u, --user Edge user') print('-p, --password Edge password') print('-m, --method (Optional) Authentication method (linux, winnt, ldap), default is linux') sys.exit() def parse_args(argv): endpoint = "" certificatePath = None user = None password = None method = "linux" try: opts, args = getopt.getopt(argv, "he:c:u:p:m:", ["endpoint=","cert_path=", "user=", "password=", "method="]) except getopt.GetoptError: print_help() for opt, arg in opts: if opt == '-h': print_help() elif opt in ("-e", "--endpoint"): endpoint = arg elif opt in ("-u", "--user"): user = arg elif opt in ("-p", "--password"): password = arg elif opt in ("-m", "--method"): method = arg.lower() elif opt in ("-c", "--cert_path"): certificatePath = arg if method not in ['ldap', 'linux', 'winnt']: print("not valid method parameter, required are ldap, linux, winnt") print_help() if (user == None or password == None): print("To authenticate against edge user, password have to be passed together, and the region has to be set to 'edge'") print_help() if(endpoint == ""): print("You must provide a valid and reachable gateway hostname") print_help() return endpoint,certificatePath, user, password, method def main(argv): # get the command line args endpoint, certificatePath, user, password, method = parse_args(argv) accessKeyId, secretAccessKey, sessionToken, region=get_credentials(endpoint, certificatePath, user, password, method) print("Copy and paste the following credentials into the shell, they are valid for 4 hours:") print(f"export AWS_ACCESS_KEY_ID={accessKeyId}") print(f"export AWS_SECRET_ACCESS_KEY={secretAccessKey}") print(f"export AWS_SESSION_TOKEN={sessionToken}") print(f"export AWS_REGION={region}") print() if __name__ == "__main__": main(sys.argv[1:]) ``` 1. Run **get\$1credentials.py** from the terminal replacing `` and `` with the credentials you created. ``` python3 get_credentials.py -e https://$GATEWAY_HOSTNAME -c $PATH_TO_CERTIFICATE -u '' -p '' -m 'linux' ``` ------ #### [ curl ] **Note** You need [curl](https://ec.haxx.se/install/) installed. **To get the credentials using curl** 1. Run the following command from the terminal replacing and with the credentials you created. ``` curl --cacert $PATH_TO_CERTIFICATE --location \ -X POST https://$GATEWAY_HOSTNAME:443/authenticate \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "", "password": "", "authMechanism": "linux" }' ``` The response should look like the following: ``` { "username": "sweuser", "accessKeyId": "", "secretAccessKey": "", "sessionToken": "", "sessionExpiryTime": "2022-11-17T04:51:40.927095Z", "authMechanism": "linux", "role": "edge-user" } ``` 1. Run the following command from your terminal. ``` export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= export AWS_SESSION_TOKEN= export AWS_REGION=edge ``` ------ ## Step 4: Get a list of the asset models on the SiteWise Edge gateway Now that you have a signed certificate, your SiteWise Edge gateway hostname, and temporary credentials for your SiteWise Edge gateway, you can use the `ListAssetModels` API to get a list of the asset models on your SiteWise Edge gateway. ------ #### [ Python ] **Note** You need [Python3](https://www.python.org/downloads/), [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html), and [BotoCore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) installed. **To get the the list of asset models using Python** 1. Create a file called **list\$1asset\$1model.py** and the copy the following code into it. ``` import json import boto3 import botocore import os # create the client using the credentials client = boto3.client("iotsitewise", endpoint_url= "https://"+ os.getenv("GATEWAY_HOSTNAME"), region_name=os.getenv("AWS_REGION"), aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), aws_session_token=os.getenv("AWS_SESSION_TOKEN"), verify=os.getenv("PATH_TO_CERTIFICATE"), config=botocore.config.Config(inject_host_prefix=False)) # call the api using local credentials response = client.list_asset_models() print(response) ``` 1. Run **list\$1asset\$1model.py** from the terminal. ``` python3 list_asset_model.py ``` ------ #### [ curl ] **Note** You need [curl](https://ec.haxx.se/install/) installed. **To get the list of asset models using curl** Run the following command from the terminal. ``` curl \ --request GET https://$GATEWAY_HOSTNAME:443/asset-models \ --cacert $PATH_TO_CERTIFICATE \ --aws-sigv4 "aws:amz:edge:iotsitewise" \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ -H "x-amz-security-token:$AWS_SESSION_TOKEN" ``` The response should look like the following: ``` { "assetModelSummaries": [ { "arn": "arn:aws:iotsitewise:{region}:{account-id}:asset-model/{asset-model-id}", "creationDate": 1.669245291E9, "description": "This is a small example asset model", "id": "{asset-model-id}", "lastUpdateDate": 1.669249038E9, "name": "Some Metrics Model", "status": { "error": null, "state": "ACTIVE" } }, . . . ], "nextToken": null } ``` ------