对象模型
Tweet
id、text 和 created_at。Tweet 对象还是多个子对象的“父”对象，包括 user、media、poll 和 place。在请求 Tweet 对象的这些根级字段时，请使用字段参数 tweet.fields。
可以在 user 资源中查找并展开 Tweet 对象。与所请求 Tweet 相关的其他 Tweet 也可以在 Tweet 资源中查找并展开。该对象可通过在 user 资源中使用 ?expansions=pinned_tweet_id 或在 Tweet 资源中使用 ?expansions=referenced_tweets.id 来展开，以仅获取默认字段的对象。在请求其他字段以补全对象时，请将该 expansion 与字段参数 tweet.fields 搭配使用。
| 字段值 | 类型 | 描述 | 使用方式 |
|---|---|---|---|
| id（默认） | 字符串 | 所请求的 Tweet 的唯一标识符。 | 使用此方法以编程方式获取特定的 Tweet。 |
| 文本（默认） | 字符串 | Tweet 的实际 UTF-8 文本。参见twitter-text查看有效字符的详细说明。 | 关键词抽取与情感分析/分类。 |
| edit_history_tweet_ids（默认） | 对象 | 用于标示某条 Tweet 所有版本的唯一标识符。未经过编辑的 Tweet 只有一个 id；有编辑历史的 Tweet 会有多个 id。 | 使用这些信息查找某条 Tweet 的编辑记录。 |
| 文章 | 对象 | 包含此 Tweet 中所含 Article 的元数据。 | 用于获取文章的文本和实体。 |
| 附件 | 对象 | 指定此 Tweet（如有）所包含的附件类型。 | 了解针对所请求 expansions 返回的对象。 |
| author_id | 字符串 | 发布此 Tweet 的用户的唯一标识符。 | 填充（hydrate）User 对象，分享数据集以供同行评审。 |
| card_uri | 字符串 | 此条 Tweet 中所含 Card 的 URI。 | |
| community_id | 字符串 | 此 Post 所属 Community 的唯一标识符。 | |
| context_annotations | 数组 | 包含该 Tweet 的上下文注释。 | 实体识别/抽取、主题分析。 |
| conversation_id | 字符串 | 该会话中原始 Tweet 的 Tweet ID（包括直接回复及其后续层级的回复）。 | 用它从一条 Tweet 重建完整的会话。 |
| created_at | 日期（ISO 8601） | Tweet 的创建时间。 | 适用于时间序列分析，并帮助了解 Tweet 的创建时间。 |
| display_text_range | 数组 | 一个数组，包含要展示的文本片段的起始索引和结束索引。 | 有助于了解长篇 Post 默认显示的文本区段。 |
| 编辑_控件 | 对象 | 指示 Tweet 还可编辑的剩余时间和剩余编辑次数。 | 用于判断某条 Tweet 是否具备可编辑资格。 |
| entities（实体） | 对象 | 从 Tweet 文本中解析出的实体。请参阅 Twitter 对象中的 entities。 | 提供有关话题标签、URL、提及等的附加信息。 |
| 地理 | 对象 | 指示带地理标签的 Tweet 的位置或地点。 | 使用此项来获取带地理标记的 Tweet 的位置。 |
| in_reply_to_user_id | 字符串 | 如果所表示的 Tweet 为回复，则此字段将包含原始 Tweet 的作者 id。 | 确定某条 Tweet 是否为对另一条 Tweet 的回复。 |
| 语言 | 字符串 | 如果由 Twitter 检测到，则为该 Tweet 的语言。 | 按口语语言对 Tweet 进行分类。 |
| 非公开_指标 | 对象 | 请求时该 Tweet 的非公开参与度指标。需要用户上下文认证。 | 确定该 Tweet 产生的总展示次数。 |
| note_tweet | 对象 | 包含长文 Post 的完整文本（>280 个字符）。 | 获取一条 Post 的完整文本。 |
| organic_metrics | 对象 | 在请求时点、在自然曝光情境下为该 Tweet 追踪的互动指标。需要用户上下文认证。 | 衡量该 Tweet 的自然参与度。 |
| 可能_敏感 | 布尔 | 指示该内容是否可能被识别为敏感信息。 | 研究特定类型内容的传播情况。 |
| promoted_metrics | 对象 | 在推广场景中追踪的该 Tweet 的互动指标，数值以请求时的状态为准。需要用户上下文认证。 | 在 Tweet 推广期间衡量其互动表现。 |
| public_metrics | 对象 | 请求时该 Tweet 的公开互动指标。 | 衡量 Tweet 参与度。 |
| referenced_tweets | 数组 | 此 Tweet 所关联的 Tweet 列表，例如转推、引用 Tweet 或回复。 | 理解转推等内容的对话属性。 |
| reply_settings | 字符串 | 显示哪些人可以回复指定的 Tweet。选项包括”所有人”,“提及_用户”，和”粉丝”。 | 确定该 Tweet 的对话回复设置。 |
| 已扣留 | 对象 | 包含与被屏蔽内容相关的屏蔽详情因法律要求隐藏的内容。 | |
| 作用域（scopes） | 对象 | 包含该 Tweet 的范围详情。 | 指明可查看该 Post 的对象。仅对推广的 Post 返回。 |
| media_metadata | 数组 | 包含该 Tweet 的媒体附件元数据。 | 获取更多元数据，例如alt_text某条 Tweet 的’的媒体附件。 |
$BEARER_TOKEN 替换为你自己生成的 Bearer Token。
User
user.fields。
user 对象也可能作为子对象出现在 Tweet 对象中，并可被展开。可通过 ?expansions=author_id 或 ?expansions=in_reply_to_user_id 进行展开，以获取仅包含默认字段的精简对象。若需请求更多字段以补全该对象，请将该扩展与字段参数配合使用：user.fields。
| 字段取值 | 类型 | 描述 | 使用方式 |
|---|---|---|---|
| id（默认） | 字符串 | 该用户的唯一标识符。"id": "2244994945" | 使用此方法以编程方式获取特定 Twitter 用户的信息。 |
| 名称（默认） | 字符串 | 用户在其个人资料中设置的名称。不一定是本人的真实姓名。通常限制为 50 个字符，但可能会调整。"name": "Twitter Dev" | |
| 用户名（默认） | 字符串 | 该用户用于自我标识的 Twitter 屏幕名称、用户名（handle）或别名。用户名具有唯一性，但可能会变更。通常最长为 15 个字符，但某些早期账户可能使用更长的名称。"username": "TwitterDev" | |
| 隶属 | 对象 | 包含用户的详细信息’的隶属关系。 | 可用于获取某个用户’的联盟徽章。 |
| 已确认_邮箱 | 字符串 | 已通过身份验证用户的已确认电子邮件地址。 | |
| 连接_状态 | 数组 | 提供一个列表，说明正在进行身份验证的用户与被查询用户之间的关系，例如：正在关注、被其关注、已发送关注请求、已收到关注请求、已屏蔽、已静音 ”连接_状态”: [ “关注_请求_已收到”， “关注_请求_已发送”， “屏蔽中”， “已关注_作者”， “关注”， “静音” ] | 可用于判断经过身份验证的用户与被查询用户之间的关联状态。 |
| 创建时间_于 | 日期（ISO 8601） | 用户账户在 Twitter 上创建的 UTC 日期时间。"created_at": "2013-12-14T04:35:55.000Z" | 可用于判断某人使用 Twitter 的时间长度 |
| 说明 | 字符串 | 该用户的文本’用户的个人简介（亦称“bio”），如果该用户有提供的话。"description": "X Dev 团队之声——关于 X API 的更新、新闻与活动的官方渠道。" | |
| 实体 | 对象 | 包含有关对用户具有特殊含义的文本的详细信息’的说明。"entities": { <br/> "url": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.x.com/en/community" <br/> } <br/> ] <br/> }, <br/> "description": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.x.com/en/community" <br/> }, <br/> "hashtags": [ <br/> { <br/> "start": 23, <br/> "end": 30, <br/> "tag": "DevRel" <br/> }, <br/> { <br/> "start": 113, <br/> "end": 130, <br/> "tag": "BlackLivesMatter" <br/> }, <br/> "mentions": [ <br/> { <br/> "start": 0, <br/> "end": 10, <br/> "tag": "TwitterDev" <br/> }, <br/> "cashtags": [ <br/> { <br/> "start": 12, <br/> "end": 16, <br/> "tag": "twtr" <br/> } <br/> ] <br/> } <br/> } | Entities 是 JSON 对象，用于提供与描述相关的主题标签、链接、用户提及和现金标签的补充信息。有关详细信息，请参阅相应的实体。 所有用户开始索引为闭区间，而所有用户结束索引为左闭右开（不包含上界）。 |
| 是_身份_已验证 | 布尔 | 指示该用户是否已完成身份ID验证。 | |
| 位置 | 字符串 | 用户所指定的位置’用户在其个人资料中填写的位置（如果有）。由于这是自由输入的值，可能并非有效位置，但在使用位置条件进行搜索时，可能会进行模糊匹配。"location": "127.0.0.1" | |
| 大多数_最近_Tweet_id | 字符串 | 该用户的唯一标识符’其最新的 Tweet。 | 获取该用户的最新 Tweet。 |
| 仿作 | 布尔 | 指示该用户账户是否带有“Parody”标签。 | |
| 已置顶_Tweet_id | 字符串 | 该用户的唯一标识符’置顶的 Tweet。"pinned_tweet_id": "1255542774432063488" | 确定该用户个人资料页顶部置顶的 Tweet。可用于推断该用户的语言。 |
| 个人信息_横幅_URL | 字符串 | 此用户的个人资料横幅图片的 URL，如显示在该用户主页上’的个人资料。"profile_banner_url": "https://pbs.twimg.com/profile_banners/1716450569358098432/1721022977" | 可用于下载此用户’的个人资料横幅。 |
| 个人资料_图像_url | 字符串 | 此用户的个人资料图片的 URL，如同在其个人资料页中所示’的资料。"profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg" | 可用于下载该用户的数据’的头像。 |
| 受保护 | 布尔 | 指示该用户是否选择保护其 Tweet（换言之，该用户的 Tweet 是否为受保护状态）‘s 的推文是私密的)。"protected": false | |
| 公共_度量 | 对象 | 包含该用户的活动详情。"public_metrics": { "followers_count": 507902, "following_count": 1863, "tweet_count": 3561, "listed_count": 1550 } | 可用于评估某位 Twitter 用户的触达范围或影响力、量化其兴趣广度，以及衡量其在 Twitter 上的参与度。 |
| 接收_您的_私信 | 布尔 | 指示该用户是否接收来自已认证用户的私信（DM）‘的私信（DM）。 | |
| 订阅 | 对象 | 包含该用户是否已订阅经过身份验证用户的详细信息。 | |
| 订阅_media_key | 字符串 | 表示已验证用户所持有的 X Premium 订阅类型的字符串。示例：无，基础，高级，PremiumPlus。将始终返回无如果该用户不是已认证用户。 | |
| url | 字符串 | 用户资料中指定的 URL（如果有）。‘如果有，则来自该用户的个人资料。"url": "https://t.co/3ZX3TNiZCY" | Twitter 用户在其个人资料中提供的 URL。它可能是主页，但不一定是。 |
| 已验证 | 布尔 | 指示该用户是否为已验证的 Twitter 用户。"verified": true | 指示该 Twitter 用户的账户是否已通过验证。已验证账户可让公众了解该账户（具有公共利益）的真实性。 |
| 已验证_粉丝_计数器 | 字符串 | 表示某用户经验证关注者数量的字符串。 | |
| 已验证_media_key | 字符串 | 表示用户验证类型的字符串。例如：“蓝”，“业务”，“政府” | |
| 被扣留 | 对象 | 包含与被扣留内容相关的扣留详情（如适用）受限内容（如适用）。 |
$BEARER_TOKEN 替换为你自己生成的 Bearer Token。
Space
expansions 查询参数中添加至少一个 host_ids、creator_id、speaker_ids、mentioned_user_ids，即可展开这些对象。
与 Tweet 不同，Spaces 具有时效性，在结束后或被创建者取消时将不可用。当你的应用处理 Spaces 数据时，你需要返回最新信息，并且必须移除平台上已不再可用的数据。Spaces 查找端点可帮助你确保尊重用户的期望和意图。
| Field Value | Type | Description | How it can be used |
|---|---|---|---|
| id (default) | string | 请求的 Space 的唯一标识符。"id": "1zqKVXPQhvZJB" | 唯一标识响应中返回的 Space。 |
| state (default) | string | 指示该 Space 已开始、将开始或已结束。"state": "live" | 筛选正在进行或已排期的 Spaces。 |
| created_at | date (ISO 8601) | 此 Space 的创建时间。"created_at": "2021-07-04T23:12:08.000Z" | 了解 Space 的创建时间并按时间排序。 |
| creator_id | string | Space 创建者的唯一标识符。"creator_id": "2244994945" | |
| ended_at | date (ISO 8601) | Space 的结束时间（如适用）。"ended_at": "2021-07-04T00:11:44.000Z" | 确定直播 Space 的结束时间以计算持续时长。 |
| host_ids | array | Space 主持人的唯一标识符。"host_ids": ["2244994945", "6253282"] | 展开 User 对象，了解互动情况。 |
| lang | string | Space 的语言（如检测到）。"lang": "en" | 按语言对 Spaces 进行分类。 |
| is_ticketed | boolean | 指示是否为售票 Space。"is_ticketed": false | 突出显示感兴趣的内容。 |
| invited_user_ids | array | 被邀请为发言者的用户 ID 列表。"invited_user_ids": ["2244994945", "6253282"] | 展开 User 对象，了解互动情况。 |
| participant_count | integer | Space 中的用户数量，包括主持人和发言者。"participant_count": 420 | 了解互动情况，生成报告。 |
| subscriber_count | integer | 为某个 Space 设置提醒的人数。"subscriber_count": 36 | 了解活动关注度。 |
| scheduled_start | date (ISO 8601) | Space 的计划开始时间。"scheduled_start": "2021-07-14T08:00:00.000Z" | 与日历通知集成。 |
| speaker_ids | array | 任意时间点发言的用户列表。"speaker_ids": ["2244994945", "6253282"] | 展开 User 对象，了解互动情况。 |
| started_at | date (ISO 8601) | Space 的实际开始时间。"started_at": "2021-07-14T08:00:12.000Z" | 确定 Space 的开始时间。 |
| title | string | Space 的标题。"title": "Say hello to the Space data object!" | 分析关键词、话题标签和提及。 |
| topic_ids | array | 由 Space 创建者选择的话题 ID。"topic_ids": ["2244994945", "6253282"] | 分析关键词、话题标签和提及。 |
| id | date (ISO 8601) | Space 元数据的最后更新时间。"updated_at": "2021-07-11T14:44:44.000Z" | 保持信息为最新。 |
$BEARER_TOKEN 替换为你自己生成的 Bearer Token。
列表
list.fields。
List 对象不会作为其他数据对象的子对象出现。不过，可以在用户资源中找到并展开用户对象。通过在 expansions 查询参数中添加 owner_id，这些对象即可用于扩展。在请求其他字段以完善主要的 List 对象时，将此扩展与 list.fields 字段参数一起使用，并使用 user.fields 来完善扩展对象。
| 字段值 | 类型 | 说明 | 用途 |
|---|---|---|---|
| id（默认） | string | 此 List 的唯一标识符。"id": "2244994945" | 用于以编程方式检索特定 List 的信息。 |
| name（默认） | string | 创建 List 时指定的名称。"name": "Twitter Lists" | |
| created_at | date (ISO 8601) | 创建该 List 的 UTC 日期时间。"created_at": "2013-12-14T04:35:55.000Z" | 用于判断某个 List 在 Twitter 上存在了多长时间。 |
| description | string | 向用户说明该 List 的简要描述。"description": "People that are active members of the Bay area cycling community on Twitter." | |
| follower_count | integer | 关注此 List 的用户数量。"follower_count": 198 | |
| member_count | integer | 此 List 的成员数量。"member_count": 60 | |
| private | boolean | 指示该 List 是否为私密。"private": false | |
| owner_id | string | 此 List 所有者的唯一标识符。"owner_id": "1255542774432063488" | 可用于判断该用户是否拥有其他 List，并展开 User 对象。 |
$BEARER_TOKEN 替换为你生成的 Bearer Token。
媒体
?expansions=attachments.media_keys 可展开以获取仅包含默认字段的精简对象。请求更多字段以补全对象时，将该扩展与字段参数 media.fields 搭配使用。
| 字段值 | 类型 | 说明 | 用途 |
|---|---|---|---|
| media_key（默认） | string | 已展开媒体内容的唯一标识符。 "media_key": "13_1263145212760805376" | 可用于以编程方式检索媒体 |
| type（默认） | string | 内容类型（animated_gif、photo、video）。 "type": "video" | 将媒体归类为照片、GIF 或视频 |
| url | string | 指向 Twitter 上媒体文件的直接 URL。 | 对于照片，返回带有 URL 字段的 Media 对象 |
| duration_ms | integer | 当 type 为 video 时提供。视频时长（毫秒）。 "duration_ms": 46947 | |
| height | integer | 此内容的高度（像素）。 "height": 1080 | |
| non_public_metrics | object | 请求时刻的媒体内容非公开互动指标。需要用户上下文认证。 "non_public_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183,} | 判断视频互动：有多少用户分别观看到视频的四分之一区间。 |
| organic_metrics | object | 在自然场景中跟踪的媒体内容互动指标，取请求时刻。需要用户上下文认证。 "organic_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183, "view_count": 629} | 判断媒体的自然互动。 |
| preview_image_url | string | 此内容的静态占位预览图 URL。 "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg" | |
| promoted_metrics | object | 在推广场景中跟踪的媒体内容互动指标，取请求时刻。需要用户上下文认证。 "promoted_metrics": { "playback_0_count": 259, "playback_100_count": 15, "playback_25_count": 113, "playback_50_count": 57, "playback_75_count": 25, "view_count": 124} | 判断 Tweet 被推广时的媒体互动。 |
| public_metrics | object | 请求时刻的媒体内容公开互动指标。 "public_metrics": { "view_count": 6865141} | 判断附加到该 Tweet 的视频的总观看次数。 |
| width | integer | 此内容的宽度（像素）。 "width": 1920 | |
| alt_text | string | 用于无障碍的图像描述。最长 1000 个字符。目前仅可为图像添加替代文本。 "alt_text": "Rugged hills along the Na Pali coast on the island of Kauai" | 供视障用户查看时提供图像的文字说明。 |
| variants | array | 每个媒体对象可能具有多个显示或播放版本，分辨率或格式各异。 "variants": [{ "bit_rate": 632000, "content_type": "video/mp4", "url": "https://video.twimg.com/ext_tw_video/1527322141724532740/pu/vid/320x568/lnBaR2hCqE-R_90a.mp4?tag=12"}] |
attachment.media_keys 扩展。请务必将 $BEARER_TOKEN 替换为你自己生成的 Bearer Token。
投票
?expansions=attachments.poll_ids 进行展开，以获取仅包含默认字段的精简对象。在请求附加字段以完善该对象时，请将该 expansion 与字段参数 poll.fields 一起使用。
| 字段值 | 类型 | 说明 |
|---|---|---|
| id（默认） | string | 已展开投票的唯一标识符。 |
{"id": "1199786642791452673"} | ||
| options（默认） | array | 包含描述所引用投票中每个选项的对象。 |
{"options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ]} | ||
| duration_minutes | integer | 指定此投票的总持续时长。 |
{"duration_minutes": 1440} | ||
| end_datetime | date (ISO 8601) | 指定此投票的结束日期和时间。 |
{"end_datetime": "2019-11-28T20:26:41.000Z"} | ||
| voting_status | string | 指示此投票是否仍处于活动状态且可继续投票，或投票是否已关闭。 |
{"voting_status": "closed"} |
attachments.poll_id expansion。请务必将 $BEARER_TOKEN 替换为你自行生成的 Bearer Token。
地点
?expansions=geo.place_id 获取仅包含默认字段的精简对象。若需请求更多字段以完善该对象，请将该扩展与字段参数 place.fields 一起使用。
| 字段值 | 类型 | 说明 | 用途 |
|---|---|---|---|
| full_name（默认） | string | 更长、更详细的地点名称。 | 按特定地点名称对 Tweet 进行分类 |
"full_name": "Manhattan, NY" | |||
| id（默认） | string | 若 Tweet 中标记的是兴趣点，则为所扩展地点的唯一标识符。 | 使用此值以编程方式检索地点 |
"id": "01a9a39529b27f36" | |||
| contained_within | array | 返回包含所引用地点的已知地点的标识符。 | |
| country | string | 此地点所属国家的全称。 | 按国家名称对 Tweet 进行分类 |
"country": "United States" | |||
| country_code | string | 此地点所属国家的 ISO Alpha-2 国家/地区代码。 | 按国家/地区代码对 Tweet 进行分类 |
"country_code": "US" | |||
| geo | object | 以 GeoJSON 格式包含地点详情。 | |
| `json | |||
| ”geo”: | |||
| “type”: “Feature”, | |||
| “bbox”: [ | |||
| -74.026675, | |||
| 40.683935, | |||
| -73.910408, | |||
| 40.877483 | |||
| ], | |||
| “properties”: | |||
| } | |||
| ` | |||
| name | string | 此地点的简称。 | 按特定地点名称对 Tweet 进行分类 |
"name": "Manhattan" | |||
| place_type | string | 指明该地点信息所表示的具体类型，例如城市名称或兴趣点。 | 按特定地点类型对 Tweet 进行分类 |
"place_type": "city" |
geo.place_id 扩展。请务必将 $BEARER_TOKEN 替换为你自己生成的 Bearer Token。
私信事件
- sender_id - 发送消息的账号 ID，或将参与者邀请至群组会话的账号 ID
- partricipants_ids - 账号 ID 的数组。对于 ParticipantsJoin 和 ParticipantsLeave 事件，此数组将包含创建该事件的账号的单个 ID
- attachments - 提供发送者在 Twitter 上传内容的媒体 ID
- referenced_tweets - 如果在 text 字段中检测到 Tweet URL，响应中会包含该 Tweet 的 ID
| 字段值 | 类型 | 说明 | 使用方式 |
| id (默认) | string | 事件的唯一标识符。 “id”: “1050118621198921728” | 用于以编程方式检索特定会话事件（适用于 v1.1 端点）。 |
| event_type (默认) | string | 描述事件类型。目前支持三种类型： * MessageCreate * ParticipantsJoin * ParticipantsLeave “event_type”: “MessageCreate” | 在检索会话历史时，用于了解消息的创建时间；对于群组会话，用于了解参与者加入和离开的时间。所有 GET 方法都支持使用 event_type= 查询参数过滤特定事件类型。 |
| text (默认) | string | 私信的实际 UTF-8 文本。 “text”: “Hello, just you!” | 搭配聊天机器人，可用于分析消息内容并确定自动回复；也可用于构建会话搜索功能。 |
| entities | object | 从私信文本中解析出的实体。 | 提供关于话题标签、URL、提及等的更多信息。 |
| sender_id | string | 创建该事件的用户 ID。要在响应中展开此对象，请将 sender_id 作为 expansion 包含，并使用 user.fields 查询参数指定所需的用户对象属性。 “sender_id”: “906948460078698496” | 检索创建 MessageCreate 或 ParticipantsJoin 事件的用户对象。 |
| participant_ids | array (of strings) | 加入和离开群组会话的参与者 ID。创建新的群组会话时也会使用。要在响应中展开此对象，请将 participant_ids 作为 expansion 包含，并使用 user.fields 查询参数指定所需的用户对象属性。 “participant_ids”: [ “906948460078698496” ] | 用于检索加入和离开群组会话的参与者的用户对象。 |
| dm_conversation_id | string | 该事件所属会话的唯一标识符。 “dm_conversation_id”: “1584988213961031680” | 用于以编程方式从某个会话中检索事件，并向该会话添加私信。 |
| created_at | date (ISO 8601) | Tweet 的创建时间（UTC）。 “created_at”: “2019-06-04T23:12:08.000Z” | 可用于了解私信的创建时间或会话参与者加入或离开的时间。 |
| referenced_tweets | array | 私信文本中提到的任何 Tweet 的 ID。要在响应中展开此对象，请将 referenced_tweets.id 作为 expansion 包含，并使用 tweet.fields 查询参数指定所需的 Tweet 对象属性。 “referenced_tweets”: [ “id”: “1578868150510456833” ] | 当私信引用了 Tweet 时，可使用这些 ID 查询该 Tweet 的详细信息。 |
| attachments | object | 对于带有媒体的私信，提供已上传内容（照片、视频或 GIF）的 media key。要在响应中展开此对象，请将 attachments.media_keys 作为 expansion 包含，并使用 media.fields 查询参数指定所需的媒体对象属性。目前支持一个附件。 “attachments”: “media_keys”: [ “3_1136048009270239232” ] | 用于了解附加在私信中的媒体对象。 |
- 基础事件属性，例如其创建时间以及所属的会话（dm_conversation）。
- 发送私信者的账户 ID 和描述。
- 任何被引用的 Tweet 的文本以及其发布时间。
- 任何被引用的 Tweet 作者的账户 ID 和描述。
?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description
社区
| 字段值 | 类型 | 描述 | |
|---|---|---|---|
| created_at | date (ISO 8601) | 社区的创建时间。 | |
| id | string | 社区的唯一标识符。 | |
| name | string | 社区名称。 | |
| description | string | 社区的描述文本（如有）。 | |
| access | string | 社区的访问级别。 可能的取值： | |
- Public | |||
- Closed | |||
| join_policy | string | 社区的加入策略。 可能的取值： | |
- Open | |||
- RestrictedJoinRequestsDisabled | |||
- RestrictedJoinRequestsRequireAdminApproval | |||
- RestrictedJoinRequestsRequireModeratorApproval | |||
- SuperFollowRequired | |||
| member_count | integer | 已加入该社区的成员数。 |
$BEARER_TOKEN 替换为你自行生成的 Bearer Token。
如何使用 fields 和 expansions
fields 和 expansions 查询参数，以便在响应中获取额外的对象和字段。
在本指南中，我们将基于下方的 Tweet 截图请求多个字段。
如截图所示，存在多项与 Tweet 相关的可见信息，包括 Tweet 作者、Tweet 指标、创建时间戳、视频以及视频观看次数。还有一些数据在截图中不可见，但仍可通过请求获取。
在向 API 发出请求时，默认响应较为精简，仅包含默认的 Tweet 字段（id 和 text）。你也只会收到所使用端点返回的主要对象，而不会包含可能与该主要对象相关的任何关联数据对象。
这种精简性，加上 fields 和 expansions 参数，使你能够根据用例仅请求所需的字段。
请求其他字段和对象。
- 通过查看我们的对象模型或各端点的 API 参考页面中的字段列表，识别你希望请求的其他字段。 在本例中，我们将请求以下附加字段： attachments、author_id、created_at、public_metrics。
-
使用逗号分隔的列表，将上述字段作为值来构建
tweet.fields查询参数：?tweet.fields=attachments,author_id,created_at,public_metrics - 将该查询参数添加到你之前发出的 GET /tweets 请求中。
curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN'
Response:
- 接下来,我们将请求 Tweet 中包含的视频相关字段。为此,我们将使用
expansions参数,将attachments.media_keys作为值,并将其添加到请求中。
- 最后,我们将请求视频的观看次数和时长。这些不是默认字段,因此需要明确指定。在请求中使用
media.fields参数,传入以逗号分隔的值:public_metrics和duration_ms。
curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'
响应中现在包含了在 Tweet 截图中可见的所有 data：
- ids=1260294888811347969
- tweet.fields=attachments,author_id,created_at,public_metrics
- expansions=attachments.media_keys
- media.fields=public_metrics,duration_ms