View a markdown version of this page

CreateBulkImportJob 用于场景发现 - Amazon IoT SiteWise
先决条件Aliases请求形状请求有效载荷示例Amazon CLI — CreateBulkImportJobboto3 (Python) — CreateBulkImportJobcurl（原始 HTTPS）— CreateBulkImportJob验证作业
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

CreateBulkImportJob 用于场景发现

先决条件

来源和错误报告 S3 存储桶

您需要一个 S3 位置来存放要提取的数据文件，以及一个用于写入每个文件的错误报告的 S3 URI。来源和错误报告位置可以共享存储分区。

IAM 的角色是 Amazon IoT SiteWise 假设（工作RoleArn）

通过jobRoleArn参数将此 Amazon IoT SiteWise 角色传递给。 Amazon IoT SiteWise 假设它可以读取你的源对象并写入错误报告。

信任政策 — iotsitewise.amazonaws.com 允许扮演以下角色：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": { "Service": "iotsitewise.amazonaws.com" },
            "Action": "sts:AssumeRole"
        }
    ]
}

权限策略 — 授予 Amazon IoT SiteWise S3 访问权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

呼叫者的 IAM 角色和权限

您的调用身份（用户、角色或任务角色）需要权限才能调用 API 并将上一节中的角色传递给 Amazon IoT SiteWise。

最低来电者权限政策：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeBulkImport",
            "Effect": "Allow",
            "Action": [
                "iotsitewise:CreateBulkImportJob",
                "iotsitewise:DescribeBulkImportJob",
                "iotsitewise:ListBulkImportJobs"
            ],
            "Resource": "*"
        },
        {
            "Sid": "PassRoleToSiteWise",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "iotsitewise.amazonaws.com"
                }
            }
        },
        {
            "Sid": "StageSourceObjectsInS3",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:AbortMultipartUpload"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

该PassRoleToSiteWise声明使您可以安全地jobRoleArn移交 Amazon IoT SiteWise。如果没有iam:PassRole（和iam:PassedToService条件），CreateBulkImportJob则因授权错误而失败。

如果您的调用者是应用程序角色，请将该策略与该信任策略配对，这样 EC2、ECS 或 Lambda 工作负载就可以假定该策略：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com",
                    "ecs-tasks.amazonaws.com",
                    "lambda.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

将服务列表修剪为仅显示实际运行代码的工作负载类型。

Aliases

别名标识数据的物理或逻辑来源。持续使用它们可以让 Scenario Discovery 关联来自同一事件的视频、遥测和注释。

MP4 视频

Alias 可识别车辆和摄像头：/car_120/front_left_camera/

通过File.alias请求字段进行设置。

镶木地板遥测

别名是每行的，而不是每个文件的。您的 Parquet 文件必须包含以下列：

列 注意
timestamp_ns 自 Unix 时代以来的纳秒
alias 此遥测点的属性别名（例如，/car_120/speed/kph/）
value 标量值，编码为字符串
data_type 其中之一：布尔值、整数、双精度、时间戳、字符串

请勿设置 File.alias Parquet 遥测导入。

注解（OpenLabel 子集）

别名标识车辆：/car_120/annotations/

通过File.alias请求字段进行设置。

请求形状

必需的顶级参数（场景发现）

参数 Type 注意
jobName 字符串 1—256 个字符，每个字符是唯一的 account/region
jobRoleArn 字符串 先决条件部分中的 IAM 角色 ARN
files 列表 文件对象列表（至少一个）
errorReportLocation 结构 包含s3Uri（字符串，写入错误报告的 S3 URI）的对象
datasetId 字符串 场景发现数据集的 ID
workspaceName 字符串 场景探索工作空间的名称（1—64 个字符，）^[a-zA-Z0-9_-]+$

可选的顶级参数

参数 Type 注意
adaptiveIngestion 布尔值 必须始终false用于场景发现
deleteFilesAfterImport 布尔值 如果true，源 S3 对象将在成功摄取后删除

文件对象

字段 必填 注意
bucket 是 源 S3 存储桶名称（3—63 个字符）
key 是 Object key
versionId 否 特定的 S3 对象版本
alias 必填项 (MP4/annotation) File-level 属性别名（最多 2048 个字符）
startTime MP4 是必需的 将文件的数据锚定到挂钟时间。使用 nanos 格式：{"timeInSeconds": N, "offsetInNanos": N}

JobConfiguration.fileFormat

恰好是mp4parquet、或annotation：

{ "fileFormat": { "mp4": {} } }
{ "fileFormat": { "parquet": {} } }
{ "fileFormat": { "annotation": {} } }

对于在单个请求中导入多种文件类型的混合任务，每个文件对象可以指定自己的fileFormat字段。当存在文件级fileFormat时，它会覆盖该文件的任务级别。jobConfiguration.fileFormat这使您能够在单个批量导入任务中导入 MP4 视频、Parquet 遥测和注释文件。

响应

{
    "jobId": "string",
    "jobName": "string",
    "jobStatus": "PENDING | RUNNING | COMPLETED | FAILED | COMPLETED_WITH_FAILURES"
}

成功时的 HTTP 状态：202 已接受。

请求有效载荷示例

MP4 视频

{
    "jobName": "car120-front-left-camera-2026-07-14",
    "jobRoleArn": "arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    "files": [
        {
            "bucket": "your-bucket-name",
            "key": "video/car_120/2026-07-14/front_left_cam_0001.mp4",
            "alias": "/car_120/front_left_camera/",
            "startTime": {"timeInSeconds": 1720958400, "offsetInNanos": 0}
        }
    ],
    "errorReportLocation": {
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/"
    },
    "jobConfiguration": {
        "fileFormat": { "mp4": {} }
    },
    "datasetId": "your-dataset-id",
    "workspaceName": "scenario_discovery_car120",
    "adaptiveIngestion": false,
    "deleteFilesAfterImport": false
}

镶木地板遥测

{
    "jobName": "car120-telemetry-2026-07-14",
    "jobRoleArn": "arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    "files": [
        {
            "bucket": "your-bucket-name",
            "key": "telemetry/car_120/2026-07-14/part-0000.parquet"
        },
        {
            "bucket": "your-bucket-name",
            "key": "telemetry/car_120/2026-07-14/part-0001.parquet"
        }
    ],
    "errorReportLocation": {
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/"
    },
    "jobConfiguration": {
        "fileFormat": { "parquet": {} }
    },
    "datasetId": "your-dataset-id",
    "workspaceName": "scenario_discovery_car120",
    "adaptiveIngestion": false,
    "deleteFilesAfterImport": false
}

Parquet 文件中的每一行都包含：timestamp_ns（纳秒）、别名、值和 data_type。

注解（OpenLabel 子集）

{
    "jobName": "car120-annotations-2026-07-14",
    "jobRoleArn": "arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    "files": [
        {
            "bucket": "your-bucket-name",
            "key": "annotations/car_120/2026-07-14/labels.json",
            "alias": "/car_120/annotations/"
        }
    ],
    "errorReportLocation": {
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/"
    },
    "jobConfiguration": {
        "fileFormat": { "annotation": {} }
    },
    "datasetId": "your-dataset-id",
    "workspaceName": "scenario_discovery_car120",
    "adaptiveIngestion": false,
    "deleteFilesAfterImport": false
}

Amazon CLI — CreateBulkImportJob

命令（使用输入文件）：

aws iotsitewise create-bulk-import-job \
    --region us-east-1 \
    --cli-input-json file://bulk-import-request.json

等效的行内表单（MP4 示例）：

aws iotsitewise create-bulk-import-job \
    --region us-east-1 \
    --job-name car120-front-left-camera-2026-07-14 \
    --job-role-arn arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole \
    --files '[{"bucket":"your-bucket-name","key":"video/car_120/2026-07-14/front_left_cam_0001.mp4","alias":"/car_120/front_left_camera/","startTime":{"timeInSeconds":1720958400,"offsetInNanos":0}}]' \
    --error-report-location '{"s3Uri":"s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/"}' \
    --job-configuration '{"fileFormat":{"mp4":{}}}' \
    --dataset-id your-dataset-id \
    --workspace-name scenario_discovery_car120 \
    --no-adaptive-ingestion \
    --no-delete-files-after-import

CLI-only 标志：

  • --region <name>（或AWS_REGION环境变量）— 必填项

  • --profile <name>— 从中选择一个已命名的个人资料 ~/.aws/config

  • --cli-input-json file://...— 从 JSON 文件中读取整个请求正文

  • --generate-cli-skeleton— 打印空白的请求模板

boto3 (Python) — CreateBulkImportJob

代码 — MP4

import boto3

client = boto3.client("iotsitewise", region_name="us-east-1")

response = client.create_bulk_import_job(
    jobName="car120-front-left-camera-2026-07-14",
    jobRoleArn="arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    files=[
        {
            "bucket": "your-bucket-name",
            "key": "video/car_120/2026-07-14/front_left_cam_0001.mp4",
            "alias": "/car_120/front_left_camera/",
            "startTime": {"timeInSeconds": 1720958400, "offsetInNanos": 0},
        },
    ],
    errorReportLocation={
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/",
    },
    jobConfiguration={
        "fileFormat": {"mp4": {}},
    },
    datasetId="your-dataset-id",
    workspaceName="scenario_discovery_car120",
    adaptiveIngestion=False,
    deleteFilesAfterImport=False,
)

print(response["jobId"], response["jobStatus"])

代码 — 实木复合地板遥测

response = client.create_bulk_import_job(
    jobName="car120-telemetry-2026-07-14",
    jobRoleArn="arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    files=[
        {"bucket": "your-bucket-name", "key": "telemetry/car_120/2026-07-14/part-0000.parquet"},
        {"bucket": "your-bucket-name", "key": "telemetry/car_120/2026-07-14/part-0001.parquet"},
    ],
    errorReportLocation={
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/",
    },
    jobConfiguration={"fileFormat": {"parquet": {}}},
    datasetId="your-dataset-id",
    workspaceName="scenario_discovery_car120",
    adaptiveIngestion=False,
)

代码 — 注释

response = client.create_bulk_import_job(
    jobName="car120-annotations-2026-07-14",
    jobRoleArn="arn:aws:iam::123456789012:role/UATSiteWiseBulkImportRole",
    files=[
        {
            "bucket": "your-bucket-name",
            "key": "annotations/car_120/2026-07-14/labels.json",
            "alias": "/car_120/annotations/",
        },
    ],
    errorReportLocation={
        "s3Uri": "s3://your-bucket-name/bulk-import-errors/car_120/2026-07-14/",
    },
    jobConfiguration={"fileFormat": {"annotation": {}}},
    datasetId="your-dataset-id",
    workspaceName="scenario_discovery_car120",
    adaptiveIngestion=False,
)

boto3 专属笔记

  • region_name— 必填项、传递给boto3.client()或通过AWS_REGION/设置 AWS_DEFAULT_REGION

  • 通过标准的 boto3 链（环境变量、角色~/.aws/credentials、 instance/task SSO）解析证书

  • 所有请求参数都使用与 API 模型相匹配的 camelCase 名称

  • 将调用打包try / except botocore.exceptions.ClientError以处理:InvalidRequestExceptionResourceAlreadyExistsException、ResourceNotFoundException、、InternalFailureException、ThrottlingException、LimitExceededException、ConflictingOperationException

curl（原始 HTTPS）— CreateBulkImportJob

CreateBulkImportJobPOST /jobs位于 Amazon IoT SiteWise 数据平面端点上。每个请求都必须使用 Amazon 签名版本 4 (SigV4) 进行签名。

端点

https://data.iotsitewise.<region>.amazonaws.com/jobs

HTTP 必填元素

Element 值
方法 POST
路径 /jobs
主机标头 data.iotsitewise.<region>.amazonaws.com
Content-Type 标题 application/json
X-Amz-Date 标题 ISO 8601 基本格式（例如，）20260714T170000Z
X-Amz-Security-Token 仅在使用临时证书 (STS) 时才需要
Authorization 标头 SigV4 签名（服务 = iotsitewise）
Body JSON 请求负载

推荐：awscurl

awscurl \
    --service iotsitewise \
    --region us-east-1 \
    -X POST \
    -H "Content-Type: application/json" \
    -d @bulk-import-request.json \
    https://data.iotsitewise.us-east-1.amazonaws.com/jobs

Plain curl — 预签名请求框架

curl -v -X POST \
    "https://data.iotsitewise.us-east-1.amazonaws.com/jobs" \
    -H "Host: data.iotsitewise.us-east-1.amazonaws.com" \
    -H "Content-Type: application/json" \
    -H "X-Amz-Date: 20260714T170000Z" \
    -H "X-Amz-Security-Token: <SESSION_TOKEN_IF_TEMP_CREDS>" \
    -H "Authorization: AWS4-HMAC-SHA256 \
Credential=<ACCESS_KEY_ID>/20260714/us-east-1/iotsitewise/aws4_request, \
SignedHeaders=content-type;host;x-amz-date;x-amz-security-token, \
Signature=<COMPUTED_HEX_SIGNATURE>" \
    --data-binary @bulk-import-request.json

有关完整的 SigV4 派生版本，请参阅有关签名 Amazon API 请求的 Amazon 文档。

验证作业

aws iotsitewise describe-bulk-import-job \
    --region us-east-1 \
    --job-id d1e2f3a4-5678-90ab-cdef-1234567890ab

jobStatus进度：PENDING→ RUNNING → 其中之一COMPLETEDCOMPLETED_WITH_FAILURES、或FAILED。当终端状态为COMPLETED_WITH_FAILURES或时FAILED，在中指定的 S3 URI 处检查错误报告对象errorReportLocation.s3Uri。