电报 API中的分页

许多 Telegram API 方法提供了对可能非常大的对象列表的访问，这就需要分页。

为了仅获取每个请求的相关结果子集，API 提供了多个输入参数。以下列表按 API 中的应用顺序排列。

通常情况下，结果按时间倒序返回，对象 ID 值按降序排列。

limit范围

返回对象数量的限制，通常介于 1 到 100 之间。当提供 0 时，限制值通常会默认为中间值，例如 ~20。

offset基于分页

对于一些数据主要为静态数据的方法，此参数允许跳过offset列表开头的元素；在某些情况下允许负值。

offset_id基于分页

对于大多数结果为实时数据（例如聊天记录）的方法，offset值不会直接传递。而是根据传递的参数值计算得出，计算公式offset_id为add_offset，offsetFromID(offset_id) + add_offset其中offsetFromID(offset_id)是从列表开头到 ID 为的结果（offset_id包含）之间的结果数。

使用案例示例：

• 正在加载 20 条消息，最早的消息 ID 为MSGID：

  messages.getHistory({offset_id: MSGID, add_offset: 0, limit: 20})

• 正在加载 20 条消息，这些消息比 ID 为：的消息更新MSGID。

  messages.getHistory({offset_id: MSGID, add_offset: -20, limit: 20})

• 正在加载 ID 为MSGID：的消息周围的 20 条消息

  messages.getHistory({offset_id: MSGID, add_offset: -10, limit: 20})

附加筛选

还有一些参数，在对列表进行偏移量和限制条件切片后，会应用这些参数来进一步缩小结果子集：

• max_id：可用于仅返回 ID 严格小于指定值max_id（例如消息 ID）的结果。
• min_id：可用于仅返回 ID 严格大于特定值min_id（例如消息 ID）的结果。
• max_date：可用于仅返回早于以下日期的结果max_date：
• min_date：可用于仅返回日期晚于以下日期的结果min_date：
• 哈希值：见下文。

哈希生成

为了进一步缩小结果子集，存在一种机制，如果结果列表与客户端存储的列表没有变化，则避免获取数据，类似于ETag。

当客户端缓存了 API 请求的结果时，它可以hash通过获取结果 ID（消息 ID 或其他名称字段id，或在某些情况下使用一些额外字段）并使用以下算法计算 64 位哈希值来计算该值：

# Here, ^ indicates a bitwise XORhash = 0for id in ids:hash = hash ^ (hash >> 21)hash = hash ^ (hash << 35)hash = hash ^ (hash >> 4)hash = hash + id

该>>运算符是无符号右移运算符。

注意：在某些情况下，ids传递给算法的数组必须包含字符串（例如业务快捷方式中的快捷方式名称等），在这种情况下，必须通过取字符串的 MD5 哈希的前 8 个字节（不是十六进制形式）并将其视为大端 64 位长整型来将其转换为长整型。

在某些情况下，如果结果容器中已经存在某个hash字段，则可以使用该字段代替。

当客户端传递正确的值时，API 将返回*NotModified构造函数之一，例如messages.messagesNotModified，而不是实际结果。

示例方法

• messages.getHistory支持所有结果导航参数，包括消息 ID 哈希值，但不包括过滤器。
• channels.getParticipants支持使用limit和offset进行简单导航，以及hash使用返回参与者的用户 ID 进行筛选和缩减。