View a markdown version of this page

Durchführung von Massenimport- und Exportvorgängen - AWS IoT TwinMaker
TransferJob Voraussetzungen für MetadatenIAM-BerechtigungenFühren Sie einen Massenvorgang ausFehlerbehandlungMetadaten-Vorlagen importierenAWS IoT TwinMaker TransferJob Beispiele für Metadaten

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Durchführung von Massenimport- und Exportvorgängen

In diesem Thema wird beschrieben, wie Sie Massenimport- und Exportvorgänge durchführen und wie Sie mit Fehlern bei Ihren Übertragungsaufträgen umgehen. Es enthält Beispiele für Übertragungsaufträge mithilfe von CLI-Befehlen.

Die AWS IoT TwinMaker API-Referenz enthält Informationen zu den CreateMetadataTransferJob und anderen API-Aktionen.

TransferJob Voraussetzungen für Metadaten

Bitte erfüllen Sie die folgenden Voraussetzungen, bevor Sie Metadaten ausführenTransferJob:

  • Erstellen Sie einen AWS IoT TwinMaker Arbeitsbereich. Der Workspace kann das Importziel oder die Exportquelle für Metadaten seinTransferJob. Informationen zum Erstellen eines Workspace finden Sie unterEinen Workspace erstellen.

  • Erstellen Sie einen Amazon S3-Bucket zum Speichern von Ressourcen. Weitere Informationen zur Verwendung von Amazon S3 finden Sie unter Was ist Amazon S3?

IAM-Berechtigungen

Wenn Sie Massenvorgänge ausführen, müssen Sie eine IAM-Richtlinie mit Berechtigungen erstellen, die den Austausch von AWS Ressourcen zwischen Amazon S3, AWS IoT TwinMaker AWS IoT SiteWise, und Ihrem lokalen Computer ermöglichen. Weitere Informationen zum Erstellen von IAM-Richtlinien finden Sie unter Erstellen von IAM-Richtlinien.

Die Richtlinienerklärungen für AWS IoT TwinMaker AWS IoT SiteWise und Amazon S3 sind hier aufgeführt:

  • AWS IoT TwinMaker Richtlinie:

    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 Richtlinie:

    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-Richtlinie:

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

    Alternativ können Sie Ihre Amazon S3-Richtlinie so anpassen, dass nur auf einen einzelnen Amazon S3-Bucket zugegriffen wird. Weitere Informationen finden Sie in der folgenden Richtlinie.

    Amazon S3-Richtlinie für einen einzelnen 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/*"
    ]
}

Richten Sie die Zugriffskontrolle für Metadaten ein TransferJob

Um zu steuern, auf welche Art von Jobs ein Benutzer zugreifen kann, fügen Sie der Rolle, die für den Aufruf AWS IoT TwinMaker verwendet wird, die folgende IAM-Richtlinie hinzu.

Anmerkung

Diese Richtlinie erlaubt nur den Zugriff auf AWS IoT TwinMaker Import- und Exportaufträge, die Ressourcen von und zu Amazon S3 übertragen.

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

Führen Sie einen Massenvorgang aus

In diesem Abschnitt wird beschrieben, wie Sie Massenimport- und Exportvorgänge durchführen.

Importieren Sie Daten von Amazon S3 nach AWS IoT TwinMaker

  1. Geben Sie mithilfe des AWS IoT TwinMaker TransferJob Metadatenschemas die Ressourcen an, die Sie übertragen möchten. Erstellen und speichern Sie Ihre Schemadatei in Ihrem Amazon S3-Bucket.

    Beispiele für Schemas finden Sie unterMetadaten-Vorlagen importieren.

  2. Erstellen Sie einen Anforderungstext und speichern Sie ihn als JSON-Datei. Der Anforderungstext gibt die Quelle und das Ziel für den Übertragungsauftrag an. Stellen Sie sicher, dass Sie Ihren Amazon S3-Bucket als Quelle und Ihren AWS IoT TwinMaker Workspace als Ziel angeben.

    Das Folgende ist ein Beispiel für einen Anfragetext:

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

    Notieren Sie sich den Dateinamen, den Sie Ihrem Anfragetext gegeben haben. Sie benötigen ihn im nächsten Schritt. In diesem Beispiel wird der Anfragetext benanntcreateMetadataTransferJobImport.json.

  3. Führen Sie zum Aufrufen den folgenden CLI-Befehl aus CreateMetadataTransferJob (ersetzen Sie den Namen der input-json-Datei durch den Namen, den Sie Ihrem Anforderungstext gegeben haben):

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

    Dadurch werden Metadaten erstellt TransferJob und der Prozess der Übertragung Ihrer ausgewählten Ressourcen gestartet.

Exportieren Sie Daten von AWS IoT TwinMaker zu Amazon S3

  1. Erstellen Sie einen JSON-Anforderungstext mit den entsprechenden Filtern, um die Ressourcen auszuwählen, die Sie exportieren möchten. Für dieses Beispiel verwenden wir:

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

    Mit dem filters Array können Sie angeben, welche Ressourcen exportiert werden. In diesem Beispiel filtern wir nachentity, undcomponentType.

    Stellen Sie sicher, dass Sie Ihren AWS IoT TwinMaker Workspace als Quelle und Ihren Amazon S3-Bucket als Ziel des Metadaten-Übertragungsauftrags angeben.

    Speichern Sie Ihren Anfragetext und notieren Sie den Dateinamen. Sie benötigen ihn im nächsten Schritt. Für dieses Beispiel haben wir unseren Anfragetext benanntcreateMetadataTransferJobExport.json.

  2. Führen Sie zum Aufrufen den folgenden CLI-Befehl aus CreateMetadataTransferJob (ersetzen Sie den Namen der input-json-Datei durch den Namen, den Sie Ihrem Anforderungstext gegeben haben):

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

    Dadurch werden Metadaten erstellt TransferJob und der Prozess der Übertragung Ihrer ausgewählten Ressourcen gestartet.

Verwenden Sie die folgenden Befehle, um den Status eines Übertragungsauftrags zu überprüfen oder zu aktualisieren:

  • Verwenden Sie die CancelMetadataTransferJob API-Aktion, um einen Job abzubrechen. Wenn Sie aufrufen CancelMetadataTransferJob, storniert die API nur laufende MetadatenTransferJob, und alle bereits exportierten oder importierten Ressourcen sind von diesem API-Aufruf nicht betroffen.

  • Verwenden Sie die GetMetadataTransferJob API-Aktion, um Informationen zu einem bestimmten Job abzurufen.

    Oder Sie können einen vorhandenen Übertragungsauftrag mit dem folgenden CLI-Befehl aufrufen GetMetadataTransferJob :

    aws iottwinmaker get-metadata-transfer-job --job-id ExistingJobId

    Wenn Sie einen nicht vorhandenen AWS IoT TwinMaker Import- oder Exportauftrag aufrufen GetMetadataTransferJob , erhalten Sie als Antwort eine ResourceNotFoundException Fehlermeldung.

  • Verwenden Sie die ListMetadataTransferJobs API-Aktion, um aktuelle Jobs aufzulisten.

    Hier ist ein CLI-Beispiel, das ListMetadataTransferJobs AWS IoT TwinMaker als destinationType und s3 als sourceType aufgerufen wird:

    aws iottwinmaker list-metadata-transfer-jobs --destination-type iottwinmaker --source-type s3
    Anmerkung

    Sie können die Werte für die Parameter sourceType und destinationType so ändern, dass sie der Quelle und dem Ziel Ihres Import- oder Exportauftrags entsprechen.

Weitere Beispiele für CLI-Befehle, die diese API-Aktionen aufrufen, finden Sie unter. AWS IoT TwinMaker TransferJob Beispiele für Metadaten

Wenn Sie während des Übertragungsauftrags auf Fehler stoßen, finden Sie unterFehlerbehandlung.

Fehlerbehandlung

Nachdem Sie einen Übertragungsauftrag erstellt und ausgeführt haben, können Sie ihn aufrufen, GetMetadataTransferJob um alle aufgetretenen Fehler zu diagnostizieren:

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

Sobald Sie den Status des Auftrags sehenCOMPLETED, können Sie die Ergebnisse des Auftrags überprüfen. GetMetadataTransferJob gibt ein Objekt mit MetadataTransferJobProgress dem Namen zurück, das die folgenden Felder enthält:

  • FailedCount: Gibt die Anzahl der Ressourcen an, die während des Übertragungsvorgangs ausgefallen sind.

  • SkippedCount: Gibt die Anzahl der Ressourcen an, die während des Übertragungsvorgangs übersprungen wurden.

  • SucceededCount: Gibt die Anzahl der Ressourcen an, die während des Übertragungsvorgangs erfolgreich waren.

  • totalCount: Gibt die Gesamtzahl der Ressourcen an, die am Übertragungsprozess beteiligt sind.

Zusätzlich wird ein ReportUrl-Element zurückgegeben, das eine vorsignierte URL enthält. Wenn Ihr Übertragungsauftrag Fehler enthält, die Sie weiter untersuchen möchten, können Sie über diese URL einen vollständigen Fehlerbericht herunterladen.

Metadaten-Vorlagen importieren

Sie können viele Komponenten, ComponentTypes oder Entitäten mit einem einzigen Massenimportvorgang importieren. Die Beispiele in diesem Abschnitt zeigen, wie das geht.

template: Importing entities

Verwenden Sie das folgende Vorlagenformat für einen Job, der Entitäten importiert:

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

Verwenden Sie das folgende Vorlagenformat für einen Job, der ComponentTypes importiert:

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

Verwenden Sie das folgende Vorlagenformat für einen Job, der Komponenten importiert:

{
  "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 Beispiele für Metadaten

Verwenden Sie die folgenden Befehle, um Ihre Metadatentransfers zu verwalten:

  • CreateMetadataTransferJobAPI-Aktion.

    Beispiel für einen CLI-Befehl:

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

  • Verwenden Sie die CancelMetadataTransferJob API-Aktion, um einen Job abzubrechen.

    Beispiel für einen CLI-Befehl:

    aws iottwinmaker cancel-metadata-transfer-job 
--region us-east-1 \
--metadata-transfer-job-id job-to-cancel-id

    Wenn Sie aufrufen CancelMetadataTransferJob, wird nur ein bestimmter Metadaten-Übertragungsauftrag storniert, und alle bereits exportierten oder importierten Ressourcen sind nicht betroffen.

  • Verwenden Sie die GetMetadataTransferJob API-Aktion, um Informationen zu einem bestimmten Job abzurufen.

    Beispiel für einen CLI-Befehl:

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

  • Verwenden Sie die ListMetadataTransferJobs API-Aktion, um aktuelle Jobs aufzulisten.

    Sie können die zurückgegebenen Ergebnisse ListMetadataTransferJobs mithilfe einer JSON-Datei filtern. Sehen Sie sich das folgende Verfahren mit der CLI an:

    1. Erstellen Sie eine CLI-JSON-Eingabedatei, um die Filter anzugeben, die Sie verwenden möchten:

      {
    "sourceType": "s3",
    "destinationType": "iottwinmaker",
    "filters": [{
        "workspaceId": "workspaceforbulkimport"
    },
    {
        "state": "COMPLETED"
    }]
}

      Speichern Sie es und notieren Sie den Dateinamen. Sie benötigen ihn, wenn Sie den CLI-Befehl eingeben.

    2. Verwenden Sie die JSON-Datei als Argument für den folgenden CLI-Befehl:

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