Vuforia Web Query API使您能够将提交的图像与云数据库进行匹配。它通过HTTP接收单个图像,并返回任何匹配结果的列表。
Query Web API在与授权标头中提供的客户端访问密钥关联的云数据库中执行云识别搜索。
身份验证
所有对Web Query API的请求都需要进行身份验证。身份验证方案在Vuforia Web API身份验证遵循Vuforia Web Services(VWS)方案。按照本文中描述的步骤进行API调用,同时替换服务器访问密钥服务器访问密钥
和服务器密钥
使用客户端访问密钥»服务器密钥
和客户端密钥
.
提交查询
通过包含下面列出的所需请求来执行图像识别查询。在请求头中包含内容类型的授权、日期和声明。请求正文可以由三个字段组成,用于在查询中提交图像识别规范。
请求方法:邮政
请求URL: cloudreco.vuforia.com/v1/query
请求标头:
- 授权(身份验证VWS协议要求,见上文身份验证)。
- 内容类型(多部分/表单数据)。
- 可选:Accept(application/json)。
- 日期(身份验证协议要求)。
请求正文:请求正文的格式为multipart/form-data。表2:Query Request Body中列出了预期字段。
笔记:
- 建议的图像设置(最佳识别性能和延迟):JPEG,长图像侧640像素,压缩质量50-75。
- 最大图像大小:2.1 MPixel。JPEG为512 KB,PNG为2MB。
- 文本字段应采用UTF-8编码。
- API接受具有未知数据字段的请求,并忽略未知字段。
- API拒绝数据字段缺失、格式错误、超出范围或不完整的请求。
查询请求正文
字段
|
内容类型
|
类型
|
强制性的
|
说明
|
形象
|
image/jpeg或image/png
|
jpg或png格式的二进制图像文件
|
是的
|
查询图像。有关建议和最大尺寸,请参见上述注释。
|
最大数量结果
|
文本/纯文本
|
国际[1..10]
|
不
|
指示要返回的最大匹配目标数。默认值为1(如果有任何目标完全匹配,则返回最佳匹配)
|
包括目标数据
|
文本/纯文本
|
字符串
|
不
|
指示是否应为匹配的目标返回target_data记录。接受的值为top(默认值,对于排名靠前的匹配,只返回target_data)、none(不返回target_data)和all(对于所有匹配的目标)
|
响应消息
返回的响应将包含查询ID、匹配目标列表以及查询是否成功,
响应标题:
- 内容类型(application/json或其他,用于未指定主体的某些故障情况)。
响应状态代码:
响应正文:
- 成功案例:JSON对象,字段如表3所示:查询响应正文。
- 失败案例:根据失败的类型,可能会有表3所示的JSON主体:查询响应主体(没有结果字段),也可能会有任意主体(甚至根本没有主体)。有关详细信息,请参阅故障案例和返回值列表.
查询响应正文
字段
|
类型
|
强制性的
|
说明
|
查询id
|
32字符字符串(UUID)
|
对
|
此查询的唯一事务id。
|
结果
|
查询结果条目列表
|
对于成功的查询是必需的,对于失败的查询是缺少的。
|
目标匹配列表,按内部识别可信度排序。
|
结果代码
|
字符串
|
对
|
指示请求成功(success)或特定类型失败的结果代码。请参阅以下错误情况的可能值。
|
查询结果输入
字段
|
类型
|
强制性的
|
说明
|
目标id
|
32字符字符串(UUID)
|
对
|
目标的UUID
|
目标数据
|
目标数据记录
|
否(见说明)
|
描述匹配目标的目标数据记录。是否返回此字段取决于请求中的include_target_data参数。
|
目标数据
字段
|
类型
|
强制性的
|
说明
|
名称
|
字符串
|
对
|
目标的名称
|
应用程序元数据
|
字符串
|
对
|
与目标关联的应用程序元数据(用户提供)。以base64编码。
|
目标时间戳
|
国际
|
对
|
自1970年1月1日GMT(Unix时间)以来创建/更新目标的时间戳(以秒为单位)。请注意,这是一个无符号32位整数。
|