IMM支持多种数据输出,其中有些处理时间会比较长,无法在一次同步请求中返回。因此IMM提供了一类API来异步处理这种请求,这类API通常以CreateXXXTask
命名,同时提供了结果获取的消息通知方式。
任务处理流程
开发者上传源数据至阿里云对象存储OSS。
开发者调用IMM API接口
CreateXXXTask
发起异步任务处理请求。IMM从开发者指定的OSS地址获取源数据进行数据处理。
IMM将数据处理结果写回开发者指定的OSS地址。
IMM处理完数据后,将任务状态发送至开发者指定的MNS或RocketMQ。
MNS或RocketMQ将消息推送至开发者的服务中。
任务输入输出
输入数据参数一般以Source命名,包括如下参数:
SourceURI:数据源地址,目前仅支持OSS URI。
Sources:多个输入URI地址数组。
Source:多个输入URI对象。
输出数据参数一般以Target命名,包括如下参数:
TargetURI:目标地址,该地址支持模板语法。
TargetURIPrefix:目标地址前缀。
Target:多个输出URI对象。
输入数据和输出数据需要和IMM在同一个地域。
OSS URI
OSS URI是用来定位唯一的一个OSS资源,其格式为oss://<bucket>/<object>
,例如oss://test-bucket/test-object/test.docx
。
Bucket为和当前项目处于同一地域的OSS Bucket名称,Object为包含文件扩展名的文件完整路径。
常见的错误输入格式:
http://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx
oss://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx
TargetURI模板
TargetURI模板是在URI提供一些占位符,使用时用实际的值去替换占位符,从而动态生成实际的URI地址。例如oss://{bucket}/{tags.custom}/{dirname}/{barename}.{autoext}
。
关于TargetURI的更多信息,请参见TargetURI 模板。
授权机制
异步任务处理的输入数据和输出数据均为开发者提供的地址,需要授权IMM服务输入数据的读权限和输出数据的写权限。这些权限来自于ProjectName参数,在CreateProject - 创建项目接口中,通过参数ServiceRole指定了一个授权给IMM的服务角色(默认为AliyunIMMDefaultRole,开通服务时自动创建),IMM在异步任务处理中会通过扮演这个服务角色获取和上传数据。
获取任务状态
通过MNS或RocketMQ获取任务状态
如任务处理流程中的介绍,开发者可以通过设置MNS或RocketMQ来接受IMM的任务处理状态,这也是IMM推荐的使用方式。MNS通知消息格式请参见异步通知消息格式。
MNS或RocketMQ需要和IMM在同一个地域。
通过Notification参数指定MNS或RocketMQ配置接收异步消息通知(推荐)
MNS:通过Notification参数中的MNS参数指定MNS通知地址和主题接收异步消息通知。
{ "Notification": { "MNS": { "Endpoint": "MNS消息通知地址", "TopicName": "MNS消息通知主题" } } }
RocketMQ:通过Notification参数中的RocketMQ参数指定RocketMQ通知地址、主题和实例ID接收异步消息通知。
{ "Notification": { "RocketMQ": { "Endpoint": "RocketMQ消息通知地址", "TopicName": "RocketMQ消息通知主题", "InstanceId": "RocketMQ消息通知实例Id" } } }
通过NotifyEndpoint和NotifyTopicName两个参数指定MNS接收地址和主题接收异步消息通知
NotifyEndpoint:MNS消息通知地址,默认为调用者的MNS地址。
NotifyTopicName:MNS消息通知主题,为空则不会发送消息通知。
通过GetTask接口获取任务状态
IMM同样也提供GetTask - 获取任务信息接口来查询任务状态。
通过轮询GetTask - 获取任务信息直到任务完成同样可以获取到任务状态,但这种方式的效率很低,在任务处理时间比较长的场景中,需要大量的GetTask - 获取任务信息调用,如果堆积的任务比较多,可能会触发全局限流,影响其他接口的调用。此外,轮询有时间间隔,而任务完成可能在间隔中的任意一个时间,平均需要延迟半个时间的时间间隔才能获取到任务状态。因此不建议在实际生产中使用该接口来获取任务状态。
任务开始执行后,任务信息只保存7天,超过7天则无法再获取。
标签机制
请求参数中的Tags参数提供了一种标签机制,此参数可以在以下场景中使用:
开发者可以设置自定义数据,这些数据会在MNS消息中返回。
Tags可以作为搜索条件搜索任务。
Tags可以作为变量在TargetURI中使用。