本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # CreateEnrichmentJob 用于场景发现 ## 先决条件 ### 场景探索工作空间和包含视频数据的数据集 `CreateEnrichmentJob`在现有工作空间 \+ 数据集上运行。在你可以给它打电话之前： + 工作空间必须存在且处于活动状态（未被删除）。 + 数据集必须存在于该工作空间内，并且必须包含要分析的 MP4 视频时间序列数据。如果您尚未将视频数据摄入到数据集中，则可使用`CreateBulkImportJob`此方法。 + 如果两个请求共享相同的作业类型、工作空间、属性和数据集，但指定的时间范围不同，则系统会接受这两个请求。 您的调用身份需要权限才能调用丰富任务 API、读取目标 workspace/dataset /时间序列资源以及（当工作空间使用客户管理的 KMS 密钥时）使用该密钥进行解密。 最低来电者权限政策： ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "InvokeEnrichmentJob", "Effect": "Allow", "Action": [ "iotsitewise:CreateEnrichmentJob", "iotsitewise:DescribeEnrichmentJob", "iotsitewise:CancelEnrichmentJob", "iotsitewise:ListEnrichmentJobs" ], "Resource": "*" }, { "Sid": "ReadWorkspaceAndDataset", "Effect": "Allow", "Action": [ "iotsitewise:DescribeWorkspace", "iotsitewise:DescribeDataset", "iotsitewise:ListDatasetDataSegments", "iotsitewise:ListTimeSeries", "iotsitewise:DescribeTimeSeries" ], "Resource": "*" }, { "Sid": "DecryptWorkspaceCMK", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-east-1:123456789012:key/00000000-0000-0000-0000-000000000000", "Condition": { "StringEquals": { "kms:ViaService": "iotsitewise.us-east-1.amazonaws.com" } } } ] } ``` 备注： + 当工作空间使用默认 Amazon 托管密钥`DecryptWorkspaceCMK`时，省略或缩小范围。使用客户管理的 KMS 密钥创建工作空间时，将其包括在内（使用正确的密钥 ARN）。 + 服务本身执行视频处理 — 您不传递服务角色（没有 st `jobRoleArn` yle 参数）。您只授予呼叫者足够的权限来提交和跟踪作业。 + `AccessDeniedException`来自API的几乎总是表明呼叫者身份缺少 Amazon IoT SiteWise 或KMS权限。 如果您的调用者是应用程序角色，请将该策略与运行代码的工作负载类型的信任策略配对： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "ec2.amazonaws.com", "ecs-tasks.amazonaws.com", "lambda.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` 将服务列表修剪为仅显示实际运行代码的工作负载类型。 ## Aliases 扩充范围仅限于数据集中的单个视频时间序列。您可以通过其系统分配`timeSeriesId`或按其`propertyAlias`来识别该时间序列。强烈建议使用别名，因为它们可读、稳定，并且与批量导入期间使用的别名约定一致。 对于车载摄像机，别名遵循与 MP4 导入相同的结构： ``` /car_120/front_left_camera/ ``` 在请求`timeSeriesId`中只指定其中一个`propertyAlias`或——切勿同时指定两者。`ValidationException`如果两者都提供，则 API 将返回。 ## 请求形状 ### 必需的顶级参数 | 参数 | Type | 注意 | | --- | --- | --- | | workspaceName | 字符串 | 场景探索工作空间的名称（1—64 个字符，^[a-zA-Z0-9\_-]\+$）。作为 URI 路径参数发送，而不是在 JSON 正文中发送。 | | jobConfiguration | 结构 | 配置联盟。目前必须仅包含一个成员:eventDetection. | ### 可选的顶级参数 | 参数 | Type | 注意 | | --- | --- | --- | | clientToken | 字符串 | 36—64 个字符，没有空格。等效性令牌 — 使用相同的令牌重新提交相同的请求会返回原始任务，而不会创建副本。使用 UUID。 | ### EnrichmentJobConfiguration （工会 — 正好是一个成员） 目前唯一支持的成员是`eventDetection`。 EventDetection 字段： | 字段 | 必填 | 注意 | | --- | --- | --- | | datasetId | 是 | 包含视频时间序列的场景发现数据集的 ID | | timeSeriesId | 其中之一 timeSeriesId/alias | System-generated 视频时间序列的标识符。36—73 个字符。 | | propertyAlias | 其中之一 timeSeriesId/alias | Human-readable 视频时间序列的别名（最多 2048 个字符）。首选。 | | trimSettings | 是 | { startTime, endTime }— 限制处理的时间窗口。两个边界都必须位于数据集的实际时间范围内。 | ### EnrichmentTrimSettings 两`startTime`者`endTime`都是 TimeInNanos 结构： ``` { "timeInSeconds": , "offsetInNanos": } ``` `endTime`必须严格大于`startTime`，并且两者都必须在数据集的数据范围内。 **注意** 只有在此时间范围内完全封装的数据段才会丰富。不支持对数据段进行部分扩展。 计算 seconds/nanos 拆分的 Python 助手： ``` import datetime def as_time_in_nanos(dt: datetime.datetime) -> dict: ts_ns = int(dt.timestamp() * 1_000_000_000) return { "timeInSeconds": ts_ns // 1_000_000_000, "offsetInNanos": ts_ns % 1_000_000_000 } ``` ### 响应 ``` { "jobId": "string", "status": "PENDING | RUNNING | COMPLETED | FAILED | TIMED_OUT | CANCELLED", "createdAt": "2026-07-14T17:00:00Z" } ``` 成功时的 HTTP 状态：200 正常。（与返回 202 不同`CreateBulkImportJob`，`CreateEnrichmentJob`返回 200。） ### 错误 | 错误 | 含义 | | --- | --- | | ValidationException | 参数无效（例如，同时指定了 time SeriesId 和 propertyAlias，endTime <= startTime） | | AccessDeniedException | 呼叫 Amazon IoT SiteWise 者缺少 KMS 权限 | | ConflictException | 重复的作业（相同 workspace/dataset/property/type）已经在运行 | | ResourceNotFoundException | 工作空间、数据集或时间序列不存在 | | ThrottlingException | 已超过请求率 | | LimitExceededException | 并发任务太多 | | InternalServerException | Service-side 失败 | ## 请求负载示例 将此另存为`enrichment-job-request.json`。`workspaceName`是通过 URL 路径（或通过 CLI 标志）传递的，而不是在 JSON 正文中传递的。 ``` { "jobConfiguration": { "eventDetection": { "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a", "propertyAlias": "/camera/front", "trimSettings": { "startTime": { "timeInSeconds": 1778275007, "offsetInNanos": 0 }, "endTime": { "timeInSeconds": 1778275307, "offsetInNanos": 0 } } } }, "clientToken": "c9c1d2b8-2f4b-4d6a-9b83-8b8a9b9d9a0a" } ``` 备注： + 1778275007 和 1778275307 表示 5 分钟的分析窗口。 + `clientToken`是可选的，但建议使用。如果您的呼叫者重试，请使用相同的令牌以避免创建重复的任务。 + 只有完全包含在`trimSettings`时间范围内的数据段才会丰富。与起始边界或终点边界重叠但未完全位于起点或终点边界内的分段将被忽略。 ## Amazon CLI 命令（使用输入文件）： ``` aws iotsitewise create-enrichment-job \ --region us-east-1 \ --workspace-name scenario_discovery_car120 \ --cli-input-json file://enrichment-job-request.json ``` 等效的行内表单： ``` aws iotsitewise create-enrichment-job \ --region us-east-1 \ --workspace-name ws-1778278606 \ --job-configuration '{ "eventDetection": { "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a", "propertyAlias": "/camera/front", "trimSettings": { "startTime": { "timeInSeconds": 1778275007 }, "endTime": { "timeInSeconds": 1778275307 } } } }' ``` CLI-only 标志： + `--region `（或`AWS_REGION`环境变量）— 必填项 + `--profile `— 从中选择一个已命名的个人资料 `~/.aws/config` + `--cli-input-json file://...`— 从 JSON 文件中读取请求正文 + `--generate-cli-skeleton`— 打印空白的请求模板 示例输出： ``` { "jobId": "9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6", "status": "PENDING", "createdAt": "2026-07-14T17:00:00Z" } ``` ## boto3 (Python) ``` import uuid import boto3 client = boto3.client("iotsitewise", region_name="us-east-1") response = client.create_enrichment_job( workspaceName="ws-1778278606", jobConfiguration={ "eventDetection": { "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a", "propertyAlias": "/camera/front", "trimSettings": { "startTime": {"timeInSeconds": 1778275007, "offsetInNanos": 0}, "endTime": {"timeInSeconds": 1778275307, "offsetInNanos": 0}, }, }, }, clientToken=str(uuid.uuid4()), ) print(response["jobId"], response["status"], response["createdAt"]) ``` boto3 特定注意事项： + `region_name`— 必填项、传递给`boto3.client()`或通过`AWS_REGION`/`AWS_DEFAULT_REGION` + 通过标准的 boto3 链（环境变量、角色`~/.aws/credentials`、 instance/task SSO）解析证书 + 所有请求参数都使用与 API 模型相匹配的 camelCase 名称。`workspaceName`以 kwarg 的形式传递；boto3 会将其放在 URL 路径上供你使用。 + 将调用打包`try / except botocore.exceptions.ClientError`以处理:`ValidationException`,`AccessDeniedException`,`ConflictException`,`ResourceNotFoundException`,,`ThrottlingException`,`LimitExceededException`, `InternalServerException` ## curl（原始 HTTPS） `CreateEnrichmentJob``POST /workspaces/{workspaceName}/enrichment-jobs`位于 Amazon IoT SiteWise 数据平面端点上。每个请求都必须使用 Amazon 签名版本 4 (SigV4) 进行签名。 ### 端点 ``` https://data.iotsitewise..amazonaws.com/workspaces//enrichment-jobs ``` ### HTTP 必填元素 | Element | 值 | | --- | --- | | 方法 | POST | | 路径 | /workspaces//enrichment-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 @enrichment-job-request.json \ https://data.iotsitewise.us-east-1.amazonaws.com/workspaces/scenario_discovery_car120/enrichment-jobs ``` ### Plain curl — 预签名请求框架 ``` curl -v -X POST \ "https://data.iotsitewise.us-east-1.amazonaws.com/workspaces/scenario_discovery_car120/enrichment-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 @enrichment-job-request.json ``` 有关完整的 SigV4 派生版本，请参阅有关签名 Amazon API 请求的 Amazon 文档。 示例 HTTP 响应： ``` HTTP/1.1 200 OK Content-Type: application/json { "jobId": "9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6", "status": "PENDING", "createdAt": "2026-07-14T17:00:00Z" } ``` ## 验证作业 ``` aws iotsitewise describe-enrichment-job \ --region us-east-1 \ --workspace-name scenario_discovery_car120 \ --job-id 9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6 ``` 状态进度：`PENDING`→ `RUNNING` → `COMPLETED`、`FAILED``TIMED_OUT`、或`CANCELLED`中的一个。 + `COMPLETED`— 嵌入式可用，视频可以通过场景探索的语义搜索进行搜索。 + `FAILED`— 检查`DescribeEnrichmentJob`响应中的`failureMessage`字段以了解详细信息。 ### 取消正在运行的作业 ``` aws iotsitewise cancel-enrichment-job \ --region us-east-1 \ --workspace-name scenario_discovery_car120 \ --job-id 9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6 ``` `CancelEnrichmentJob`是等效的 —— 只要任务尚未处于非取消的终端状态（、、`TIMED_OUT`），多次调用它就会`jobId`返回当前状态而不会出现错误`COMPLETED`，在这种情况下`FAILED`，它将返回。`ConflictException`如果已经开始向存储服务中提取数据，则取消 RUNNING 扩充任务可能会失败，但会出现异常。