空间搜索

简介

空间搜索服务提供通过关键字、多边形、矩形、周边搜索等多种方式，实现对指定范围内entity实时位置和数量的搜索。类BTKEntityAction中支持实时查询entity最新位置、高度、速度、方向和相关属性信息。支持以下搜索方式：

1. 关键字模糊查询：根据entityName和entityDesc字段模糊查询entity

2. 周边搜索：查询某中心点周边的entity

3. 矩形搜索：查询某矩形地理范围内的entity

4. 多边形搜索：查询多边形范围内的entity

关键字检索

通过 -(void)searchEntityWith:(BTKSearchEntityRequest *)request delegate:(id)delegate; 方法，根据关键字检索终端实体，并返回其实时位置。与 -(void)queryEntityWith:(BTKQueryEntityRequest *)request delegate:(id)delegate; 方法相比，该方法增加了关键字检索的功能，支持对终端实体的名称和描述的联合模糊检索。

以下代码片段表示，查找100000这个service下，名称或描述字段含有“entity”的，在过去7天有轨迹上传的，终端实体的实时位置。若有多个entity满足条件，则按照它们最后定位时间 “loc_time” 字段的倒序返回，即定位时间离现在越近越靠前。

// 设置过滤条件
BTKQueryEntityFilterOption *filterOption = [[BTKQueryEntityFilterOption alloc] init];
filterOption.activeTime = [[NSDate date] timeIntervalSince1970] - 7 * 24 * 3600;
// 设置排序条件，返回的多个entity按照，定位时间'loc_time'的倒序排列
BTKSearchEntitySortByOption * sortbyOption = [[BTKSearchEntitySortByOption alloc] init];
sortbyOption.fieldName = @"loc_time";
sortbyOption.sortType = BTK_ENTITY_SORT_TYPE_DESC;
// 构造请求对象
BTKSearchEntityRequest *request = [[BTKSearchEntityRequest alloc] initWithQueryKeyword:@"entity" filter:filterOption sortby:sortbyOption outputCoordType:BTK_COORDTYPE_BD09LL pageIndex:1 pageSize:10 ServiceID:100000 tag:34];
// 发起检索请求
[[BTKEntityAction sharedInstance] searchEntityWith:request delegate:self];

矩形范围搜索

通过 -(void)boundSearchEntityWith:(BTKBoundSearchEntityRequest *)request delegate:(id)delegate; 方法，在指定的矩形地理范围内，检索符合条件的终端实体，并返回其实时位置。

以下代码片段表示，在西南角为东经116.311046度、北纬40.046667度，东北角为东经116.315264度、北纬40.048973度，所构成的矩形区域内，检索名称为 “entityA” 、 “entityB”、“entityC” 这3个终端实体，在过去的7天内是否有轨迹点上传。如果有，则返回每个终端实体最后一次上传的轨迹点，如果返回结果包含不止一个轨迹点，则按照它们最后一次上传的时间戳 “loc_time” 字段的倒序排列，即离当前时间越近的轨迹点越靠前。

// 设置矩形的区域
NSMutableArray *bounds = [NSMutableArray arrayWithCapacity:2];
// 矩形左下角的顶点坐标
CLLocationCoordinate2D point1 = CLLocationCoordinate2DMake(40.046667, 116.311046);
[bounds addObject:[NSValue valueWithBytes:&point1 objCType:@encode(CLLocationCoordinate2D)]];
// 矩形右上角的顶点坐标
CLLocationCoordinate2D point2 = CLLocationCoordinate2DMake(40.048973, 116.315264);
[bounds addObject:[NSValue valueWithBytes:&point2 objCType:@encode(CLLocationCoordinate2D)]];
// 设置检索的过滤选项
BTKQueryEntityFilterOption *filterOption = [[BTKQueryEntityFilterOption alloc] init];
filterOption.entityNames = @[@"entityA", @"entityB"，@"entityC"];
filterOption.activeTime = [[NSDate date] timeIntervalSince1970] - 7 * 24 * 3600;
// 设置检索结果的排序选项
BTKSearchEntitySortByOption * sortbyOption = [[BTKSearchEntitySortByOption alloc] init];
sortbyOption.fieldName = @"loc_time";
sortbyOption.sortType = BTK_ENTITY_SORT_TYPE_DESC;
// 构造检索请求    
BTKBoundSearchEntityRequest *request = [[BTKBoundSearchEntityRequest alloc] initWithBounds:bounds inputCoordType:BTK_COORDTYPE_BD09LL filter:filterOption sortby:sortbyOption outputCoordType:BTK_COORDTYPE_BD09LL pageIndex:1 pageSize:10 ServiceID:100000 tag:44];
// 发起检索请求    
[[BTKEntityAction sharedInstance] boundSearchEntityWith:request delegate:self];

周边搜索

通过 -(void)aroundSearchEntityWith:(BTKAroundSearchEntityRequest *)request delegate:(id)delegate; 方法，在指定的圆形地理范围内，检索符合条件的终端实体，并返回其实时位置。

以下代码片段表示，在以东经116.312964度、北纬40.047772度为圆心，半径100米的范围内，检索100000这个service下所有在过去7天有轨迹点上传的活跃终端，如果有满足条件的终端实体，则返回其最后一次上传的轨迹点。若有多个终端实体符合以上检索条件，则返回结果按照它们的定位时间戳”loc_time” 字段倒序排列，即离当前时间越近的轨迹点越靠前。

// 设置圆形的圆心
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.047772, 116.312964);
// 设置检索的过滤条件
BTKQueryEntityFilterOption *filterOption = [[BTKQueryEntityFilterOption alloc] init];
filterOption.activeTime = [[NSDate date] timeIntervalSince1970] - 7 * 24 * 3600;
// 设置检索结果的排序方式
BTKSearchEntitySortByOption * sortbyOption = [[BTKSearchEntitySortByOption alloc] init];
sortbyOption.fieldName = @"loc_time";
sortbyOption.sortType = BTK_ENTITY_SORT_TYPE_DESC;
// 构造检索请求对象
BTKAroundSearchEntityRequest *request = [[BTKAroundSearchEntityRequest alloc] initWithCenter:center inputCoordType:BTK_COORDTYPE_BD09LL radius:100 filter:filterOption sortby:sortbyOption outputCoordType:BTK_COORDTYPE_BD09LL pageIndex:1 pageSize:10 ServiceID:100000 tag:55];
// 发起检索请求
[[BTKEntityAction sharedInstance] aroundSearchEntityWith:request delegate:self];

通过entity属性字段查询

开发者可在轨迹管理台中可视化地创建 entity自定义属性字段，方法详见自定义属性字段。在queryEntityList方法中，通过指定columnKey，来根据属性进行查询，columnKey字段的格式为k1=v1,k2=v2。

例如开发者创建了team和city两个可检索的自定义属性字段，需要查询team=A且city=beijing的entity，示例如下：

  [[BTRACEAction shared] queryEntityList:self serviceId:100001 entityNames:nil columnKey:@"team=A,city=beijing" activeTime:0 returnType:0 pageSize:20 pageIndex:1];

以上例子会返回该service下所有的entity中，属于A队的，城市是beijing的所有entity的实时位置。

注意：和trackAttr()所添加的基于轨迹点的自定义字段不同，属性信息是基于entity的，一个entity的属性是不会经常变动的。比如货运车辆所归属的车辆编队，或配送人员所管辖的区域信息等。而trackAttr()所添加的自定义字段是基于轨迹点的，类似于当前跑者的心跳等在每个轨迹点都会变化的信息。

通过活跃时间activeTime查询

支持查询在某个时间之后仍活跃的entity，如查询5分钟之内活跃的，则需将activeTime设为当前时间减去5分钟；如查询当天活跃的entity，则将activeTime设为当天0点：

如：查询在UNIX时间戳为1442824667之后仍活跃的所有entity

[[BTRACEAction shared] queryEntityList:self serviceId:100001 entityNames:nil  columnKey:nil activeTime:1442824667 returnType:0 pageSize:20 pageIndex:1];

组合查询

对于entity以及columnKey和activeTime这些字段，可以同时指定一个或多个字段，做联合查询，会返回同时满足这些条件的entity的实时位置。

[[BTRACEAction shared] queryEntityList:self serviceId:100001 entityNames:@"entity1,entity2" columnKey:@"team=A,region=haidian" activeTime:1442824667 returnType:0 pageSize:20 pageIndex:1];

以上例子就会查询在entity1和entity2这两个entity中，team是A，region是haidian，且在1442824667时间戳后仍有轨迹数据上传的entity的实时位置。

关于数据的实时性的说明

从数据上传到鹰眼服务端，到通过查询接口查询到该数据，在联网正常的情况下延时在毫秒级别，可认为是无延时地同步。 在上传时，受打包周期的限制，会存在一个打包周期的延迟。若开发者对实时性要求较高，可以将打包周期设置成采集周期，但需考虑流量的消耗。