pré-requisitos de metadados TransferJob Permissões do IAM Execute uma operação em massa Tratamento de erros Importar modelos de metadados AWS IoT TwinMaker exemplos de metadados TransferJob

Executando operações de importação e exportação em massa

Este tópico aborda como realizar operações de importação e exportação em massa e como lidar com erros em seus trabalhos de transferência. Ele fornece exemplos de tarefas de transferência usando comandos CLI.

A Referência AWS IoT TwinMaker da API contém informações sobre as CreateMetadataTransferJob e outras ações da API.

Tópicos

pré-requisitos de metadados TransferJob
Permissões do IAM
Execute uma operação em massa
Tratamento de erros
Importar modelos de metadados
AWS IoT TwinMaker exemplos de metadados TransferJob

pré-requisitos de metadados TransferJob

Preencha os seguintes pré-requisitos antes de executar um metadado: TransferJob

Crie um AWS IoT TwinMaker espaço de trabalho. O espaço de trabalho pode ser o destino de importação ou a fonte de exportação de um TransferJob metadado. Para obter informações sobre como criar um espaço de trabalho, consulte,Criar um espaço de trabalho.
Crie um bucket do Amazon S3 para armazenar recursos. Para obter mais informações sobre o uso do Amazon S3, consulte O que é o Amazon S3?

Permissões do IAM

Ao realizar operações em massa, você precisa criar uma política de IAM com permissões para permitir a troca de AWS recursos entre o Amazon S3,, AWS IoT TwinMaker AWS IoT SiteWise, e sua máquina local. Para obter mais informações sobre a criação de políticas do IAM, consulte Criação de políticas do IAM.

As declarações de política do Amazon S3 AWS IoT SiteWise e do Amazon S3 estão listadas aqui: AWS IoT TwinMaker

AWS IoT TwinMaker política:

AWS IoT SiteWise política:

Política do Amazon S3:


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

Como alternativa, você pode definir o escopo de sua política do Amazon S3 para acessar somente um único bucket do Amazon S3, consulte a política a seguir.

Política com escopo único de bucket do 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/*"
    ]
}

Definir controle de acesso para metadados TransferJob

Para controlar os tipos de trabalhos que um usuário pode acessar, adicione a seguinte política do IAM à função usada para chamar AWS IoT TwinMaker.

nota

Essa política só permite acesso a trabalhos de AWS IoT TwinMaker importação e exportação que transferem recursos de e para o Amazon S3.


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

Execute uma operação em massa

Esta seção aborda como realizar operações de importação e exportação em massa.

Importe dados do Amazon S3 para AWS IoT TwinMaker

Especifique os recursos que você deseja transferir usando o TransferJob esquema de AWS IoT TwinMaker metadados. Crie e armazene seu arquivo de esquema em seu bucket do Amazon S3.

Por exemplo, esquemas, consulteImportar modelos de metadados.
Crie um corpo de solicitação e salve-o como um arquivo JSON. O corpo da solicitação especifica a fonte e o destino do trabalho de transferência. Certifique-se de especificar seu bucket Amazon S3 como origem e seu AWS IoT TwinMaker espaço de trabalho como destino.

Veja a seguir um exemplo de corpo de solicitação:
```
{
    "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"
        }
    }
}
```
Registre o nome do arquivo que você deu ao corpo da solicitação. Você precisará dele na próxima etapa. Neste exemplo, o corpo da solicitação é chamadocreateMetadataTransferJobImport.json.
Execute o seguinte comando CLI para invocar CreateMetadataTransferJob (substitua o nome do arquivo input-json pelo nome que você deu ao corpo da solicitação):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
Isso cria metadados TransferJob e inicia o processo de transferência dos recursos selecionados.

Exportar dados de AWS IoT TwinMaker para Amazon S3

Crie um corpo de solicitação JSON com os filtros apropriados para escolher os recursos que você deseja exportar. Para este exemplo, usamos:


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

A filters matriz permite especificar quais recursos serão exportados. Neste exemplo, filtramos porentity, componentType e.

Certifique-se de especificar seu AWS IoT TwinMaker espaço de trabalho como origem e seu bucket do Amazon S3 como destino do trabalho de transferência de metadados.

Salve o corpo da solicitação e registre o nome do arquivo, você precisará dele na próxima etapa. Neste exemplo, nomeamos nosso corpo de solicitaçãocreateMetadataTransferJobExport.json.

Execute o seguinte comando CLI para invocar CreateMetadataTransferJob (substitua o nome do arquivo input-json pelo nome que você deu ao corpo da solicitação):
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
Isso cria metadados TransferJob e inicia o processo de transferência dos recursos selecionados.

Para verificar ou atualizar o status de um trabalho de transferência, use os seguintes comandos:

Para cancelar um trabalho, use a ação CancelMetadataTransferJob da API. Quando você chama CancelMetadataTransferJob, a API cancela apenas os metadados em execuçãoTransferJob, e quaisquer recursos já exportados ou importados não são afetados por essa chamada de API.
Para recuperar informações sobre um trabalho específico, use a ação da GetMetadataTransferJob API.

Ou você pode chamar um trabalho GetMetadataTransferJob de transferência existente com o seguinte comando CLI:
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
Se você chamar GetMetadataTransferJob um trabalho de AWS IoT TwinMaker importação ou exportação inexistente, receberá um ResourceNotFoundException erro em resposta.
Para listar os trabalhos atuais, use a ação ListMetadataTransferJobs da API.

Aqui está um exemplo de CLI que chama ListMetadataTransferJobs com AWS IoT TwinMaker como destinationType e s3 como sourceType:
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
nota
Você pode alterar os valores dos parâmetros sourceType e destinationType para que correspondam à origem e ao destino do trabalho de importação ou exportação.

Para ver mais exemplos de comandos da CLI que invocam essas ações de API, consulte. AWS IoT TwinMaker exemplos de metadados TransferJob

Se você encontrar algum erro durante o trabalho de transferência, consulteTratamento de erros.

Tratamento de erros

Depois de criar e executar um trabalho de transferência, você pode ligar GetMetadataTransferJob para diagnosticar qualquer erro que tenha ocorrido:


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

Depois de ver o estado do trabalhoCOMPLETED, você pode verificar os resultados do trabalho. GetMetadataTransferJob retorna um objeto chamado MetadataTransferJobProgress que contém os seguintes campos:

FailedCount: indica o número de recursos que falharam durante o processo de transferência.
SkippedCount: indica o número de recursos que foram ignorados durante o processo de transferência.
SucceededCount: indica o número de recursos que tiveram sucesso durante o processo de transferência.
TotalCount: indica a contagem total de recursos envolvidos no processo de transferência.

Além disso, é retornado um elemento reportUrl que contém um URL pré-assinado. Se seu trabalho de transferência tiver erros que você deseja investigar mais detalhadamente, você pode baixar um relatório de erro completo usando esse URL.

Importar modelos de metadados

Você pode importar vários componentes, tipos de componentes ou entidades com uma única operação de importação em massa. Os exemplos desta seção mostram como fazer isso.

template: Importing entities

Use o formato de modelo a seguir para um trabalho que importa 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

Use o formato de modelo a seguir para um trabalho que 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

Use o formato de modelo a seguir para um trabalho que importa 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 exemplos de metadados TransferJob

Use os seguintes comandos para gerenciar suas transferências de metadados:

CreateMetadataTransferJobAção da API.

Exemplo de comando CLI:


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

Para cancelar um trabalho, use a ação CancelMetadataTransferJob da API.

Exemplo de comando CLI:
```
aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
Quando você liga CancelMetadataTransferJob, ele cancela apenas um trabalho específico de transferência de metadados, e quaisquer recursos já exportados ou importados não são afetados.

Para recuperar informações sobre um trabalho específico, use a ação da GetMetadataTransferJob API.

Exemplo de comando CLI:


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

Para listar os trabalhos atuais, use a ação ListMetadataTransferJobs da API.

Você pode filtrar os resultados retornados ListMetadataTransferJobs usando um arquivo JSON. Veja o procedimento a seguir usando a CLI:
1. Crie um arquivo JSON de entrada CLI para especificar os filtros que você deseja usar:
```
{
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}
```
  Salve-o e registre o nome do arquivo, você precisará dele ao inserir o comando CLI.
2. Use o arquivo JSON como argumento para o seguinte comando da CLI:
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Operações em massa

AWS IoT TwinMaker esquema de trabalho de transferência de metadados