Requisitos previos Paso 1: Obtenga un certificado firmado por el servicio SiteWise Edge Gateway Paso 2: Obtenga el nombre de host de la puerta de enlace SiteWise Edge Paso 3: Obtenga credenciales temporales para su SiteWise puerta de enlace Edge Paso 4: Obtenga una lista de los modelos de activos de la puerta de enlace SiteWise Edge

Tutorial: Obtener una lista de modelos de activos en una puerta de enlace SiteWise Edge

Puede utilizar un subconjunto de las API de AWS IoT SiteWise disponibles junto con API específicas de periferia para interactuar con sus recursos y modelos de recursos en la periferia. En este tutorial, se explica cómo obtener credenciales temporales para una puerta de enlace AWS IoT SiteWise Edge y cómo obtener una lista de los modelos de activos de la puerta de enlace SiteWise Edge.

Requisitos previos

En los pasos de este tutorial puede utilizar diversas herramientas. Para utilizar estas herramientas, asegúrese de tener instalados los requisitos previos correspondientes.

Necesitará lo siguiente para completar este tutorial:

Un SiteWise Requisitos de Edge Gateway implementado y en ejecución
Acceda a su puerta de enlace SiteWise Edge en la misma red a través del puerto 443.
OpenSSL instalado
(AWS OpsHubparaAWS IoT SiteWise) La AWS IoT SiteWiseaplicación AWS OpsHub para
(curl) curl instalado
(Python) urllib3 instalado
(Python) Python3 instalado
(Python) Boto3 instalado
(Python) BotoCoreinstalado

Paso 1: Obtenga un certificado firmado por el servicio SiteWise Edge Gateway

Para establecer una conexión TLS con las API disponibles en la puerta de enlace SiteWise Edge, necesita un certificado de confianza. Puede generar este certificado mediante OpenSSL AWS OpsHub o for. AWS IoT SiteWise

En este tutorial se utiliza la ruta absoluta al certificado de puerta de enlace SiteWise Edge descargado. Ejecute el siguiente comando para exportar la ruta completa de su certificado, sustituyendo <absolute_path_to_certificate> por la ruta al certificado:


export PATH_TO_CERTIFICATE='<absolute_path_to_certificate>'

Paso 2: Obtenga el nombre de host de la puerta de enlace SiteWise Edge

nota

Necesita tener instalado OpenSSL para ejecutar este comando.

Para completar el tutorial, necesitará el nombre de host de su puerta de enlace SiteWise Edge. Para obtener el nombre de host de la puerta de enlace SiteWise Edge, ejecute lo siguiente y sustitúyalo por <sitewise_gateway_ip> la IP de la puerta de enlace SiteWise Edge:


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

Ejecute el siguiente comando para exportar el nombre de host para usarlo más adelante y <your_edge_gateway_hostname> sustitúyalo por el nombre de host de su SiteWise puerta de enlace Edge:


export GATEWAY_HOSTNAME='<your_edge_gateway_hostname>'

Paso 3: Obtenga credenciales temporales para su SiteWise puerta de enlace Edge

Ahora que tiene el certificado firmado y el nombre de host de su puerta de enlace SiteWise Edge, necesita obtener credenciales temporales para poder ejecutar las API en la puerta de enlace. Puede obtener estas credenciales a través de la puerta AWS OpsHub de enlace de SiteWise Edge AWS IoT SiteWise o directamente desde ella mediante las API.

importante

Las credenciales caducan cada 4 horas, por lo que debe obtenerlas justo antes de usar las API de su puerta de enlace SiteWise Edge. No almacene las credenciales en caché durante más de 4 horas.

Obtenga credenciales temporales utilizando AWS OpsHub para AWS IoT SiteWise

nota

Necesita tener instalada la aplicación AWS OpsHub para AWS IoT SiteWise.

Para utilizar la aplicación AWS OpsHub para AWS IoT SiteWise a fin de obtener sus credenciales temporales, haga lo siguiente:

Inicie sesión en la aplicación.
Elija Configuración.
En Autenticación, elija Copiar credenciales.
Amplíe la opción que se adapte a su entorno y elija Copiar.
Guarde las credenciales para utilizarlas más tarde.

Obtenga credenciales temporales mediante la API de SiteWise Edge Gateway

Para usar la API de puerta de enlace de SiteWise Edge para obtener las credenciales temporales, puede usar un script de Python o un curl, primero necesitará tener un nombre de usuario y una contraseña para su puerta de enlace de SiteWise Edge. Las puertas de enlace SiteWise Edge utilizan la autenticación y la autorización SigV4. Para obtener más información sobre cómo añadir usuarios, consulte LDAP o Grupo de usuarios de Linux. Estas credenciales se utilizarán en los siguientes pasos para obtener las credenciales locales en su puerta de enlace SiteWise Edge que se necesitan para usar las AWS IoT SiteWise API.

Python

nota

Necesita tener urllib3 y Python3 instalados.

Para obtener las credenciales mediante Python

Cree un archivo llamado get_credentials.py y copie en él el siguiente código.


'''
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:])

Ejecute get_credentials.py desde el terminal sustituyendo <gateway_username> y <gateway_password> por las credenciales que ha creado.


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

curl

nota

Necesita tener curl instalado.

Para obtener las credenciales mediante curl

Ejecute el siguiente comando desde el terminal sustituyendo <gateway_username> y <gateway_password> por las credenciales que ha creado.


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 respuesta debe ser similar a la siguiente:


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

Ejecute el siguiente comando desde el terminal.


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

Paso 4: Obtenga una lista de los modelos de activos de la puerta de enlace SiteWise Edge

Ahora que tiene un certificado firmado, el nombre de host de la puerta de enlace SiteWise Edge y las credenciales temporales de la puerta de enlace SiteWise Edge, puede usar la ListAssetModels API para obtener una lista de los modelos de activos de la puerta de enlace SiteWise Edge.

Python

nota

Necesitas tener instalado Python3 y Boto3. BotoCore

Para obtener la lista de modelos de recursos mediante Python

Cree un archivo llamado list_asset_model.py y copie el siguiente código en él.


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)

Ejecute list_asset_model.py desde el terminal.
```
python3 list_asset_model.py
```

curl

nota

Necesita tener curl instalado.

Para obtener la lista de modelos de recursos mediante curl

Ejecute el siguiente comando desde el 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"

La respuesta debe ser similar a la siguiente:


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

API de solo periferia

Backup y restauración de gateways SiteWise Edge