metadataTransferJob 前提 IAM 許可執行大量作業錯誤處理匯入詮釋資料樣 AWS IoT TwinMaker metadataTransferJob 例子

執行大量匯入和匯出作業

本主題說明如何執行大量匯入和匯出作業，以及如何處理移轉工作中的錯誤。它提供了使用 CLI 命令傳輸作業的示例。

AWS IoT TwinMaker API 參考包含有關 CreateMetadataTransferJob和其他 API 動作的資訊。

主題

metadataTransferJob 前提
IAM 許可
執行大量作業
錯誤處理
匯入詮釋資料樣
AWS IoT TwinMaker metadataTransferJob 例子

metadataTransferJob 前提

請先完成下列先決條件，然後再執行 metadataTransferJob：

建立 AWS IoT TwinMaker 工作區。工作區可以是的匯入目標或匯出來源 metadataTransferJob。如需有關建立工作區的資訊，請參閱，建立工作區。
建立 Amazon S3 儲存貯體來存放資源。有關使用 Amazon S3 的更多信息，請參閱什麼是 Amazon S3？

IAM 許可

執行大量操作時，您需要建立具有許可的 IAM 政策，以便在 Amazon S3、 AWS IoT TwinMaker AWS IoT SiteWise、和本機電腦之間交換 AWS 資源。如需建立 IAM 政策的詳細資訊，請參閱建立 IAM 政策。

AWS IoT SiteWise 和 Amazon S3 的政策聲明如 AWS IoT TwinMaker下所示：

AWS IoT TwinMaker 政策：


{
    "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 政策：


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

注意

此政策僅允許存取將資源傳 AWS IoT TwinMaker 入和傳出 Amazon S3 的匯入和匯出任務。


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

執行大量作業

本節介紹如何執行大量匯入和匯出作業。

將資料從 Amazon S3 匯入到 AWS IoT TwinMaker

指定要使用結構描述傳輸的 AWS IoT TwinMaker metadataTransferJob 資源。建立您的結構描述檔案並將其存放在 Amazon S3 儲存貯體中。

如需資料架構範例，請參閱匯入詮釋資料樣。

建立要求主體並將其儲存為 JSON 檔案。要求主體會指定傳送工作的來源和目的地。請務必將 Amazon S3 儲存貯體指定為來源，並將 AWS IoT TwinMaker 工作區指定為目的地。

以下是要求主體的範例：


{
    "metadataTransferJobId": "your-transfer-job-Id",
    "sources": [{
        "type": "s3",
        "s3Configuration": {
            "location": "arn:aws:s3:::your-S3-bucket-name/your_import_data.json"
        }
    }],
    "destination": {
        "type": "iottwinmaker",
        "iotTwinMakerConfiguration": {
            "workspace": "arn:aws:iottwinmaker:us-east-1:111122223333:workspace/your-worksapce-name"
        }
    }
}

記錄您為請求主體提供的文件名，下一步將需要它。在這個例子中，請求主體被命名為createMetadataTransferJobImport.json。

運行以下 CLI 命令以調用CreateMetadataTransferJob（將輸入 json 文件名替換為您給請求主體的名稱）：
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
這會建立 metadataTransferJob 並開始移轉所選資源的程序。

將資料從 AWS IoT TwinMaker Amazon S3 匯出

使用適當的篩選器建立 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:::your-S3-bucket-location"
        }
    }
}

filters陣列可讓您指定要匯出的資源。在此範例中，我們篩選了entity、和componentType。

確保將您的工作 AWS IoT TwinMaker 區指定為來源，並將 Amazon S3 儲存貯體指定為中繼資料傳輸任務的目的地。

保存您的請求正文並記錄文件名，您將在下一步中使用它。在這個例子中，我們命名我們的請求體createMetadataTransferJobExport.json。

運行以下 CLI 命令以調用CreateMetadataTransferJob（將輸入 json 文件名替換為您給請求主體的名稱）：
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
這會建立 metadataTransferJob 並開始移轉所選資源的程序。

若要檢查或更新移轉工作的狀態，請使用下列指令：

若要取消工作，請使用 CancelMetadataTransferJobAPI 動作。當您呼叫時 CancelMetadataTransferJob，API 只會取消執行中 metadataTransferJob，且任何已匯出或匯入的資源都不會受此 API 呼叫的影響。
若要擷取特定工作的資訊，請使用 GetMetadataTransferJobAPI 動作。

或者，您也可以使用下列 CLI 指令呼叫 GetMetadataTransferJob 現有的傳送工作：
```
aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId
```
如果您呼叫 GetMetadataTransferJob 不存在的 AWS IoT TwinMaker 匯入或匯出工作，您會收到回應ResourceNotFoundException錯誤。
若要列出目前的工作，請使用 ListMetadataTransferJobsAPI 動作。

以下是呼叫 ListMetadataTransferJobs AWS IoT TwinMaker 作為目標類型和 s3 sourceType 的 CLI 範例：
```
aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
```
注意
您可以變更「sourceType」和「目的地類型」參數的值，以符合匯入或匯出工作的來源和目的地。

如需呼叫這些 API 動作的 CLI 命令的更多範例，請參閱AWS IoT TwinMaker metadataTransferJob 例子。

如果在傳送工作期間遇到任何錯誤，請參閱錯誤處理。

錯誤處理

建立並執行移轉工作之後，您可以呼叫 GetMetadataTransferJob以診斷發生的任何錯誤：


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

一旦您看到工作轉向的狀態COMPLETED，就可以驗證工作的結果。 GetMetadataTransferJob 會傳回名為的物件 MetadataTransferJobProgress，其中包含下列欄位：

失敗計數：表示在傳輸過程中失敗的資源數目。
跳過計數：表示在移轉處理期間略過的資源數目。
成功計數：表示在傳輸過程中成功的資源數目。
總計數：表示移轉處理中涉及的資源總數。

此外，會傳回包含預先簽署網址的 ReporTurl 元素。如果您的移轉工作有您想要進一步調查的錯誤，您可以使用此 URL 下載完整的錯誤報告。

匯入詮釋資料樣

您可以使用單一大量匯入作業匯入許多元件、元件類型或實體。本節中的範例說明如何執行此操作。

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": [
    {
      "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 例子

使用下列指令來管理中繼資料傳輸：

CreateMetadataTransferJobAPI 動作。

CLI 指令範例：


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

若要取消工作，請使用 CancelMetadataTransferJobAPI 動作。

CLI 指令範例：
```
aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id
```
通話時 CancelMetadataTransferJob，只會取消特定的中繼資料傳輸工作，而任何已匯出或匯入的資源都不會受到影響。

若要擷取特定工作的資訊，請使用 GetMetadataTransferJobAPI 動作。

CLI 指令範例：


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

若要列出目前的工作，請使用 ListMetadataTransferJobsAPI 動作。

您可以 ListMetadataTransferJobs 使用 JSON 檔案篩選傳回的結果。請參閱使用 CLI 的下列程序：
1. 建立 CLI 輸入 JSON 檔案以指定您要使用的篩選器：
```
{
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}
```
  保存並記錄文件名，輸入 CLI 命令時將需要它。
2. 使用 JSON 檔案做為下列 CLI 命令的引數：
```
aws iottwinmaker list-metadata-transfer-job --region us-east-1 \
--cli-input-json file://ListMetadataTransferJobsExample.json
```

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

批量操作

AWS IoT TwinMaker 詮釋資料傳送工作綱