TransferJob prérequis en matière de métadonnées Autorisations IAM Exécuter une opération groupée Gestion des erreurs Importer des modèles de métadonnées AWS IoT TwinMaker TransferJob exemples de métadonnées

Réalisation d'opérations d'importation et d'exportation en masse

Cette rubrique explique comment effectuer des opérations d'importation et d'exportation en masse et comment gérer les erreurs dans vos tâches de transfert. Il fournit des exemples de tâches de transfert utilisant des commandes CLI.

La référence de AWS IoT TwinMaker l'API contient des informations sur les actions de l'API CreateMetadataTransferJob et sur d'autres actions.

Rubriques

TransferJob prérequis en matière de métadonnées
Autorisations IAM
Exécuter une opération groupée
Gestion des erreurs
Importer des modèles de métadonnées
AWS IoT TwinMaker TransferJob exemples de métadonnées

TransferJob prérequis en matière de métadonnées

Veuillez remplir les conditions préalables suivantes avant d'exécuter une métadonnée TransferJob :

Créez un AWS IoT TwinMaker espace de travail. L'espace de travail peut être la destination d'importation ou la source d'exportation d'une métadonnéeTransferJob. Pour plus d'informations sur la création d'un espace de travail, voirCréation d’un espace de travail.
Créez un compartiment Amazon S3 pour stocker les ressources. Pour plus d'informations sur l'utilisation d'Amazon S3, consultez Qu'est-ce qu'Amazon S3 ?

Autorisations IAM

Lorsque vous effectuez des opérations en masse, vous devez créer une politique IAM avec des autorisations permettant l'échange de AWS ressources entre Amazon S3, AWS IoT TwinMaker AWS IoT SiteWise, et votre machine locale. Pour plus d'informations sur la création de politiques IAM, consultez la section Création de politiques IAM.

Les déclarations de politique relatives à AWS IoT TwinMaker Amazon S3 AWS IoT SiteWise et à Amazon S3 sont répertoriées ici :

AWS IoT TwinMaker politique :

AWS IoT SiteWise politique :

Politique Amazon S3 :


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

Vous pouvez également définir votre politique Amazon S3 de manière à n'accéder qu'à un seul compartiment Amazon S3. Consultez la politique suivante.

Politique relative à un compartiment unique pour 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/*"
    ]
}

Configurer le contrôle d'accès pour une métadonnée TransferJob

Pour contrôler le type de tâches auquel un utilisateur peut accéder, ajoutez la politique IAM suivante au rôle utilisé pour appeler AWS IoT TwinMaker.

Note

Cette politique autorise uniquement l'accès aux tâches AWS IoT TwinMaker d'importation et d'exportation qui transfèrent des ressources depuis et vers Amazon S3.


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

Exécuter une opération groupée

Cette section explique comment effectuer des opérations d'importation et d'exportation en masse.

Importer des données depuis Amazon S3 vers AWS IoT TwinMaker

Spécifiez les ressources que vous souhaitez transférer à l'aide du TransferJob schéma de AWS IoT TwinMaker métadonnées. Créez et stockez votre fichier de schéma dans votre compartiment Amazon S3.

Pour des exemples de schémas, voirImporter des modèles de métadonnées.
Créez un corps de requête et enregistrez-le en tant que fichier JSON. Le corps de la demande spécifie la source et la destination de la tâche de transfert. Assurez-vous de spécifier votre compartiment Amazon S3 comme source et votre AWS IoT TwinMaker espace de travail comme destination.

Voici un exemple de corps de requête :
```
{
    "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"
        }
    }
}
```
Enregistrez le nom de fichier que vous avez donné au corps de votre demande, vous en aurez besoin à l'étape suivante. Dans cet exemple, le corps de la requête est nommécreateMetadataTransferJobImport.json.
Exécutez la commande CLI suivante pour invoquer CreateMetadataTransferJob (remplacez le nom du fichier input-json par le nom que vous avez donné au corps de votre requête) :
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
Cela crée des métadonnées TransferJob et lance le processus de transfert des ressources que vous avez sélectionnées.

Exporter des données depuis AWS IoT TwinMaker vers Amazon S3

Créez un corps de requête JSON avec les filtres appropriés pour choisir les ressources que vous souhaitez exporter. Pour cet exemple, nous utilisons :


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

Le filters tableau vous permet de spécifier quelles ressources seront exportées. Dans cet exempleentity, nous filtrons par etcomponentType.

Assurez-vous de spécifier votre AWS IoT TwinMaker espace de travail comme source et votre compartiment Amazon S3 comme destination de la tâche de transfert de métadonnées.

Enregistrez le corps de votre demande et enregistrez le nom du fichier, vous en aurez besoin à l'étape suivante. Pour cet exemple, nous avons nommé le corps de notre requêtecreateMetadataTransferJobExport.json.

Exécutez la commande CLI suivante pour invoquer CreateMetadataTransferJob (remplacez le nom du fichier input-json par le nom que vous avez donné au corps de votre requête) :
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
Cela crée des métadonnées TransferJob et lance le processus de transfert des ressources que vous avez sélectionnées.

Pour vérifier ou mettre à jour l'état d'une tâche de transfert, utilisez les commandes suivantes :

Pour annuler une tâche, utilisez l'action de CancelMetadataTransferJob l'API. Lorsque vous appelez CancelMetadataTransferJob, l'API annule uniquement les métadonnées en cours d'exécutionTransferJob, et les ressources déjà exportées ou importées ne sont pas affectées par cet appel d'API.
Pour récupérer des informations sur une tâche spécifique, utilisez l'action de GetMetadataTransferJob l'API.

Vous pouvez également faire appel GetMetadataTransferJob à une tâche de transfert existante à l'aide de la commande CLI suivante :
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
Si vous faites appel GetMetadataTransferJob à une tâche d' AWS IoT TwinMaker importation ou d'exportation qui n'existe pas, une ResourceNotFoundException erreur s'affiche en réponse.
Pour répertorier les tâches en cours, utilisez l'action d' ListMetadataTransferJobsAPI.

Voici un exemple de CLI qui appelle ListMetadataTransferJobs avec AWS IoT TwinMaker comme DestinationType et s3 comme SourceType :
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
Note
Vous pouvez modifier les valeurs des paramètres SourceType et DestinationType en fonction de la source et de la destination de votre tâche d'importation ou d'exportation.

Pour plus d'exemples de commandes CLI qui invoquent ces actions d'API, consultezAWS IoT TwinMaker TransferJob exemples de métadonnées.

Si vous rencontrez des erreurs lors de la tâche de transfert, consultezGestion des erreurs.

Gestion des erreurs

Après avoir créé et exécuté une tâche de transfert, vous pouvez appeler GetMetadataTransferJob pour diagnostiquer les erreurs qui se sont produites :


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

Une fois que vous voyez l'état de la tâche évoluerCOMPLETED, vous pouvez vérifier les résultats de la tâche. GetMetadataTransferJob renvoie un objet appelé MetadataTransferJobProgress qui contient les champs suivants :

FailedCount : indique le nombre de ressources qui ont échoué pendant le processus de transfert.
SkippedCount : indique le nombre de ressources qui ont été ignorées pendant le processus de transfert.
SucceededCount : indique le nombre de ressources qui ont réussi pendant le processus de transfert.
TotalCount : indique le nombre total de ressources impliquées dans le processus de transfert.

En outre, un élément ReportUrl contenant une URL pré-signée est renvoyé. Si votre tâche de transfert comporte des erreurs que vous souhaitez approfondir, vous pouvez télécharger un rapport d'erreur complet à l'aide de cette URL.

Importer des modèles de métadonnées

Vous pouvez importer de nombreux composants, types de composants ou entités en une seule opération d'importation groupée. Les exemples de cette section montrent comment procéder.

template: Importing entities

Utilisez le format de modèle suivant pour une tâche qui importe des entités :


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

Utilisez le format de modèle suivant pour une tâche qui importe des 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

Utilisez le format de modèle suivant pour une tâche qui importe des composants :


{
  "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 TransferJob exemples de métadonnées

Utilisez les commandes suivantes pour gérer vos transferts de métadonnées :

CreateMetadataTransferJobAction d'API.

Exemple de commande CLI :


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

Pour annuler une tâche, utilisez l'action de CancelMetadataTransferJob l'API.

Exemple de commande CLI :
```
aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
Lorsque vous appelez CancelMetadataTransferJob, cela annule uniquement une tâche de transfert de métadonnées spécifique, et les ressources déjà exportées ou importées ne sont pas affectées.
Pour récupérer des informations sur une tâche spécifique, utilisez l'action de GetMetadataTransferJob l'API.

Exemple de commande CLI :
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1 \
```
Pour répertorier les tâches en cours, utilisez l'action d' ListMetadataTransferJobsAPI.

Vous pouvez filtrer les résultats renvoyés à ListMetadataTransferJobs l'aide d'un fichier JSON. Consultez la procédure suivante à l'aide de l'interface de ligne de commande :
1. Créez un fichier JSON d'entrée CLI pour spécifier les filtres que vous souhaitez utiliser :
```
{
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}
```
  Enregistrez-le et enregistrez le nom du fichier, vous en aurez besoin lors de la saisie de la commande CLI.
2. Utilisez le fichier JSON comme argument pour la commande CLI suivante :
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Opérations en vrac

AWS IoT TwinMaker schéma des tâches de transfert de métadonnées