列出相机中的所有图片/所有视频/所有图片和视频。可能需要发出几次请求才能列出所有文件。此命令是在 API 级别 2 中添加的。
如果摄像头不支持所请求的参数,则摄像头必须返回硬件可用的最大功能。例如,一个罕见的情况可能是请求:{entryCount: 500, maxSize: 2000}
。响应应基于相机支持的最大功能(例如 {entryCount: 100, maxSize: 200}
),而不是抛出错误。对于所有其他情况,请抛出错误;例如,当请求为 {entryCount: 500, maxSize: -500}
时,应抛出错误 invalidParameterValue
,因为 maxSize
为负数。
参数
- fileType:要列出的文件类型,应为以下三项中的任何一项:“image”“video”和“all”。
- startPosition:(可选)列表中要返回的第一个文件的位置。如果省略,则起始位置为 0,表示第一个文件。如果它大于最后一个文件的位置,则返回结果中包含空条目的正常响应,而不是错误响应。
- entryCount:要返回的条目数。如果超过剩余文件数量,则只需返回包含实际剩余文件的正常响应,而不是错误响应。
- maxThumbSize:缩略图的大小上限;max(thumbnail_width,thumbnail_width,thumbnail_height)。当客户端想要从结果中省略缩略图时,系统会将其设置为
null
。
成果
- entries:图片属性列表。每个条目都应包含以下字段,但纬度和经度除外(这两个是选填字段):
- name:文件的名称。
- fileUrl:文件的绝对网址,可用于直接从相机下载。
- size:文件的大小(以字节为单位)。
- dateTimeZone:文件的日期、时间和时区,格式为
YYYY:MM:DD HH:MM:SS+(-)HH:MM
。时间采用 24 小时制。日期和时间用一个空白字符分隔。时区与世界协调时间 (UTC) 的偏差。请注意,这表示视频捕获结束。 - lat::(可选)文件拍摄时位置的纬度。
- lng::(可选)文件拍摄时位置的经度。
- width:图片或每个视频帧的宽度。
- height:图片或每个视频帧的高度。
- thumbnail:文件的缩略图的 Base64 编码字符串(当
maxThumbSize != null
时)。 - isProcessed:一个布尔值,表示文件是已处理(例如拼接)还是只是预览。除非
delayProcessing
设置为 true,否则此值默认为 true。如果存在经过处理的图片,则不应列出相应的预览图片(即使存在),否则应列出预览图片。 - previewUrl:如果
delayProcessing
不受支持、isProcessed
设为 false 或从未生成预览图片作为中间结果,则默认为空字符串,否则,该值为与最终图片对应的预览图片的网址。它用于在预览图片与最终图片之间建立对应关系。
- totalEntries:存储空间中
fileType
的条目总数,例如,如果 fileType 为“image”,就是存储空间中的图片总数。
错误数
- missingParameter:未指定任何必需参数;例如,未指定
entryCount
。 - invalidParameterName:输入参数名称无法识别。
- invalidParameterValue:系统可识别输入参数名称,但其值无效;例如,
entryCount
为负数,或其数据类型不正确。
命令 I/O | |
---|---|
命令输入 | { "parameters": { "entryCount": 50, "maxThumbSize": 100 } } |
命令输出 | { "results": { "entries": [ { "name": "abc", "fileUrl": "file URL", "size": file size, # of bytes, "dateTimeZone": "2014:12:27 08:00:00+08:00", "lat": 50.5324, "lng": -120.2332, "width": 2000, "height": 1000, "thumbnail": "ENCODEDSTRING", "isProcessed": true, "previewUrl": "" } ... { ... } ], "totalEntries": 250 } } |
命令输出(错误) | { "error": { "code": "invalidParameterValue", "message": "Parameter entryCount is negative." } } |