기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 대량 가져오기 및 내보내기 작업 수행
이 주제에서는 대량 가져오기 및 내보내기 작업을 수행하는 방법과 전송 작업의 오류를 처리하는 방법을 다룹니다. CLI 명령을 사용한 전송 작업의 예를 제공합니다.
AWS IoT TwinMaker API 참조에는 [ CreateMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateMetadataTransferJob.html) 및 기타 API 작업에 대한 정보가 포함되어 있습니다.
**Topics**
+ [metadataTransferJob 사전 조건](#tm-import-export-prereqs)
+ [IAM 권한](#tm-import-export-prereqs-permissions)
+ [대량 작업 실행](#tm-import-export-procedure)
+ [오류 처리](#tm-import-export-error-handling)
+ [메타데이터 템플릿 가져오기](#tm-import-metadata-templates)
+ [AWS IoT TwinMaker metadataTransferJob 예제](#tm-import-export-cli-examples)
## metadataTransferJob 사전 조건
metadataTransferJob을 실행하기 전에 다음 사전 조건을 완료하세요.
+ AWS IoT TwinMaker 워크스페이스를 생성합니다. 워크스페이스는 metadataTransferJob의 가져오기 대상 또는 내보내기 소스일 수 있습니다. 워크스페이스 생성에 대한 자세한 내용은 섹션을 참조하세요[워크스페이스 생성](twinmaker-gs-workspace.md).
+ 리소스를 저장할 Amazon S3 버킷을 생성합니다. Amazon S3 사용에 대한 자세한 내용은 [ Amazon S3란 무엇입니까?](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Welcome.html)를 참조하세요.
## IAM 권한
대량 작업을 수행할 때는 Amazon S3 AWS IoT SiteWise, AWS IoT TwinMaker및 로컬 시스템 간에 AWS 리소스를 교환할 수 있는 권한이 있는 IAM 정책을 생성해야 합니다. IAM 정책 생성에 대한 자세한 내용은 [IAM 정책 생성을](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_create.html) 참조하세요.
AWS IoT TwinMaker AWS IoT SiteWise 및 Amazon S3에 대한 정책 설명은 다음과 같습니다.
+ **AWS IoT TwinMaker 정책**:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:AbortMultipartUpload",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iottwinmaker:GetWorkspace",
"iottwinmaker:CreateEntity",
"iottwinmaker:GetEntity",
"iottwinmaker:UpdateEntity",
"iottwinmaker:GetComponentType",
"iottwinmaker:CreateComponentType",
"iottwinmaker:UpdateComponentType",
"iottwinmaker:ListEntities",
"iottwinmaker:ListComponentTypes",
"iottwinmaker:ListTagsForResource",
"iottwinmaker:TagResource",
"iottwinmaker:UntagResource"
],
"Resource": "*"
}
]
}
```
------
+ **AWS IoT SiteWise 정책**:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:AbortMultipartUpload",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iotsitewise:CreateAsset",
"iotsitewise:CreateAssetModel",
"iotsitewise:UpdateAsset",
"iotsitewise:UpdateAssetModel",
"iotsitewise:UpdateAssetProperty",
"iotsitewise:ListAssets",
"iotsitewise:ListAssetModels",
"iotsitewise:ListAssetProperties",
"iotsitewise:ListAssetModelProperties",
"iotsitewise:ListAssociatedAssets",
"iotsitewise:DescribeAsset",
"iotsitewise:DescribeAssetModel",
"iotsitewise:DescribeAssetProperty",
"iotsitewise:AssociateAssets",
"iotsitewise:DisassociateAssets",
"iotsitewise:AssociateTimeSeriesToAssetProperty",
"iotsitewise:DisassociateTimeSeriesFromAssetProperty",
"iotsitewise:BatchPutAssetPropertyValue",
"iotsitewise:BatchGetAssetPropertyValue",
"iotsitewise:TagResource",
"iotsitewise:UntagResource",
"iotsitewise:ListTagsForResource"
],
"Resource": "*"
}
]
}
```
------
+ **Amazon S3 정책**:
```
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:AbortMultipartUpload",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"
],
"Resource": "*"
}
```
또는 단일 Amazon S3 버킷에만 액세스하도록 Amazon S3 정책의 범위를 지정할 수 있습니다. 다음 정책을 참조하세요.
**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/*"
]
}
```
### metadataTransferJob에 대한 액세스 제어 설정
사용자가 액세스할 수 있는 작업의 종류를 제어하려면 호출에 사용되는 역할에 다음 IAM 정책을 추가합니다 AWS IoT TwinMaker.
**참고**
이 정책은 Amazon S3와 리소스를 주고 받는 AWS IoT TwinMaker 가져오기 및 내보내기 작업에 대한 액세스만 허용합니다.
```
{
"Effect": "Allow",
"Action": [
"iottwinmaker:*DataTransferJob*"
],
"Resource": "*",
"Condition": {
"StringLikeIfExists": {
"iottwinmaker:sourceType": [
"s3",
"iottwinmaker"
],
"iottwinmaker:destinationType": [
"iottwinmaker",
"s3"
]
}
}
}
```
## 대량 작업 실행
이 섹션에서는 대량 가져오기 및 내보내기 작업을 수행하는 방법을 다룹니다.
**Amazon S3에서 로 데이터 가져오기 AWS IoT TwinMaker**
1. AWS IoT TwinMaker metadataTransferJob 스키마를 사용하여 전송할 리소스를 지정합니다. 스키마 파일을 생성하여 Amazon S3 버킷에 저장합니다.
스키마 예제는 단원을 참조하십시오[메타데이터 템플릿 가져오기](#tm-import-metadata-templates).
1. 요청 본문을 생성하고 JSON 파일로 저장합니다. 요청 본문은 전송 작업의 소스와 대상을 지정합니다. Amazon S3 버킷을 소스로 지정하고 AWS IoT TwinMaker 워크스페이스를 대상으로 지정해야 합니다.
다음은 요청 본문의 예입니다.
```
{
"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"
}
}
}
```
요청 본문에 지정한 파일 이름을 기록합니다. 다음 단계에서 필요합니다. 이 예제에서 요청 본문의 이름은 입니다`createMetadataTransferJobImport.json`.
1. 다음 CLI 명령을 실행하여를 호출합니다`CreateMetadataTransferJob`(input-json 파일 이름을 요청 본문에 지정한 이름으로 바꿉니다).
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
그러면 metadataTransferJob이 생성되고 선택한 리소스 전송 프로세스가 시작됩니다.
**에서 Amazon S3 AWS IoT TwinMaker 로 데이터 내보내기**
1. 적절한 필터를 사용하여 JSON 요청 본문을 생성하여 내보낼 리소스를 선택합니다. 이 예제에서는 다음을 사용합니다.
```
{
"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"
}
}
}
```
`filters` 배열을 사용하면 내보낼 리소스를 지정할 수 있습니다. 이 예제에서는 `entity`, 및를 기준으로 필터링합니다`componentType`.
워크 AWS IoT TwinMaker 스페이스를 소스로 지정하고 Amazon S3 버킷을 메타데이터 전송 작업의 대상으로 지정해야 합니다.
요청 본문을 저장하고 파일 이름을 기록합니다. 다음 단계에서 필요합니다. 이 예제에서는 요청 본문의 이름을 지정했습니다`createMetadataTransferJobExport.json`.
1. 다음 CLI 명령을 실행하여를 호출합니다`CreateMetadataTransferJob`(input-json 파일 이름을 요청 본문에 지정한 이름으로 바꿉니다).
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
그러면 metadataTransferJob이 생성되고 선택한 리소스 전송 프로세스가 시작됩니다.
전송 작업의 상태를 확인하거나 업데이트하려면 다음 명령을 사용합니다.
+ 작업을 취소하려면 [ CancelMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CancelMetadataTransferJob.html) API 작업을 사용합니다. CancelMetadataTransferJob을 호출하면 API는 실행 중인 metadataTransferJob만 취소하며 이미 내보내거나 가져온 리소스는이 API 호출의 영향을 받지 않습니다.
+ 특정 작업에 대한 정보를 검색하려면 [ GetMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetMetadataTransferJob.html) API 작업을 사용합니다.
또는 다음 CLI 명령을 사용하여 기존 전송 작업에서 GetMetadataTransferJob을 호출할 수 있습니다.
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
존재하지 않는 AWS IoT TwinMaker 가져오기 또는 내보내기 작업에서 GetMetadataTransferJob을 호출하면 응답에 `ResourceNotFoundException` 오류가 발생합니다.
+ 현재 작업을 나열하려면 [ ListMetadataTransferJobs](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ListMetadataTransferJobs.html) API 작업을 사용합니다.
다음은를 destinationType AWS IoT TwinMaker 으로,를 sourceType으로 사용하여 ListMetadataTransferJobs`s3`를 호출하는 CLI 예제입니다. sourceType
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
**참고**
가져오기 또는 내보내기 작업의 소스 및 대상과 일치하도록 sourceType 및 destinationType 파라미터의 값을 변경할 수 있습니다.
이러한 API 작업을 호출하는 CLI 명령의 자세한 예는 섹션을 참조하세요[AWS IoT TwinMaker metadataTransferJob 예제](#tm-import-export-cli-examples).
전송 작업 중에 오류가 발생하면 섹션을 참조하세요[오류 처리](#tm-import-export-error-handling).
## 오류 처리
전송 작업을 생성하고 실행한 후 GetMetadataTransferJob을 호출하여 발생한 오류를 진단할 수 있습니다.
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1
```
작업 상태가 로 바뀌는 `COMPLETED`것을 확인하면 작업 결과를 확인할 수 있습니다. GetMetadataTransferJob은 다음 필드가 [https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_MetadataTransferJobProgress.html](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_MetadataTransferJobProgress.html) 포함된 라는 객체를 반환합니다.
+ **failedCount:** 전송 프로세스 중에 실패한 리소스 수를 나타냅니다.
+ **skippedCount:** 전송 프로세스 중에 건너뛴 리소스 수를 나타냅니다.
+ **succeededCount:** 전송 프로세스 중에 성공한 리소스 수를 나타냅니다.
+ **totalCount:** 전송 프로세스와 관련된 총 리소스 수를 나타냅니다.
또한 미리 서명된 URL이 포함된 reportUrl 요소가 반환됩니다. 전송 작업에 추가 조사하려는 오류가 있는 경우이 URL을 사용하여 전체 오류 보고서를 다운로드할 수 있습니다.
## 메타데이터 템플릿 가져오기
단일 대량 가져오기 작업으로 여러 구성 요소, componentTypes 또는 개체를 가져올 수 있습니다. 이 섹션의 예제에서는 이를 수행하는 방법을 보여줍니다.
------
#### [ template: Importing entities ]
개체를 가져오는 작업에 다음 템플릿 형식을 사용합니다.
```
{
"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 ]
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 ]
구성 요소를 가져오는 작업에 다음 템플릿 형식을 사용합니다.
```
{
"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 metadataTransferJob 예제
다음 명령을 사용하여 메타데이터 전송을 관리합니다.
+ [ CreateMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateMetadataTransferJob.html) API 작업.
CLI 명령 예제:
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://yourTransferFileName.json
```
+ 작업을 취소하려면 [ CancelMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CancelMetadataTransferJob.html) API 작업을 사용합니다.
CLI 명령 예제:
```
aws iottwinmaker cancel-metadata-transfer-job
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
CancelMetadataTransferJob을 호출하면 특정 메타데이터 전송 작업만 취소되며 이미 내보내거나 가져온 리소스는 영향을 받지 않습니다.
+ 특정 작업에 대한 정보를 검색하려면 [ GetMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetMetadataTransferJob.html) API 작업을 사용합니다.
CLI 명령 예제:
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1 \
```
+ 현재 작업을 나열하려면 [ ListMetadataTransferJobs](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ListMetadataTransferJobs.html) API 작업을 사용합니다.
JSON 파일을 사용하여 ListMetadataTransferJobs에서 반환한 결과를 필터링할 수 있습니다. CLI를 사용하여 다음 절차를 참조하세요.
1. CLI 입력 JSON 파일을 생성하여 사용할 필터를 지정합니다.
```
{
"sourceType": "s3",
"destinationType": "iottwinmaker",
"filters": [{
"workspaceId": "workspaceforbulkimport"
},
{
"state": "COMPLETED"
}]
}
```
파일을 저장하고 파일 이름을 기록합니다. CLI 명령을 입력할 때 필요합니다.
1. JSON 파일을 다음 CLI 명령의 인수로 사용합니다.
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```