Method: samplePlayableLocations

返回位于指定区域内且满足可选过滤条件的一组可播放位置。

注意:随着世界状况随着时间的推移而变化,相同的 v3.samplePlayableLocations 请求可能会返回不同的结果。

HTTP 请求

POST https://playablelocations.googleapis.com/v3:samplePlayableLocations

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据:

JSON 表示法
{
  "areaFilter": {
    object (AreaFilter)
  },
  "criteria": [
    {
      object (Criterion)
    }
  ]
}
字段
areaFilter

object (AreaFilter)

必需。指定要在其中搜索可播放位置的区域。

criteria[]

object (Criterion)

必需。指定一个或多个(最多 5 个)条件,用于过滤返回的可播放位置。

响应正文

如果成功,响应正文将包含结构如下的数据:

v3.samplePlayableLocations 方法的响应。

JSON 表示法
{
  "locationsPerGameObjectType": {
    string: {
      object(PlayableLocationList)
    },
    ...
  },
  "ttl": string
}
字段
locationsPerGameObjectType

map (key: integer, value: object (PlayableLocationList))

每个 PlayableLocation 对象都与请求中指定的 gameObjectType 对应。

包含一系列 "key": value 对的对象。示例:{ "name": "wrench", "mass": "1.3kg", "count": "3" }

ttl

string (Duration format)

必需。指定一组可播放位置的“存留时间”。您可以使用此值来确定可播放位置集的缓存时长。待这段时间过后,您的后端游戏服务器应发出新的 v3.samplePlayableLocations 请求,以获取一组新的可供畅玩的地点(例如,这些地点可能已被移除、某个公园可能在当天已关闭、商家可能已经永久停业)。

该持续时间以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

AreaFilter

指定要在其中搜索可播放位置的区域。

JSON 表示法
{
  "s2CellId": string
}
字段
s2CellId

string (fixed64 format)

必需。所需区域的 S2 小区 ID。此值必须介于 11 到 14 之间(含 11 和 14)。

S2 单元格是 64 位整数,用于标识地球上的区域。它们是分层的,因此可用于空间索引。

S2 几何图形库支持多种语言:

标准

封装用于搜索一组可播放位置的过滤条件。

JSON 表示法
{
  "gameObjectType": integer,
  "filter": {
    object (Filter)
  },
  "fieldsToReturn": string
}
字段
gameObjectType

integer

必需。开发者定义的任意标识符,属于可玩位置所针对的游戏对象类型。通过此字段,您可以在搜索可玩位置时按游戏对象类型指定条件。

您应该在所有 request_criteria 中分配一个唯一的 gameObjectType ID,以表示不同类型的游戏对象。例如,1=怪兽位置,2=能力提升道具位置。

响应包含 map<gameObjectType, Response>。

filter

object (Filter)

指定过滤选项,并指定结果集中要包含的内容。

fieldsToReturn

string (FieldMask format)

指定返回哪些 PlayableLocation 字段。

name(用于记录展示次数)、centerPointplaceId(或 plusCode)。

除非您在此处指定以下字段,否则系统会将其省略:

  • snappedPoint
  • 类型

注意:包含的字段越多,就数据以及相关延迟时间而言,查询的成本就越高。

以逗号分隔的完全限定字段名称列表。示例:"user.displayName,photo"

过滤

指定搜索可播放位置时使用的过滤条件。

JSON 表示法
{
  "maxLocationCount": integer,
  "spacing": {
    object (SpacingOptions)
  },
  "includedTypes": [
    string
  ]
}
字段
maxLocationCount

integer

指定要返回的可播放位置的数量上限。此值不得超过 1000。默认值为 100。

仅返回排名靠前的可播放位置。

spacing

object (SpacingOptions)

一组用于控制可播放位置间距的选项。默认情况下,两个位置之间的最小距离为 200 米。

includedTypes[]

string

将可播放位置集限制为仅包含所需的 types

SpacingOptions

一组选项,用于指定可播放位置之间的间隔。

JSON 表示法
{
  "minSpacingMeters": number,
  "pointType": enum (PointType)
}
字段
minSpacingMeters

number

必需。任意两个可播放位置之间的最小间距,以米为单位。最小值为 30。最大值为 1000。

输入值将向上舍入到下一个 10 米间隔。

默认值为 200m。

设置此字段可移除可播放位置的紧密聚类。

注意:

间距是一种贪心算法。它会进行优化,以便首先选择排名最高的营业地点,而不是尽可能增加所选营业地点的数量。请考虑以下场景:

  • 排名:A:2,B:1,C:3。
  • 距离:A--200 米--B--200 米--C

如果内边距为 250,则会选择排名最高的地理位置 [B],而不是 [A, C]。

注意:

间距在游戏对象类型本身以及以前的类型中都有效。假设有三种游戏对象类型,每种类型的间距如下:

  • X:400 米,Y:未定义,Z:200 米。
  1. 为 X 添加地点,彼此相距 400 米。
  2. 为 Y 添加位置,不添加任何间距。
  3. 最后,为 Z 添加彼此相距 200 米以内的位置,以及 X 和 Y。

这些位置之间的距离图最终如下:

  • 从->到。
  • X->X:400 米
  • Y->X、Y->Y:未指定。
  • Z->X、Z->Y、Z->Z:200 米。
pointType

enum (PointType)

指定最小间距约束是应用于可播放位置的中心点还是贴靠点。默认值为 CENTER_POINT

如果贴靠点不适用于可播放位置,则系统会改为使用其中心点。

请将此项设为游戏中使用的点类型。

PointType

指定可播放位置的地理坐标(纬度和经度)是对应于其中心点,还是对应于其与最近道路的人行道对应的位置。

枚举
POINT_TYPE_UNSPECIFIED 未指定的点类型。请勿使用此值。
CENTER_POINT 地理坐标对应于营业地点的中心。
SNAPPED_POINT 地理坐标对应于与最近道路的人行道对应的位置(如果存在附近的道路)。