The Vuforia Web服务API允许您查询、上传和管理云数据库中的图像，并通过HTTP使用基于REST的API获取目标和数据库的报告。您还可以使用VWS使用VuMark生成API生成VuMarks的可打印实例。
本文解释了如何使用VWS API执行各种类型的操作。我们还提供VWS示例（Java和PHP）以说明开发人员在使用VWS时应遵循的最佳实践。
目标管理
报告
调试
身份验证
所有对云目标Web API的请求都需要使用Vuforia Web Services（VWS）签名方案进行身份验证，如Vuforia Web API身份验证.
为了使用VWS API管理云目标，您需要使用与云数据库关联的服务器访问密钥。对于执行图像识别查询，您需要使用与云数据库关联的客户端访问密钥。
请参阅Vuforia Web API身份验证了解更多信息。
添加目标
您可以使用Vuforia Web Services REST API向以下对象发出POST请求，将目标添加到云数据库https://vws.vuforia.com/targets。请求应包括文章中描述的Authorization标头Vuforia Web API身份验证，它应该声明一个application/JSON内容类型。请求主体必须是定义目标属性的JSON对象。
上传的图像文件必须符合支持的格式，最大为2MB。另请参见中描述的图像的其他要求图像目标.
您可以包含最多1 MB的base 64编码内容作为附加到目标搜索结果的元数据。该内容的示例可以是图像或移动优化的3D模型。此功能允许您在云识别服务中使用目标托管内容。
JSON正文元素
下表列出了JSON主体元素：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
名称
|
字符串[1-64]
|
是的
|
目标的名称，在数据库中是唯一的
|
|
宽度
|
浮子
|
是的
|
以场景单位表示的目标宽度
|
|
形象
|
JPG或PNG格式的Base64编码二进制图像文件
|
是的
|
包含base64编码的二进制识别图像数据
|
|
活动_标志
|
布尔值
|
不
|
指示目标是否处于查询活动状态
|
|
应用程序元数据
|
Base64编码数据
|
不
|
与目标关联的base64编码的应用程序元数据
|
POST示例
POST/目标HTTP/1.1主持人：vws.vuforia.com日期：2012年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU内容类型：application/json{“name”：“tarmac”，“宽度”：32.0，“图像”：“0912ba39x…”，“application_metadata”：“496fbb6532b3863460a984de1d980bed5ebcd507”}
响应消息
响应包含返回目标的目标ID。这个结果代码字段应指示创建; 如果没有，则发生错误。返回的JSON主体结构如下表所示：
|
字段
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易的ID
|
|
目标id
|
32个字符的字符串（UUID）
|
是的
|
目标的ID
|
响应示例
HTTP/1.1 201已创建内容类型：application/json{“result_code”：“成功”，“transaction_id”：“e29b41550e8400d4a71644665544000”，“目标id”：“550b41d4a7164466554e8400e2949364”}
更新目标
要更新数据库中的目标，请对执行PUT请求https://vws.vuforia.com/targets/{目标id}
JSON主体定义如下表所示：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
名称
|
字符串[1-64]
|
不
|
目标的名称，在数据库中是唯一的
|
|
宽度
|
浮子
|
不
|
以场景单位表示的目标宽度
|
|
形象
|
JPG或PNG格式的Base 64编码二进制图像文件
|
不
|
包含基64编码的二进制识别图像数据
|
|
活动_标志
|
布尔值
|
不
|
指示目标是否处于查询活动状态
|
|
应用程序元数据
|
Base 64编码数据
|
不
|
与目标关联的基本64编码的应用程序元数据
|
PUT示例
PUT/目标HTTP/1.1主持人：vws.vuforia.com日期：2013年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU内容类型：application/json{“name”：“停机坪”，“宽度”：32.0，“图像”：“0912ba39x…”，“active_flag”：true，“application_metadata”：“496fbb6532b3863460a984de1d980bed5ebcd507”}
响应消息
响应包含结果目标的ID。确认状态为“成功”；如果没有，则发生错误。生成的JSON主体结构如下表所示。
|
字段
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易的ID
|
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“550e8400e29b41d4a716446655482752”}
删除目标
要删除数据库中的目标，请对执行delete请求https://vws.vuforia.com/targets/{目标id}。确认目标的状态值为成功在尝试删除目标之前。请参阅检索目标记录有关如何使用查询目标状态的详细信息获取/目标/｛target_id｝。的值活动_标志和评级在状态值为成功或失败.
注：无法删除处于处理状态的目标。
DELETE示例
删除/targets/550e8400e29b41d34716446655834450 HTTP/1.1主持人：vws.vuforia.com日期：2013年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
响应包含删除的状态。确认状态值为成功。否则会发生错误。下表显示了返回的JSON正文的结构：
|
字段
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
交易id
|
32字符字符串（UUID）
|
是的
|
交易的ID
|
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“550e8400e29b41d4a716446655482752”}
检索目标记录
要获取特定目标的信息，请对执行get请求https://vws.vuforia.com/targets/{目标id}.
请注意，请求数限制为每秒45个。
GET示例
GET/targets/550e8400e29b41d34716446655834450 HTTP/1.1主持人：vws.vuforia.com日期：2013年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
确认身份验证后，云识别服务返回包含指定目标内容的JSON消息。客户应检查结果代码表示成功。否则，检索列表时出现问题。
返回的JSON正文的结构如下表所示：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易ID
|
|
目标记录
|
目标记录
|
是的
|
包含TMS上的目标记录
|
|
地位
|
字符串[1-64]
|
是的
|
目标的状态；当前支持的值包括处理、成功和失败
|
这个目标记录车身如下表所示：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
目标id
|
32字符字符串（UUID）
|
是的
|
目标的Target_id
|
|
活动_标志
|
布尔值
|
不
|
指示目标是否处于查询活动状态；默认值为true
|
|
名称
|
字符串[1-64]
|
是的
|
目标名称；在数据库中唯一
|
|
宽度
|
浮子
|
是的
|
以场景单位表示的目标宽度
|
|
跟踪_评级
|
积分[0-5]
|
是的
|
用于跟踪的目标识别图像评级
|
|
重新评级（_R）
|
一串
|
不
|
未使用。始终包含空字符串
|
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“e29b41550e8400d4a71644665544000”，“目标记录”：{“目标id”：“550b41d4a7164466554e8400e2949364”，“active_flag”：true，“name”：“停机坪”，“宽度”：100.0，“tracking_rating”：4，“重新评级（_R）”：“” },“status”：“成功”}
检查类似目标
在上执行GET请求https://vws.vuforia.com/duplicates网站/{目标id}。在数据库中搜索给定target_id的重复和类似图像。进行类似目标检查时需要考虑的其他事项：
- 一旦目标的上传操作使用POST或PUT完成，就可以调用重复检查。target_id引用的目标不必处于活动状态才能执行类似的目标检查。
- 如果通过VWS API（或通过目标管理器）明确禁用了目标，则在进行类似的目标检查时不再考虑该目标。
- 如果请求的目标不存在，服务将在POST响应正文中返回UnknownTarget（404）错误。
- 请求限制为每秒10个。
GET示例
GET/duplicates/550e8400e29b41d34716446655834450 HTTP/1.1主持人：vws.vuforia.com日期：2012年4月23日星期一12:45:19格林威治标准时间授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
响应返回一个类似和/或重复目标的列表（如果有），按相似性的内部置信度排序。类似目标的最大数量为16个。生成的JSON主体结构如下：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
相似的目标
|
目标ID[0..16]
|
是的
|
给定target_id的相似和/或重复目标列表，按相似性的内部置信度排序
|
如果成功的答案不包含重复项，则表示未找到类似的目标。如果请求的目标不存在，则在响应正文中返回UnknownTarget（404）错误。
响应示例
HTTP/1.1 200正常内容类型：application/json{“类似目标”：[“550e8400e29b41d4a716446655447300”，“578fe7fd60055cbc84c2d215066b7a9d” ]}
列出目标
为了检索云数据库的目标列表，请对执行GET请求https://vws.vuforia.com/targets.
列表操作限制为每分钟1个请求，对于包含超过100万个映像的数据库，该操作将失败。如果您需要拥有超过100万张图像的数据库的目标列表，请通过Vuforia生产支持在线表单。
GET示例
获取/目标HTTP/1.1主持人：vws.vuforia.com日期：2012年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
返回一个JSON对象，其中包含数据库中的目标列表。客户应检查结果代码表示成功。否则，检索列表时出现问题。
返回的JSON消息的结构如下表所示：
|
字段
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易的ID
|
|
结果
|
target_id[0..unbounded]
|
是的
|
开发人员项目中目标的目标ID列表
|
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“550e8400e29440000b41d4a716446655”，“结果”：[“00550e84e29b41d4a71644665555678”，“578fe7fd60055a5a84c2d215066b7a9d” ]}
检索目标摘要报告
要获取数据库中特定图像的摘要，请对执行get请求https://vws.vuforia.com/summary网站/{目标id}。
GET示例
GET/summary/550e846655447733400e29b41d4a7164 HTTP/1.1主持人：vws.vuforia.com日期：2013年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
返回包含指定目标内容的JSON对象。客户端应检查result_code是否指示成功。否则检索列表时出现问题。
返回的JSON正文的结构如下表所示：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易的ID
|
|
数据库名称
|
字符串[1-64]
|
是的
|
数据库的名称
|
|
目标名称
|
字符串[1-64]
|
是的
|
目标的名称
|
|
上传日期
|
日期
|
是的
|
上传日期（指定为YYYY-MM-DD）
|
|
活动_标志
|
布尔值
|
是的
|
指示目标是否处于查询活动状态；默认值为true
|
|
地位
|
字符串[1-64]
|
是的
|
目标的状态；当前支持的值是处理、成功和失败
|
|
跟踪_评级
|
积分[0-5]
|
否*
|
用于跟踪的目标识别图像评级
|
|
重新评级（_R）
|
字符串
|
没有*
|
未使用。始终包含空字符串
|
|
总计_成本
|
国际
|
没有*
|
|
|
当前月收入
|
国际
|
没有*
|
|
|
上一个月的费用
|
国际
|
没有*
|
|
注释:跟踪评级和重新评级（_R）仅当状态返回时提供成功.
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“d4a716446655440663390e8400e29b41”，“数据库名称”：“RecoTest”，“target_name”：“tarmac”，“upload_date”：“2012-03-31”，“active_flag”：true，“status”：“成功”，“tracking_rating”：4，“重新评级（_R）”：“”，“total_recos”：0，“current_month_recos”：0，“previous_month_recos”：0}
获取数据库摘要报告
要获取云数据库的摘要报告，请在上执行get请求https://vws.vuforia.com/summary网站
GET示例
GET/summary HTTP/1.1主持人：vws.vuforia.com日期：2013年4月23日星期一12:45:19 GMT授权：VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
响应消息
返回带有数据库摘要报告的JSON对象。客户应检查结果代码表示成功。否则检索列表时出现问题。
返回的JSON正文的结构如下表所示：
|
字段名称
|
类型
|
强制性的
|
描述
|
|
结果代码
|
字符串[1-64]
|
是的
|
其中一个VWS API结果代码
|
|
事务id
|
32字符字符串（UUID）
|
是的
|
交易ID
|
|
名称
|
字符串[1-64]
|
是的
|
数据库的名称
|
|
活动图像
|
单位32
|
是的
|
数据库的active_flag为true且状态为success的图像总数
|
|
非活动图像
|
uint32
|
是的
|
数据库的active_flag=false且状态=success的图像总数
|
|
失败的图像
|
单位32
|
是的
|
数据库状态为失败的图像总数
|
| 重新折叠（_T） |
整数 |
没有* |
与此数据库关联的许可证指定的每月分配的reco数 |
| 总计_成本 |
整数 |
没有* |
此数据库生存期内的记录总量 |
| 当前月收入 |
整数 |
没有* |
当月记录数 |
| 上一个月的费用 |
整数 |
没有* |
上月记录数 |
响应示例
HTTP/1.1 200正常内容类型：application/json{“result_code”：“成功”，“transaction_id”：“00e2550e849b41d4a755440000164466”，“name”：“重新测试”，“活动图像”：3，“非活动图像”：0，“失败的图像”：0，“记录阈值”：1000，“total_recos”：1600，“current_month_recos”：100，“上一个月_重复次数”：200}
VWS API结果代码
下表列出了支持的result_code、其对应的HTTP状态代码以及结果的描述。
|
结果代码
|
HTTP状态代码
|
描述
|
|
成功
|
正常（200）
|
交易成功
|
|
目标已创建
|
创建时间（201）
|
目标已创建（目标POST响应）
|
|
身份验证失败
|
身份验证失败（401）
|
签名身份验证失败
|
|
请求时间扭曲
|
禁止（403）
|
请求时间戳超出允许范围
|
|
目标名称存在
|
禁止（403）
|
相应的目标名称已存在（目标POST/PUT响应）
|
|
已达到请求配额
|
禁止（403）
|
已达到此数据库的最大API调用数。
|
|
目标状态处理
|
禁止（403）
|
目标处于处理状态，无法更新。
|
|
目标状态未成功
|
禁止（403）
|
无法完成请求，因为目标未处于成功状态。
|
|
达到目标配额
|
禁止（403）
|
已达到此数据库的最大目标数。
|
|
项目已挂起
|
禁止（403）
|
无法完成请求，因为此数据库已挂起。
|
|
项目未激活
|
禁止（403）
|
无法完成请求，因为此数据库处于非活动状态。
|
|
项目无ApiAccess
|
禁止（403）
|
无法完成请求，因为不允许此数据库发出API请求。
|
|
未知目标
|
未找到（404）
|
指定的目标ID不存在（目标PUT/GET/DELETE响应）
|
|
错误图像
|
不可处理实体（422）
|
图像损坏或格式不受支持（目标POST/PUT响应）
|
|
图像太大
|
不可处理实体（422）
|
目标元数据大小超过最大限制（目标POST/PUT响应）
|
|
元数据太大
|
不可处理实体（422）
|
图像大小超过最大限制（目标POST/PUT响应）
|
|
日期范围错误
|
不可处理实体（422）
|
开始日期晚于结束日期
|
|
失败
|
不可处理实体（422）
|
请求无效，无法处理。检查请求标题和字段。
|
| TooMany请求 |
请求太多（429） |
每秒请求太多。最大请求数限制为每秒15个，GET/targets/和GET/duplicates/有几个例外。 |
|
失败
|
内部服务器错误（500）
|
服务器遇到内部错误；请重试请求
|