返回位于指定区域内且满足可选过滤条件的一组可播放位置。
注意:随着世界状况随着时间的推移而变化,相同的 v3.samplePlayableLocations
请求可能会返回不同的结果。
HTTP 请求
POST https://playablelocations.googleapis.com/v3:samplePlayableLocations
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 | |
---|---|
{ "areaFilter": { object ( |
字段 | |
---|---|
areaFilter |
必需。指定要在其中搜索可播放位置的区域。 |
criteria[] |
必需。指定一个或多个(最多 5 个)条件,用于过滤返回的可播放位置。 |
响应正文
如果成功,响应正文将包含结构如下的数据:
对 v3.samplePlayableLocations
方法的响应。
JSON 表示法 | |
---|---|
{
"locationsPerGameObjectType": {
string: {
object( |
字段 | |
---|---|
locationsPerGameObjectType |
每个 PlayableLocation 对象都与请求中指定的 gameObjectType 对应。 包含一系列 |
ttl |
必需。指定一组可播放位置的“存留时间”。您可以使用此值来确定可播放位置集的缓存时长。待这段时间过后,您的后端游戏服务器应发出新的 该持续时间以秒为单位,最多包含九个小数位,以“ |
AreaFilter
指定要在其中搜索可播放位置的区域。
JSON 表示法 | |
---|---|
{ "s2CellId": string } |
字段 | |
---|---|
s2CellId |
必需。所需区域的 S2 小区 ID。此值必须介于 11 到 14 之间(含 11 和 14)。 S2 单元格是 64 位整数,用于标识地球上的区域。它们是分层的,因此可用于空间索引。 S2 几何图形库支持多种语言: |
标准
封装用于搜索一组可播放位置的过滤条件。
JSON 表示法 | |
---|---|
{
"gameObjectType": integer,
"filter": {
object ( |
字段 | |
---|---|
gameObjectType |
必需。开发者定义的任意标识符,属于可玩位置所针对的游戏对象类型。通过此字段,您可以在搜索可玩位置时按游戏对象类型指定条件。 您应该在所有 响应包含 map<gameObjectType, Response>。 |
filter |
指定过滤选项,并指定结果集中要包含的内容。 |
fieldsToReturn |
指定返回哪些
除非您在此处指定以下字段,否则系统会将其省略:
注意:包含的字段越多,就数据以及相关延迟时间而言,查询的成本就越高。 以逗号分隔的完全限定字段名称列表。示例: |
过滤
指定搜索可播放位置时使用的过滤条件。
JSON 表示法 | |
---|---|
{
"maxLocationCount": integer,
"spacing": {
object ( |
字段 | |
---|---|
maxLocationCount |
指定要返回的可播放位置的数量上限。此值不得超过 1000。默认值为 100。 仅返回排名靠前的可播放位置。 |
spacing |
一组用于控制可播放位置间距的选项。默认情况下,两个位置之间的最小距离为 200 米。 |
includedTypes[] |
将可播放位置集限制为仅包含所需的 types。 |
SpacingOptions
一组选项,用于指定可播放位置之间的间隔。
JSON 表示法 | |
---|---|
{
"minSpacingMeters": number,
"pointType": enum ( |
字段 | |
---|---|
minSpacingMeters |
必需。任意两个可播放位置之间的最小间距,以米为单位。最小值为 30。最大值为 1000。 输入值将向上舍入到下一个 10 米间隔。 默认值为 200m。 设置此字段可移除可播放位置的紧密聚类。 注意: 间距是一种贪心算法。它会进行优化,以便首先选择排名最高的营业地点,而不是尽可能增加所选营业地点的数量。请考虑以下场景:
如果内边距为 250,则会选择排名最高的地理位置 [B],而不是 [A, C]。 注意: 间距在游戏对象类型本身以及以前的类型中都有效。假设有三种游戏对象类型,每种类型的间距如下:
这些位置之间的距离图最终如下:
|
pointType |
指定最小间距约束是应用于可播放位置的中心点还是贴靠点。默认值为 如果贴靠点不适用于可播放位置,则系统会改为使用其中心点。 请将此项设为游戏中使用的点类型。 |
PointType
指定可播放位置的地理坐标(纬度和经度)是对应于其中心点,还是对应于其与最近道路的人行道对应的位置。
枚举 | |
---|---|
POINT_TYPE_UNSPECIFIED |
未指定的点类型。请勿使用此值。 |
CENTER_POINT |
地理坐标对应于营业地点的中心。 |
SNAPPED_POINT |
地理坐标对应于与最近道路的人行道对应的位置(如果存在附近的道路)。 |