翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 一括インポートおよびエクスポートオペレーションの実行
このトピックでは、一括インポートおよびエクスポートオペレーションを実行する方法と、転送ジョブのエラーを処理する方法について説明します。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 TwinMaker、ローカルマシン間の AWS リソースの交換を許可するアクセス許可を持つ AWS IoT SiteWise 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": "*"
}
```
または、1 つの 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 API ](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CancelMetadataTransferJob.html)アクションを使用します。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 `s3`として ListMetadataTransferJobs を呼び出す CLI の例を次に示します。
```
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 を使用して完全なエラーレポートをダウンロードできます。
## メタデータテンプレートをインポートする
1 回の一括インポート操作で、多くのコンポーネント、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 API ](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CancelMetadataTransferJob.html)アクションを使用します。
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 アクションを使用します。
ListMetadataTransferJobs によって返された結果は、JSON ファイルを使用してフィルタリングできます。CLI を使用して次の手順を参照してください。
1. 使用するフィルターを指定する CLI 入力 JSON ファイルを作成します。
```
{
"sourceType": "s3",
"destinationType": "iottwinmaker",
"filters": [{
"workspaceId": "workspaceforbulkimport"
},
{
"state": "COMPLETED"
}]
}
```
保存してファイル名を記録します。CLI コマンドを入力するときに必要になります。
1. 次の CLI コマンドの引数として JSON ファイルを使用します。
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```