instagram-private-api 故事测验参与者数据接口:StoryQuizParticipantsFeedResponseRootObject 完全解析
instagram-private-api 故事测验参与者数据接口:StoryQuizParticipantsFeedResponseRootObject 完全解析
本文以 instagram-private-api(NodeJS Instagram Private API SDK,TypeScript 编写)中
StoryQuizParticipantsFeedResponseRootObject接口文档为核心,深入解析 Instagram 故事(Story)中"测验(Quiz)"贴纸的参与者数据返回结构、字段含义、分页机制与配套的发布/回答 API 调用链。读完本文,你将掌握如何通过ig.feed.storyQuizParticipants()拉取测验答题用户列表,并结合QuizSticker与storyQuizAnswer()完整打通"发布测验 → 用户答题 → 获取参与明细"的闭环流程。
一、接口定位:故事测验参与者的响应根对象
StoryQuizParticipantsFeedResponseRootObject 定义于 src/responses/story-quiz-participants.feed.response.ts,是 instagram-private-api 中"故事测验参与者 Feed"(story quiz participants feed)的响应根类型。它并不直接由用户在业务代码中实例化,而是由 SDK 内部的 Feed 工厂在请求 Instagram 私信接口时,将返回 JSON 反序列化(class-transformer)后得到的顶层对象。
该接口在 TypeDoc 生成文档 docs/interfaces/responses/StoryQuizParticipantsFeedResponseRootObject.md 中仅声明了两个属性:
| 属性名 | 类型 | 说明 |
|---|---|---|
participant_info |
StoryQuizParticipantsFeedResponseParticipant_info |
参与者信息容器,包含测验 ID、参与者列表与分页游标 |
status |
string |
接口请求状态,正常时为 "ok" |
在模块体系中它被挂在 responses 模块下,见 docs/modules/responses.md;其导出入口位于 src/responses/index.ts(export * from './story-quiz-participants.feed.response';)。
二、核心字段详解:participant_info 与 status
2.1 status:请求状态标志
status: string 是 Instagram 大多数内部 API 响应都携带的通用字段。当请求成功时,其值为 "ok"。由于类型定义为 string 而非枚举,业务代码中通常不做严格判断,仅用于确认响应结构完整。
2.2 participant_info:参与者信息容器
participant_info 是对应文档 docs/interfaces/responses/StoryQuizParticipantsFeedResponseParticipant_info.md 中的 StoryQuizParticipantsFeedResponseParticipant_info 接口,它聚合了测验的核心元数据:
| 属性名 | 类型 | 含义 |
|---|---|---|
quiz_id |
string |
该测验贴纸的唯一标识,也是后续调用回答接口、拉取参与明细时使用的 stickerId |
participants |
StoryQuizParticipantsFeedResponseParticipantsItem[] |
参与答题的用户明细数组 |
max_id |
null |
分页游标。在当前类型定义中固定为 null,表示该响应通常一次性返回全部数据 |
more_available |
boolean |
是否还有更多数据可分页拉取 |
从类型定义看(src/responses/story-quiz-participants.feed.response.ts 第 6-10 行),max_id 被标注为字面量 null,与故事投票(poll)等其他贴纸 Feed 的 string 类型游标不同,说明测验参与者的数量一般较小,单页即可返回完。
三、参与者明细:ParticipantsItem 与 User 子结构
participant_info.participants 的每个元素是 StoryQuizParticipantsFeedResponseParticipantsItem(对应文档 docs/interfaces/responses/StoryQuizParticipantsFeedResponseParticipantsItem.md):
| 属性名 | 类型 | 含义 |
|---|---|---|
user |
StoryQuizParticipantsFeedResponseUser |
答题用户的资料对象 |
answer |
number |
用户选择的答案索引(对应 StoryQuiz.options 数组中的第几项,从 0 开始) |
ts |
number |
答题时间戳(Unix 毫秒级时间戳) |
其中 user 为 StoryQuizParticipantsFeedResponseUser(对应文档 docs/interfaces/responses/StoryQuizParticipantsFeedResponseUser.md),包含 8 个字段:
| 属性名 | 类型 | 含义 |
|---|---|---|
pk |
number |
用户唯一数字 ID |
username |
string |
用户名 |
full_name |
string |
显示名称 |
is_private |
boolean |
是否私密账号 |
profile_pic_url |
string |
头像 URL |
profile_pic_id |
string |
头像媒体 ID |
is_verified |
boolean |
是否蓝 V 认证账号 |
latest_reel_media |
number |
最新一条 Story 的时间戳,0 表示当前无有效 Story |
这组字段覆盖了"谁在什么时候、选了哪个答案"的完整信息,足以支撑答题统计、粉丝画像等二次开发。
四、源码级调用链:从 FeedFactory 到 HTTP 请求
虽然接口文档本身只描述了响应结构,但其真实数据流依赖三个源码文件,理解它们才能正确使用这一响应类型。
4.1 FeedFactory 工厂方法
在 src/core/feed.factory.ts 中,FeedFactory 暴露了 storyQuizParticipants 方法:
public storyQuizParticipants(
mediaId: string,
stickerId: string | number,
): MediaStickerResponsesFeed<
StoryQuizParticipantsFeedResponseRootObject,
StoryQuizParticipantsFeedResponseParticipantsItem
> {
return plainToClassFromExist(new MediaStickerResponsesFeed<any, any>(this.client), {
mediaId,
stickerId,
name: 'story_quiz_participants',
rootName: 'participant_info',
itemName: 'participants',
});
}
关键点:
mediaId:包含测验贴纸的那条 Story 的媒体 ID;stickerId:测验贴纸 ID,与响应中的quiz_id一致;- 工厂通过
plainToClassFromExist将配置注入MediaStickerResponsesFeed,并把rootName设置为participant_info、itemName设置为participants——这正是RootObject上participant_info.participants的取值路径。
4.2 MediaStickerResponsesFeed 通用贴纸响应 Feed
src/feeds/media.sticker-responses.feed.ts 是所有贴纸响应类 Feed(投票、提问、测验、滑杆)共用的基类实现:
async request(): Promise<T> {
const { body } = await this.client.request.send({
url: `/api/v1/media/${this.mediaId}/${this.stickerId}/${this.name}/`,
method: 'GET',
qs: { max_id: this.maxId || void 0 },
});
this.state = body;
return body;
}
- 请求路径拼接为
/api/v1/media/{mediaId}/{stickerId}/story_quiz_participants/; - 携带
max_id查询参数以支持分页; statesetter 从响应中读取max_id与more_available,交由 src/core/feed.ts 的isMoreAvailable()驱动后续翻页。
4.3 Feed 基类的迭代与重试
src/core/feed.ts 提供了通用的 items$(RxJS Observable 流)与 observable() 方法:每当 items() 返回一页后,若 moreAvailable 为真则继续请求下一页,直到拉完或 unsubscribe 取消订阅。同时内置 @lifeomic/attempt 重试策略(默认 maxAttempts: 10,对 400/429/500/502 状态码自动退避重试),这在拉取大列表时能有效缓解 Instagram 的限流。
五、实战:拉取测验参与者并遍历
5.1 基础用法(同步迭代一页)
import { IgApiClient } from 'instagram-private-api';
const ig = new IgApiClient();
ig.state.generateDevice(process.env.IG_USERNAME);
await ig.account.login(process.env.IG_USERNAME, process.env.IG_PASSWORD);
// mediaId:包含测验贴纸的 Story 媒体 ID;quizId:测验贴纸 ID
const feed = ig.feed.storyQuizParticipants(mediaId, quizId);
const participants = await feed.items(); // StoryQuizParticipantsFeedResponseParticipantsItem[]
for (const item of participants) {
console.log({
username: item.user.username,
answerIndex: item.answer, // 第几个选项
answeredAt: new Date(item.ts), // 答题时间
verified: item.user.is_verified,
});
}
5.2 全量拉取与分页判断
由于测验参与者 Feed 在类型定义中 max_id 为 null、more_available 为布尔值,稳妥的写法是借助基类能力循环分页:
const feed = ig.feed.storyQuizParticipants(mediaId, quizId);
const all: any[] = [];
do {
const page = await feed.items();
all.push(...page);
} while (feed.isMoreAvailable());
console.log(`共 ${all.length} 名用户参与了本次测验`);
若数据量较大,也可改用 feed.items$(Observable)流式消费,并在需要时提前取消订阅,避免不必要的请求。
5.3 按答案分组统计
const answers = new Map<number, number>();
for (const p of all) {
answers.set(p.answer, (answers.get(p.answer) ?? 0) + 1);
}
// 结合 StoryQuiz.options 的文本,即可输出"每个选项多少人选"
六、配套能力:发布测验与回答测验
参与者数据通常不是孤立使用的。仓库源码中还有两个与 quiz_id/answer 语义直接相关的模块,可构成完整闭环。
6.1 发布测验贴纸:QuizSticker
src/sticker-builder/stickers/quiz.sticker.ts 定义了 QuizSticker,其 key 为 'story_quizs'、id 为 'quiz_story_sticker_default',并带有一系列默认值:
correctAnswer: number;
options: string[] | Array<{ text: string; count: number }>;
question: string;
textColor?: string = '#ffffff';
startBackgroundColor?: string = '#262626';
endBackgroundColor?: string = '#262626';
viewerCanAnswer?: boolean = false;
viewerAnswer?: number = -1;
发布侧的类型定义见 docs/interfaces/types/StoryQuiz.md 与 src/types/media.configure-story.options.ts,其中 options 数组元素含 text(选项文案)与 count(该选项被选次数)。发布时由 src/services/publish.service.ts 将 options.quiz 序列化为 configureOptions.story_quizs = [options.quiz],并把 quiz_story_sticker_default 加入 story_sticker_ids。
6.2 回答测验:storyQuizAnswer
src/repositories/media.repository.ts 提供 storyQuizAnswer(mediaId, quizId, answer):
public async storyQuizAnswer(
mediaId: string,
quizId: string | number,
answer: '0' | '1' | '2' | '3' | string,
): Promise<MediaUpdatedMediaResponseRootObject> {
const { body } = await this.client.request.send({
url: `/api/v1/media/${mediaId}/${quizId}/story_quiz_answer/`,
method: 'POST',
form: this.client.request.sign({
_csrftoken: this.client.state.cookieCsrfToken,
_uuid: this.client.state.uuid,
answer,
}),
});
return body;
}
注意 answer 参数的类型约束:'0' | '1' | '2' | '3' | string(索引从 0 开始)。这与参与明细中 ParticipantsItem.answer: number 一一对应——即你用哪个索引回答,拉取参与者列表时就能看到相同索引值,从而将答题用户的 answer 映射回 StoryQuiz.options[answer].text 得到具体选项文案。
七、注意事项与边界
- 会话与登录态:所有 Feed 请求依赖
ig.state中的 cookies(cookieCsrfToken、cookieUserId、uuid),必须先完成generateDevice()与account.login(),否则会触发IgLoginRequiredError。 - 限流与重试:拉取大量数据时建议依赖 src/core/feed.ts 内置的退避重试;如业务自有节流需求,可向
observable(semaphore)传入信号量函数控制请求节奏。 max_id类型差异:测验参与者响应中的max_id声明为null,与其他贴纸 Feed(如投票、滑杆)的字符串游标不同;若后续 Instagram 端返回分页游标,SDK 的statesetter 逻辑仍能兼容读取,但类型定义需自行留意更新。answer与ts的语义:answer是选项索引而非选项文本,ts为 Unix 毫秒时间戳,做统计与排序时需自行转换。- 隐私约束:私密账号用户(
is_private: true)的数据仍会出现在参与者列表中,二次分发时应遵守平台数据使用政策。
八、小结
StoryQuizParticipantsFeedResponseRootObject 虽只是一个两层结构的小接口,但它串联起 instagram-private-api 中"测验贴纸"这条完整链路:上游由 QuizSticker + PublishService 发布测验,中游由 MediaStickerResponsesFeed 以 /api/v1/media/{mediaId}/{stickerId}/story_quiz_participants/ 拉取参与明细,下游由 storyQuizAnswer 触发并回流答题记录。理解这一响应结构及其在 src/responses/story-quiz-participants.feed.response.ts、src/core/feed.factory.ts 与 src/feeds/media.sticker-responses.feed.ts 中的实现位置,即可在业务中稳定地完成测验互动数据的采集与分析。