instagram-private-api Story 数据洞察响应结构解析：InsightsServiceStoryResponseData 接口完全指南-开发者社区

后端

【免费下载链接】instagram-private-api

NodeJS Instagram private API SDK. Written in TypeScript.

项目地址：https://gitcode.com/gh_mirrors/in/instagram-private-api

本篇技术指南围绕instagram-private-api（NodeJS Instagram 私有 API SDK，TypeScript 编写）中 Story 数据洞察响应类型InsightsServiceStoryResponseData展开，从接口定义、嵌套结构、字段语义到其背后的 GraphQL 请求链路（InsightsService.story()→AdsRepository.graphQL()）逐一剖析，并对照列表型洞察数据源StoriesInsightsFeed，帮助读者理解单条 Story 详情与批量 Story 网格两种数据形态的差异，从而在自己的数据抓取与分析项目中正确消费这两类响应。

一、接口定位：响应类型体系中的一环

在instagram-private-api的文档体系中，InsightsServiceStoryResponseData归属于responses命名空间，是"Story 单条详情洞察"响应类型链路的中间节点。它定义在 insights.service.story.response.ts 中，并通过 src/responses/index.ts 的export * from './insights.service.story.response'统一对外导出，同时被收录在 docs/modules/responses.md 的接口索引中。

与其相关的四个姊妹接口构成一条完整的类型链：

接口	文档	职责
`InsightsServiceStoryResponseRootObject`	RootObject 文档	响应的最外层包装，携带`data`字段
`InsightsServiceStoryResponseData`	Data 文档	本次要讲解的中间层，携带`media`字段
`InsightsServiceStoryResponseMedia`	Media 文档	携带 Story 详情、互动指标与作者信息
`InsightsServiceStoryResponseInline_insights_node`	节点文档	内联洞察节点，记录状态与指标
`InsightsServiceStoryResponseInstagram_actor`	Actor 文档	内容发布者（账号主体）信息

二、InsightsServiceStoryResponseData 的源码结构与职责

依据 TypeDoc 生成的接口文档以及底层 TypeScript 源码，该接口的完整定义只有一条属性：

export interface InsightsServiceStoryResponseData { media: InsightsServiceStoryResponseMedia; }

它是整个 Story 洞察响应中"承载业务数据"的关键一层：上层RootObject只负责包装data，而这一层则把真正的 Story 详情对象以media命名暴露出来。从源码结构看，media就是一条具体 Story 的洞察聚合，包含媒体标识、作者信息、创建时间以及各项互动计数（详见第三节）。

值得注意的是，InsightsServiceStoryResponseData没有其他元数据字段（如状态码、消息文本等），这与 Instagram 广告/洞察类 GraphQL 接口的典型返回风格一致——成功时数据全部收敛在data子树中。

三、核心子对象 InsightsServiceStoryResponseMedia 字段详解

InsightsServiceStoryResponseMedia（源码）是整套结构中信息量最大的对象，共 9 个字段，覆盖"媒体标识、作者、时间、互动指标"四类信息：

字段	类型	语义
`instagram_media_id`	`string`	Instagram 侧的媒体 ID（Story 的公开标识）
`inline_insights_node`	`InsightsServiceStoryResponseInline_insights_node`	内联洞察节点，携带`state`与`metrics`
`id`	`string`	当前对象在返回数据中的内部 ID
`instagram_media_owner_id`	`string`	该 Story 所属账号（发布者）的 Instagram 用户 ID
`instagram_actor`	`InsightsServiceStoryResponseInstagram_actor`	发布者主体对象，含`instagram_actor_id`与`id`
`creation_time`	`number`	Story 的创建时间（Unix 时间戳，秒级）
`shopping_outbound_click_count`	`number`	Story 中购物组件（如有）的外部链接点击次数
`taps_back_count`	`number`	用户在 Story 上"点击返回"的次数，可反映用户回看前一条的意愿
`taps_forward_count`	`number`	用户在 Story 上"点击前进/跳过"的次数

两个嵌套对象同样值得展开：

inline_insights_node（源码）：state: string表示洞察节点当前的状态；metrics: null被声明为字面量null类型——从源码结构可以推断，当前版本的 Story 详情响应中该节点不携带扩展指标，指标数据直接平铺在Media层。
instagram_actor（源码）：instagram_actor_id是账号的 Instagram 内部 ID，id是本次返回中的本地标识。

四、完整响应链：从 RootObject 到叶子字段

结合三个接口的源码，一条完整 Story 详情响应的 JSON 形状可以还原为：

{ "data": { "media": { "instagram_media_id": "1234567890123456789", "inline_insights_node": { "state": "ok", "metrics": null }, "id": "17841404123456789", "instagram_media_owner_id": "1234567890", "instagram_actor": { "instagram_actor_id": "1234567890", "id": "1234567890" }, "creation_time": 1697000000, "shopping_outbound_click_count": 0, "taps_back_count": 12, "taps_forward_count": 87 } } }

访问路径为：RootObject.data→Data.media→Media.xxx。其中RootObject定义在 insights.service.story.response.ts，data的类型即本次主角InsightsServiceStoryResponseData。

五、数据从何而来：InsightsService.story 与底层 GraphQL 链路

InsightsServiceStoryResponse*类型体系由 InsightsService 的洞察能力支撑。InsightsService挂载在IgApiClient实例上（见 client.ts 的public insights = new InsightsService(this)），其story方法定义在 insights.service.ts：

public story(storyId: string): Promise<StoriesInsightsFeedResponseRootObject> { return this.client.ads.graphQL<StoriesInsightsFeedResponseRootObject>({ surface: { name: 'story', friendlyName: 'IgInsightsStoryInsightsAppQuery', }, documentId: '2164420446988319', variables: { query_params: { access_token: '', id: storyId, }, }, }); }

调用方式为ig.insights.story(storyId)，其中storyId是目标 Story 的媒体 ID。该请求最终进入 AdsRepository.graphQL，构造一个 POST 到/api/v1/ads/graphql/的请求：

查询参数携带locale（来自客户端状态的语言设置）、vc_policy: 'insights_policy'以及surface=story；
表单字段包含fb_api_caller_class: 'RelayModern'、fb_api_req_friendly_name: 'IgInsightsStoryInsightsAppQuery'、doc_id: '2164420446988319'，variables以 JSON 字符串形式提交。

documentId（2164420446988319）对应 Instagram 端注册的"Story 洞察 App 查询"，与account（2552829571413315）、post（2009845309144121）、igtv（1744089735627228）三组 documentId 并列，共同构成InsightsService的四类洞察入口。

需要指出一个源码层面的细节：InsightsService.story()当前声明的返回类型是StoriesInsightsFeedResponseRootObject（见 stories-insights.feed.response.ts），而InsightsServiceStoryResponseRootObject/Data/Media类型虽然完整定义并导出，却在当前方法签名中未被直接引用。可以推断，InsightsServiceStoryResponse*更接近该查询所对应响应结构的类型快照/备用定义；若直接消费原始响应体（例如绕过类型断言自行解析），RootObject.data.media即对应本篇文章的核心接口InsightsServiceStoryResponseData。

六、单条详情与列表网格：与 StoriesInsightsFeed 的对照

与insights.story()不同，StoriesInsightsFeed 提供的是"批量 Story 洞察列表"视图，二者共用同一套 GraphQL 通道（client.ads.graphQL），但查询不同：

列表请求使用documentId: '1995528257207653'、friendlyName: 'IgInsightsStoryGridSurfaceQuery'（见 stories-insights.feed.ts）；
列表按timeframe（ONE_DAY | ONE_WEEK | TWO_WEEKS）过滤，每次取count: 15条，并通过end_cursor/has_next_page游标分页；
列表中的每条 Story 由StoriesInsightsFeedResponseNode承载（源码），其指标字段比详情版更丰富，包含display_url（缩略图地址）、exits_count（退出次数）、impression_count（曝光数）、reach_count（触达数）、replies_count（回复数）、story_swipe_away_count（滑动离开数）以及taps_back_count/taps_forward_count。

对比可见：

详情响应（InsightsServiceStoryResponseMedia）强调"单条 Story"的标识、作者与购物外链点击；
列表响应（StoriesInsightsFeedResponseNode）强调"批量归档"的曝光、触达、退出等运营指标，且二者都包含inline_insights_node这一{ state, metrics: null }结构。

列表的常规用法是经由 feed.factory.ts 的storiesInsights(timeframe)工厂方法创建 Feed 实例，再调用items()拉取数据。

七、实战：在业务代码中消费 Story 洞察数据

以下示例展示了如何组合使用本项目的两个洞察入口，将"列表概览 + 单条详情"结合：

import { IgApiClient } from 'instagram-private-api'; async function main() { const ig = new IgApiClient(); // 登录（需具备可访问洞察数据的账号） ig.state.generateDevice('your_device_seed'); await ig.account.login('username', 'password'); // 方式一：批量列表，按周维度拉取 Story 洞察 const feed = ig.feed.storiesInsights('ONE_WEEK'); const edges = await feed.items(); for (const edge of edges) { const node = edge.node; console.log(node.instagram_media_id, node.reach_count, node.impression_count); } // 方式二：单条 Story 详情（返回体结构对应 RootObject -> data -> media） const storyId = '17841404123456789'; // 示例 Story ID const detail = await ig.insights.story(storyId); // 从原始响应中按 InsightsServiceStoryResponseData 的结构取数： // detail.data?.user.business_manager... 或按实际返回解析 data.media 字段 } main().catch(console.error);

需要注意：insights.story()的 TypeScript 返回类型与InsightsServiceStoryResponseData的字段布局存在上文所述差异，实际取数时建议以服务端返回的真实 JSON 为准，并用本节讲解的Data.media结构作为解析参考模板。

八、使用注意事项

数据可得性：从StoriesInsightsFeed的business_manager嵌套结构（stories-insights.feed.response.ts）可以推断，Story 洞察数据与 Instagram 的 Business Manager 体系强相关，通常仅对专业/商业账号开放；SDK 本身不校验账号类型，是否返回数据由 Instagram 服务端决定。
空值与状态：inline_insights_node.metrics固定为null，state为字符串状态；在解析时不要假定 metrics 一定存在。
时间戳语义：creation_time为数值型 Unix 时间戳，建议转换为Date后再做时间维度的聚合统计。
版本耦合：documentId与friendlyName属于 Instagram 内部 GraphQL 注册标识（见 insights.service.ts），Instagram 端变更查询注册信息时，SDK 需同步更新，使用时应留意本仓库版本与 Instagram 服务端的兼容窗口。

九、总结

InsightsServiceStoryResponseData虽然只是instagram-private-api响应类型体系中的一个"中转层"接口，但它是理解 Story 单条详情洞察数据结构的关键入口。通过它你可以顺藤摸瓜，掌握media下 9 个字段的完整语义、inline_insights_node与instagram_actor两个子对象的结构、insights.story()到AdsRepository.graphQL的底层请求链路，以及单条详情与StoriesInsightsFeed批量列表两种数据形态的取舍。对于希望深度分析 Story 运营数据（点击返回率、前进率、购物外链点击等）的开发者而言，这份结构解析足以支撑你在 SDK 之上构建自己的数据管道。