prerequisiti per i metadati TransferJob autorizzazioni IAM Esegui un'operazione in blocco Gestione degli errori Importa modelli di metadati AWS IoT TwinMaker esempi di metadati TransferJob

Esecuzione di operazioni di importazione ed esportazione in blocco

Questo argomento spiega come eseguire operazioni di importazione ed esportazione in blocco e come gestire gli errori nei processi di trasferimento. Fornisce esempi di processi di trasferimento che utilizzano i comandi CLI.

L' AWS IoT TwinMaker API Reference contiene informazioni su CreateMetadataTransferJob e altre azioni API.

Argomenti

prerequisiti per i metadati TransferJob
autorizzazioni IAM
Esegui un'operazione in blocco
Gestione degli errori
Importa modelli di metadati
AWS IoT TwinMaker esempi di metadati TransferJob

prerequisiti per i metadati TransferJob

Completa i seguenti prerequisiti prima di eseguire i metadati: TransferJob

Crea uno spazio di lavoro. AWS IoT TwinMaker L'area di lavoro può essere la destinazione di importazione o l'origine di esportazione per i metadati. TransferJob Per informazioni sulla creazione di uno spazio di lavoro, vedere,. Creare un'area di lavoro
Crea un bucket Amazon S3 per archiviare le risorse. Per ulteriori informazioni sull'utilizzo di Amazon S3, consulta Cos'è Amazon S3?

autorizzazioni IAM

Quando esegui operazioni in blocco, devi creare una policy IAM con autorizzazioni per consentire lo scambio di AWS risorse tra Amazon S3, AWS IoT TwinMaker AWS IoT SiteWise, e il tuo computer locale. Per ulteriori informazioni sulla creazione di policy IAM, consulta Creazione di policy IAM.

Le dichiarazioni politiche per AWS IoT TwinMaker Amazon S3 AWS IoT SiteWise e Amazon S3 sono elencate qui:

AWS IoT TwinMaker politica:

AWS IoT SiteWise politica:

Politica Amazon S3:


{
    "Effect": "Allow",
    "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:GetBucketLocation",
        "s3:ListBucket",
        "s3:AbortMultipartUpload",
        "s3:ListBucketMultipartUploads",
        "s3:ListMultipartUploadParts"
    ],
    "Resource": "*"
}

In alternativa, puoi impostare la tua policy Amazon S3 in modo da accedere a un solo bucket Amazon S3, consulta la seguente policy.

Policy con ambito singolo di Amazon S3


{
    "Effect": "Allow",
    "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:GetBucketLocation",
        "s3:ListBucket",
        "s3:AbortMultipartUpload",
        "s3:ListBucketMultipartUploads",
        "s3:ListMultipartUploadParts"
    ],
    "Resource": [
        "arn:aws:s3:::bucket name",
        "arn:aws:s3:::bucket name/*"
    ]
}

Imposta il controllo dell'accesso per i metadati TransferJob

Per controllare il tipo di job a cui un utente può accedere, aggiungi la seguente policy IAM al ruolo utilizzato per chiamare. AWS IoT TwinMaker

Nota

Questa policy consente l'accesso solo ai lavori di AWS IoT TwinMaker importazione ed esportazione che trasferiscono risorse da e verso Amazon S3.


{
    "Effect": "Allow",
    "Action": [
        "iottwinmaker:*DataTransferJob*"
    ],
    "Resource": "*",
    "Condition": {
        "StringLikeIfExists": {
            "iottwinmaker:sourceType": [
                "s3",
                "iottwinmaker"
            ],
            "iottwinmaker:destinationType": [
                "iottwinmaker",
                "s3"
            ]
        }
    }
}

Esegui un'operazione in blocco

Questa sezione spiega come eseguire operazioni di importazione ed esportazione in blocco.

Importa dati da Amazon S3 a AWS IoT TwinMaker

Specifica le risorse che desideri trasferire utilizzando lo schema dei AWS IoT TwinMaker metadatiTransferJob . Crea e archivia il tuo file di schema nel tuo bucket Amazon S3.

Per esempi di schemi, consulta. Importa modelli di metadati
Crea un corpo della richiesta e salvalo come file JSON. Il corpo della richiesta specifica l'origine e la destinazione del processo di trasferimento. Assicurati di specificare il bucket Amazon S3 come origine e il tuo AWS IoT TwinMaker spazio di lavoro come destinazione.

Di seguito è riportato un esempio del corpo di una richiesta:
```
{
    "metadataTransferJobId": "your-transfer-job-Id",
    "sources": [{
        "type": "s3",
        "s3Configuration": {
            "location": "arn:aws:s3:::amzn-s3-demo-bucket/your_import_data.json"
        }
    }],
    "destination": {
        "type": "iottwinmaker",
        "iotTwinMakerConfiguration": {
            "workspace": "arn:aws:iottwinmaker:us-east-1:111122223333:workspace/your-worksapce-name"
        }
    }
}
```
Registra il nome del file che hai dato al corpo della richiesta, ti servirà nel passaggio successivo. In questo esempio viene denominato il corpo della richiestacreateMetadataTransferJobImport.json.
Esegui il seguente comando CLI per richiamare CreateMetadataTransferJob (sostituisci il nome del file input-json con il nome che hai dato al corpo della richiesta):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
Questo crea un metadato TransferJob e avvia il processo di trasferimento delle risorse selezionate.

Esporta dati da AWS IoT TwinMaker verso Amazon S3

Crea un corpo di richiesta JSON con i filtri appropriati per scegliere le risorse da esportare. Per questo esempio utilizziamo:


{
    "metadataTransferJobId": "your-transfer-job-Id",
    "sources": [{
        "type": "iottwinmaker",
        "iotTwinMakerConfiguration": {
            "workspace": "arn:aws:iottwinmaker:us-east-1:111122223333:workspace/your-workspace-name",
            "filters": [{
                "filterByEntity": {
                    "entityId": "parent"
                }},
                {
                "filterByEntity": {
                    "entityId": "child"
                }},
                {
                "filterByComponentType": {
                    "componentTypeId": "component.type.minimal"
                }}
            ]
        }
    }],
    "destination": {
        "type": "s3",
        "s3Configuration": {
            "location": "arn:aws:s3:::amzn-s3-demo-bucket"
        }
    }
}

L'filtersarray consente di specificare quali risorse verranno esportate. In questo esempio filtriamo perentity, ecomponentType.

Assicurati di specificare il tuo AWS IoT TwinMaker spazio di lavoro come origine e il bucket Amazon S3 come destinazione del processo di trasferimento dei metadati.

Salva il corpo della richiesta e registra il nome del file, ti servirà nel passaggio successivo. Per questo esempio, abbiamo chiamato il corpo della richiestacreateMetadataTransferJobExport.json.

Esegui il seguente comando CLI per richiamare CreateMetadataTransferJob (sostituisci il nome del file input-json con il nome che hai dato al corpo della richiesta):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
Questo crea un metadato TransferJob e avvia il processo di trasferimento delle risorse selezionate.

Per controllare o aggiornare lo stato di un processo di trasferimento, utilizzate i seguenti comandi:

Per annullare un processo, utilizza l'azione CancelMetadataTransferJob API. Quando chiami CancelMetadataTransferJob, l'API annulla solo i metadati TransferJob in esecuzione e tutte le risorse già esportate o importate non sono interessate da questa chiamata API.
Per recuperare informazioni su un job specifico, usa l'azione API. GetMetadataTransferJob

In alternativa, puoi richiamare GetMetadataTransferJob un processo di trasferimento esistente con il seguente comando CLI:
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
Se GetMetadataTransferJob richiamate un processo di AWS IoT TwinMaker importazione o esportazione non esistente, riceverete un ResourceNotFoundException errore nella risposta.
Per elencare i lavori correnti, usa l'azione ListMetadataTransferJobs API.

Ecco un esempio di CLI che chiama ListMetadataTransferJobs with AWS IoT TwinMaker come DestinationType e s3 come SourceType:
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
Nota
È possibile modificare i valori dei parametri sourceType e destinationType in modo che corrispondano all'origine e alla destinazione del processo di importazione o esportazione.

Per altri esempi di comandi CLI che richiamano queste azioni API, consulta. AWS IoT TwinMaker esempi di metadati TransferJob

Se riscontri errori durante il processo di trasferimento, consulta. Gestione degli errori

Gestione degli errori

Dopo aver creato ed eseguito un processo di trasferimento, puoi chiamare GetMetadataTransferJob per diagnosticare eventuali errori che si sono verificati:


aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1

Una volta visualizzato lo stato del processoCOMPLETED, puoi verificarne i risultati. GetMetadataTransferJob restituisce un oggetto chiamato MetadataTransferJobProgress che contiene i seguenti campi:

FailedCount: indica il numero di risorse non riuscite durante il processo di trasferimento.
SkippedCount: indica il numero di risorse che sono state ignorate durante il processo di trasferimento.
SucceededCount: indica il numero di risorse che hanno avuto successo durante il processo di trasferimento.
TotalCount: indica il numero totale di risorse coinvolte nel processo di trasferimento.

Inoltre, viene restituito un elemento reportURL che contiene un URL prefirmato. Se il processo di trasferimento presenta degli errori che desideri approfondire, puoi scaricare una segnalazione completa degli errori utilizzando questo URL.

Importa modelli di metadati

È possibile importare molti componenti, ComponentType o entità con un'unica operazione di importazione in blocco. Gli esempi in questa sezione mostrano come eseguire questa operazione.

template: Importing entities

Utilizzate il seguente formato di modello per un processo che importa entità:


{
  "entities": [
    {
      "description": "string",
      "entityId": "string",
      "entityName": "string",
      "parentEntityId": "string",
      "tags": {
        "string": "string"
      },
      "components": {
        "string": {    
          "componentTypeId": "string",
          "description": "string",
          "properties": {
            "string": {
              "definition": {
                "configuration": {
                  "string": "string"
                },
                "dataType": "DataType",
                "defaultValue": "DataValue",
                "displayName": "string",
                "isExternalId": "boolean",
                "isRequiredInEntity": "boolean",
                "isStoredExternally": "boolean",
                "isTimeSeries": "boolean"
              },
              "value": "DataValue"
            }
          },
          "propertyGroups": {
            "string": {
              "groupType": "string",
              "propertyNames": [
                "string"
              ]
            }
          }
        }
      }
    }
  ]
}

template: Importing componentTypes

Utilizzate il seguente formato di modello per un processo che importa ComponentTypes:


{
  "componentTypes": [
    {
      "componentTypeId": "string",
      "componentTypeName": "string",
      "description": "string",
      "extendsFrom": [
        "string"
      ],
      "functions": {
        "string": {
          "implementedBy": {
            "isNative": "boolean",
            "lambda": {
              "functionName": "Telemetry-tsDataReader",
              "arn": "Telemetry-tsDataReaderARN"
            }
          },
          "requiredProperties": [
            "string"
          ],
          "scope": "string"
        }
      },
      "isSingleton": "boolean",
      "propertyDefinitions": {
        "string": {
          "configuration": {
            "string": "string"
          },
          "dataType": "DataType",
          "defaultValue": "DataValue",
          "displayName": "string",
          "isExternalId": "boolean",
          "isRequiredInEntity": "boolean",
          "isStoredExternally": "boolean",
          "isTimeSeries": "boolean"
        }
      },
      "propertyGroups": {
        "string": {
          "groupType": "string",
          "propertyNames": [
            "string"
          ]
        }
      },
      "tags": {
        "string": "string"
      }
    }
  ]
}

template: Importing components

Utilizzate il seguente formato di modello per un processo che importa componenti:


{
  "entityComponents": [
    {
      "entityId": "string",
      "componentName": "string",
      "componentTypeId": "string",
      "description": "string",
      "properties": {
        "string": {
          "definition": {
            "configuration": {
              "string": "string"
            },
            "dataType": "DataType",
            "defaultValue": "DataValue",
            "displayName": "string",
            "isExternalId": "boolean",
            "isRequiredInEntity": "boolean",
            "isStoredExternally": "boolean",
            "isTimeSeries": "boolean"
          },
          "value": "DataValue"
        }
      },
      "propertyGroups": {
        "string": {
          "groupType": "string",
          "propertyNames": [
            "string"
          ]
        }
      }
    }
  ]
}

AWS IoT TwinMaker esempi di metadati TransferJob

Utilizzate i seguenti comandi per gestire i trasferimenti di metadati:

CreateMetadataTransferJobAzione API.

Esempio di comando CLI:


aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://yourTransferFileName.json

Per annullare un lavoro usa l'azione CancelMetadataTransferJob API.

Esempio di comando CLI:
```
aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
Quando si chiama CancelMetadataTransferJob, annulla solo uno specifico processo di trasferimento dei metadati e tutte le risorse già esportate o importate non vengono interessate.

Per recuperare informazioni su un processo specifico, utilizza l'azione API. GetMetadataTransferJob

Esempio di comando CLI:


aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1 \

Per elencare i lavori correnti usa l'azione ListMetadataTransferJobs API.

È possibile filtrare i risultati restituiti ListMetadataTransferJobs utilizzando un file JSON. Consultate la seguente procedura utilizzando la CLI:
1. Crea un file JSON di input CLI per specificare i filtri che desideri utilizzare:
```
{
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}
```
  Salvalo e registra il nome del file, ti servirà quando inserisci il comando CLI.
2. Usa il file JSON come argomento per il seguente comando CLI:
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```

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

Operazioni in blocco

AWS IoT TwinMaker schema del processo di trasferimento dei metadati