TransferJob requisitos previos de metadatos Permisos de IAM Ejecute una operación masiva Gestión de errores Importa plantillas de metadatos AWS IoT TwinMaker TransferJob ejemplos de metadatos

Realizar operaciones masivas de importación y exportación

En este tema se explica cómo realizar operaciones masivas de importación y exportación y cómo gestionar los errores en los trabajos de transferencia. Proporciona ejemplos de trabajos de transferencia mediante comandos de la CLI.

La referencia AWS IoT TwinMaker de la API contiene información sobre las acciones de la API CreateMetadataTransferJob y otras.

Temas

TransferJob requisitos previos de metadatos
Permisos de IAM
Ejecute una operación masiva
Gestión de errores
Importa plantillas de metadatos
AWS IoT TwinMaker TransferJob ejemplos de metadatos

TransferJob requisitos previos de metadatos

Complete los siguientes requisitos previos antes de ejecutar un metadato: TransferJob

Cree un AWS IoT TwinMaker espacio de trabajo. El espacio de trabajo puede ser el destino de importación o la fuente de exportación de los metadatosTransferJob. Para obtener información sobre la creación de un espacio de trabajo, consulteCreación de un espacio de trabajo.
Cree un bucket de Amazon S3 para almacenar recursos. Para obtener más información sobre el uso de Amazon S3, consulte ¿Qué es Amazon S3?

Permisos de IAM

Cuando realiza operaciones masivas, debe crear una política de IAM con permisos que permitan el intercambio de AWS recursos entre Amazon S3 y su máquina local. AWS IoT TwinMaker AWS IoT SiteWise Para obtener más información sobre la creación de políticas de IAM, consulte Creación de políticas de IAM.

Las declaraciones de política de AWS IoT TwinMaker Amazon S3 AWS IoT SiteWise y Amazon S3 se enumeran aquí:

AWS IoT TwinMaker política:

AWS IoT SiteWise política:

Política de Amazon S3:


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

Si lo prefiere, puede limitar su política de Amazon S3 para acceder únicamente a un único bucket de Amazon S3, consulte la siguiente política.

Política de ámbito único de Amazon S3 para un solo bucket


{
    "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/*"
    ]
}

Establezca el control de acceso para los metadatos TransferJob

Para controlar el tipo de trabajos a los que puede acceder un usuario, añada la siguiente política de IAM al rol utilizado para llamar AWS IoT TwinMaker.

nota

Esta política solo permite el acceso a los trabajos de AWS IoT TwinMaker importación y exportación que transfieren recursos desde y hacia Amazon S3.


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

Ejecute una operación masiva

En esta sección se explica cómo realizar operaciones masivas de importación y exportación.

Importe datos de Amazon S3 a AWS IoT TwinMaker

Especifique los recursos que desea transferir mediante el TransferJob esquema de AWS IoT TwinMaker metadatos. Cree y almacene el archivo de esquema en su bucket de Amazon S3.

Para ver esquemas de ejemplo, consulteImporta plantillas de metadatos.
Cree un cuerpo de solicitud y guárdelo como un archivo JSON. El cuerpo de la solicitud especifica el origen y el destino del trabajo de transferencia. Asegúrese de especificar su bucket de Amazon S3 como origen y su AWS IoT TwinMaker espacio de trabajo como destino.

El siguiente es un ejemplo del cuerpo de una solicitud:
```
{
    "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 el nombre de archivo que le diste al cuerpo de la solicitud; lo necesitarás en el siguiente paso. En este ejemplo, el cuerpo de la solicitud recibe un nombrecreateMetadataTransferJobImport.json.
Ejecuta el siguiente comando de la CLI para invocar CreateMetadataTransferJob (reemplaza el nombre del archivo input-json por el nombre que le diste al cuerpo de la solicitud):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
Esto crea un metadato TransferJob y comienza el proceso de transferencia de los recursos seleccionados.

Exporte datos desde AWS IoT TwinMaker a Amazon S3

Cree un cuerpo de solicitud JSON con los filtros adecuados para elegir los recursos que desea exportar. Para este ejemplo utilizamos:


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

La filters matriz le permite especificar qué recursos se exportarán. En este ejemplo filtramos porentity, ycomponentType.

Asegúrese de especificar su AWS IoT TwinMaker espacio de trabajo como fuente y su depósito de Amazon S3 como destino del trabajo de transferencia de metadatos.

Guarde el cuerpo de la solicitud y registre el nombre del archivo; lo necesitará en el siguiente paso. En este ejemplo, hemos denominado al cuerpo de nuestra solicitudcreateMetadataTransferJobExport.json.

Ejecuta el siguiente comando de la CLI para invocar CreateMetadataTransferJob (reemplaza el nombre del archivo input-json por el nombre que le diste al cuerpo de la solicitud):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
Esto crea un metadato TransferJob y comienza el proceso de transferencia de los recursos seleccionados.

Para comprobar o actualizar el estado de un trabajo de transferencia, utilice los siguientes comandos:

Para cancelar un trabajo, usa la acción CancelMetadataTransferJob de la API. Cuando llamas CancelMetadataTransferJob, la API solo cancela los metadatos TransferJob en ejecución y los recursos ya exportados o importados no se ven afectados por esta llamada a la API.
Para recuperar información sobre un trabajo específico, usa la acción de la GetMetadataTransferJob API.

O bien, puede invocar GetMetadataTransferJob un trabajo de transferencia existente con el siguiente comando de la CLI:
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
Si solicita un trabajo GetMetadataTransferJob de AWS IoT TwinMaker importación o exportación que no existe, recibirá un ResourceNotFoundException error en la respuesta.
Para ver una lista de los trabajos actuales, usa la acción de la ListMetadataTransferJobs API.

Este es un ejemplo de la CLI en el que se invoca ListMetadataTransferJobs con AWS IoT TwinMaker los valores DestinationType y s3 SourceType:
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
nota
Puedes cambiar los valores de los parámetros SourceType y DestinationType para que coincidan con el origen y el destino del trabajo de importación o exportación.

Para obtener más ejemplos de comandos de la CLI que invocan estas acciones de la API, consulte. AWS IoT TwinMaker TransferJob ejemplos de metadatos

Si encuentra algún error durante el trabajo de transferencia, consulteGestión de errores.

Gestión de errores

Después de crear y ejecutar un trabajo de transferencia, puedes llamar GetMetadataTransferJob para diagnosticar cualquier error que se haya producido:


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

Cuando veas el estado del trabajoCOMPLETED, puedes verificar los resultados del trabajo. GetMetadataTransferJob devuelve un objeto llamado MetadataTransferJobProgress que contiene los siguientes campos:

FailedCount: indica la cantidad de recursos que fallaron durante el proceso de transferencia.
SkippedCount: indica la cantidad de recursos que se omitieron durante el proceso de transferencia.
SucceededCount: indica la cantidad de recursos que se realizaron correctamente durante el proceso de transferencia.
TotalCount: indica el recuento total de los recursos involucrados en el proceso de transferencia.

Además, se devuelve un elemento reportURL que contiene una URL previamente firmada. Si tu trabajo de transferencia contiene errores que deseas investigar más a fondo, puedes descargar un informe de errores completo utilizando esta URL.

Importa plantillas de metadatos

Puede importar muchos componentes, componentTypes o entidades con una sola operación de importación masiva. Los ejemplos de esta sección muestran cómo hacerlo.

template: Importing entities

Utilice el siguiente formato de plantilla para un trabajo que importe entidades:


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

Usa el siguiente formato de plantilla para un trabajo que importe 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

Utilice el siguiente formato de plantilla para un trabajo que importe componentes:


{
  "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 ejemplos de metadatos

Use los siguientes comandos para administrar las transferencias de metadatos:

CreateMetadataTransferJobAcción de API.

Ejemplo de comando de CLI:


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

Para cancelar un trabajo, utilice la acción CancelMetadataTransferJob de la API.

Ejemplo de comando de la CLI:
```
aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
Cuando llamas CancelMetadataTransferJob, solo cancela un trabajo de transferencia de metadatos específico y los recursos ya exportados o importados no se ven afectados.
Para recuperar información sobre un trabajo específico, utilice la acción de la GetMetadataTransferJob API.

Ejemplo de comando de la CLI:
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1 \
```
Para enumerar los trabajos actuales, utilice la acción ListMetadataTransferJobs de la API.

Puedes filtrar los resultados devueltos ListMetadataTransferJobs mediante un archivo JSON. Consulte el siguiente procedimiento mediante la CLI:
1. Cree un archivo JSON de entrada de la CLI para especificar los filtros que desea usar:
```
{
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}
```
  Guárdelo y registre el nombre del archivo; lo necesitará al introducir el comando de la CLI.
2. Utilice el archivo JSON como argumento para el siguiente comando de la CLI:
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```

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

Operaciones masivas

AWS IoT TwinMaker esquema de trabajo de transferencia de metadatos