本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 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
恰好是`mp4``parquet`、或`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 `（或`AWS_REGION`环境变量）— 必填项
+ `--profile `— 从中选择一个已命名的个人资料 `~/.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`以处理:`InvalidRequestException``ResourceAlreadyExistsException`、`ResourceNotFoundException`、、`InternalFailureException`、`ThrottlingException`、`LimitExceededException`、`ConflictingOperationException`
## curl（原始 HTTPS）— CreateBulkImportJob
`CreateBulkImportJob``POST /jobs`位于 Amazon IoT SiteWise 数据平面端点上。每个请求都必须使用 Amazon 签名版本 4 (SigV4) 进行签名。
### 端点
```
https://data.iotsitewise..amazonaws.com/jobs
```
### HTTP 必填元素
| Element | 值 |
| --- | --- |
| 方法 | POST |
| 路径 | /jobs |
| 主机标头 | data.iotsitewise..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: " \
-H "Authorization: AWS4-HMAC-SHA256 \
Credential=/20260714/us-east-1/iotsitewise/aws4_request, \
SignedHeaders=content-type;host;x-amz-date;x-amz-security-token, \
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` → 其中之一`COMPLETED``COMPLETED_WITH_FAILURES`、或`FAILED`。当终端状态为`COMPLETED_WITH_FAILURES`或时`FAILED`，在中指定的 S3 URI 处检查错误报告对象`errorReportLocation.s3Uri`。