Prerequisiti Passaggio 1: ottenere un certificato firmato per il servizio gateway SiteWise Edge Passaggio 2: ottieni il nome host SiteWise del gateway Edge Passaggio 3: Ottieni credenziali temporanee per il tuo gateway Edge SiteWise Passaggio 4: Ottieni un elenco dei modelli di asset sul gateway SiteWise Edge

Tutorial: Ottenere un elenco di modelli di asset su un gateway SiteWise Edge

Puoi utilizzare un sottoinsieme delle AWS IoT SiteWise API disponibili insieme alle API specifiche di Edge per interagire con i modelli di asset e le relative risorse sull'edge. Questo tutorial ti illustrerà come ottenere credenziali temporanee per un gateway AWS IoT SiteWise Edge e ottenere un elenco dei modelli di asset sul gateway Edge. SiteWise

Prerequisiti

Nei passaggi di questo tutorial puoi utilizzare una varietà di strumenti. Per utilizzare questi strumenti, assicurati di aver installato i prerequisiti corrispondenti.

Per completare questo tutorial, è necessario quanto segue:

A: distribuito e funzionante SiteWise Requisiti del gateway Edge self-hosted
Accesso al gateway SiteWise Edge nella stessa rete tramite la porta 443.
OpenSSL installato
(AWS OpsHubperAWS IoT SiteWise) L'AWS OpsHubapplicazione for AWS IoT SiteWise
(curl) curl installato
(Python) urllib3 installato
(Python) Python3 installato
(Python) Boto3 installato
(Python) installato BotoCore

Passaggio 1: ottenere un certificato firmato per il servizio gateway SiteWise Edge

Per stabilire una connessione TLS alle API disponibili sul gateway SiteWise Edge, è necessario un certificato affidabile. È possibile generare questo certificato utilizzando un OpenSSL o forAWS OpsHub. AWS IoT SiteWise

In questo tutorial viene utilizzato il percorso assoluto del certificato gateway SiteWise Edge scaricato. Esegui il comando seguente per esportare il percorso completo del certificato, sostituendolo <absolute_path_to_certificate> con il percorso del certificato:


export PATH_TO_CERTIFICATE='<absolute_path_to_certificate>'

Passaggio 2: ottieni il nome host SiteWise del gateway Edge

Nota

È necessario che sia installato OpenSSL per eseguire questo comando.

Per completare il tutorial è necessario il nome host del gateway Edge. SiteWise Per ottenere il nome host del gateway SiteWise Edge, esegui quanto segue, sostituendolo <sitewise_gateway_ip> con l'IP del gateway SiteWise Edge:


openssl s_client -connect <sitewise_gateway_ip>:443 </dev/null 2>/dev/null | grep -Po 'CN = \K.*'| head -1

Esegui il comando seguente per esportare il nome host da utilizzare in seguito, sostituendolo <your_edge_gateway_hostname> con il nome host del gateway Edge: SiteWise


export GATEWAY_HOSTNAME='<your_edge_gateway_hostname>'

Passaggio 3: Ottieni credenziali temporanee per il tuo gateway Edge SiteWise

Ora che hai il certificato firmato e il nome host del tuo gateway SiteWise Edge, devi ottenere credenziali temporanee per poter eseguire le API sul gateway. È possibile ottenere queste credenziali tramite AWS OpsHub AWS IoT SiteWise o direttamente dal gateway SiteWise Edge utilizzando le API.

Importante

Le credenziali scadono ogni 4 ore, quindi è consigliabile ottenerle subito prima di utilizzare le API sul gateway Edge. SiteWise Non memorizzate nella cache le credenziali per più di 4 ore.

Ottieni credenziali temporanee utilizzando for AWS OpsHubAWS IoT SiteWise

Nota

È necessario installare l'AWS IoT SiteWiseapplicazione AWS OpsHub for.

Per utilizzare l'AWS IoT SiteWiseapplicazione AWS OpsHub per ottenere le credenziali temporanee, procedi come segue:

Accedere all'applicazione.
Seleziona Impostazioni.
Per Autenticazione, scegli Copia credenziali.
Espandi l'opzione più adatta al tuo ambiente e scegli Copia.
Salva le credenziali per utilizzarle in seguito.

Ottieni credenziali temporanee utilizzando l'API del gateway SiteWise Edge

Per utilizzare l'API SiteWise Edge gateway per ottenere le credenziali temporanee è possibile utilizzare uno script Python o curl, per prima cosa è necessario disporre di un nome utente e una password per SiteWise il gateway Edge. I gateway SiteWise Edge utilizzano l'autenticazione e l'autorizzazione SigV4. Per ulteriori informazioni sull'aggiunta di utenti, consulta LDAP o pool di utenti Linux. Queste credenziali verranno utilizzate nei passaggi seguenti per ottenere le credenziali locali sul gateway SiteWise Edge necessarie per utilizzare le API. AWS IoT SiteWise

Python

Nota

È necessario installare urllib3 e Python3.

Per ottenere le credenziali usando Python

Crea un file chiamato get_credentials.py e poi copia il seguente codice al suo interno.


'''
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://<gateway_hostname> -c <path_to_certificate> -u '<gateway_username>' -p '<gateway_password>' -m '<method>'
'''
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 <endpoint> -c <path/to/certificate> -u <user> -p <password> -m <method> -a <alias>')
    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:])

Esegui get_credentials.py dal terminale sostituendo <gateway_username> e <gateway_password> con le credenziali che hai creato.


python3 get_credentials.py -e https://$GATEWAY_HOSTNAME -c $PATH_TO_CERTIFICATE -u '<gateway_username>' -p '<gateway_password>' -m 'linux'

curl

Nota

È necessario installare curl.

Per ottenere le credenziali usa curl

Esegui il seguente comando dal terminale sostituendo <gateway_username>e <gateway_password>con le credenziali che hai creato.


curl --cacert $PATH_TO_CERTIFICATE --location \
-X POST https://$GATEWAY_HOSTNAME:443/authenticate \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "<gateway_username>",
    "password": "<gateway_password>",
    "authMechanism": "linux"
}'

La risposta dovrebbe essere simile alla seguente:


{
    "username": "sweuser",
    "accessKeyId": "<accessKeyId>",
    "secretAccessKey": "<secretAccessKey>",
    "sessionToken": "<sessionToken>",
    "sessionExpiryTime": "2022-11-17T04:51:40.927095Z",
    "authMechanism": "linux",
    "role": "edge-user"
}

Eseguire il seguente comando dal terminale.


export AWS_ACCESS_KEY_ID=<accessKeyId>
export AWS_SECRET_ACCESS_KEY=<secretAccessKey>
export AWS_SESSION_TOKEN=<sessionToken>
export AWS_REGION=edge

Passaggio 4: Ottieni un elenco dei modelli di asset sul gateway SiteWise Edge

Ora che disponete di un certificato firmato, del nome host del gateway SiteWise Edge e delle credenziali temporanee per il gateway SiteWise Edge, potete utilizzare l'ListAssetModelsAPI per ottenere un elenco dei modelli di asset sul gateway SiteWise Edge.

Python

Nota

È necessario installare Python3 e Boto3. BotoCore

Per ottenere l'elenco dei modelli di asset usando Python

Crea un file chiamato list_asset_model.py e poi copia il seguente codice al suo interno.


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)

Esegui list_asset_model.py dal terminale.
```
python3 list_asset_model.py
```

curl

Nota

È necessario installare curl.

Per ottenere l'elenco dei modelli di asset che utilizzano curl

Esegui il seguente comando dal terminale.


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"

La risposta dovrebbe essere simile alla seguente:


{
    "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
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

API solo Edge

Ospita un gateway su Siemens Industrial Edge