字段

X API v2 的各个端点都提供了一组名为「fields」的参数，可让你仅从端点响应中的各对象选择所需的 data。

默认情况下，Post 对象只返回 id 和 text 字段；对于 2022 年 9 月 29 日之后创建的 Post，还会返回 edit_history_tweet_ids 字段。若你需要 Post 的创建时间或公开指标，则需使用 tweet.fields 参数进行请求。这样可根据你的使用场景仅请求所需字段，从而实现更高的定制化。例如，你可以在请求中包含如下查询字符串：

?tweet.fields=created_at,public_metrics

每种对象都有其对应的参数，用于专门请求与该对象关联的字段。以下是当前可用的字段参数：

• Post → tweet.fields
• User → user.fields
• Media → media.fields
• Poll → poll.fields
• Place → place.fields

当使用主要返回某一特定对象的端点时，只需使用相应的字段参数，并以逗号分隔的列表形式将所需字段作为该参数的值，即可在响应中返回这些字段。

​

示例

如果你使用 GET /tweets/search/recent 端点，响应中主要会返回 Tweet 对象。如果未指定任何 fields 参数，你将只会收到默认值 id 和 text。如果希望在响应中获取返回的 Post 的公开指标，请在请求中包含 tweet.fields 参数，并将其值设为 public_metrics。

该请求如下所示。若要直接使用此请求，请确保将 $BEARER_TOKEN 替换为你的 Bearer Token，并通过命令行工具发送。

curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

如果你在终端中发送此请求，返回的每个 Post 都将包含以下 fields：

{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "你看到👀我们新的 Tweet 设置了吗?\n\n我们想了解你会如何以及为什么在 API 中使用这个功能。查看详情并告诉我们你的想法👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}

如果你希望从某个端点返回的主对象所关联的次级对象中检索一组字段，则需要额外包含一个 expansions 参数。比如，如果你继续使用前面相同的 GET search/tweets/recent 端点，并想获取作者的个人资料简介，则需要在请求中传递 expansions=author_id 和 user.fields=description。下面是一个示例。如果你想尝试此请求，请在将其粘贴到命令行工具之前，务必将 $BEARER_TOKEN 替换为你的Bearer Token。

  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

如果你在请求中进行了相应指定，则每个返回的 Post 都会包含以下字段，且相关的用户对象的默认字段和你指定的字段会在 includes 中返回。可以通过匹配 tweet.author_id 与 users.id 字段将该用户对象映射回相应的 Post。

{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "你有没有👀看过我们的全新 Tweet 设置？\n\n我们想了解你会如何、以及为何在 API 中使用此类功能。查看详情后告诉我们你的想法👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "#TwitterDev 团队的声音；与你分享 #TwitterAPI 相关更新、新闻与活动的官方渠道。",
        "name": "Twitter Dev"
      }
    ]
  }
}

请注意，您无法请求特定子字段（例如 public_metrics.retweet_count）。当指定顶级字段（public_metrics）时，将返回所有子字段。我们在各个端点的 API 参考页面的参数表中列出了可请求的所有字段。

完整的 fields 列表见对象模型。若需为非该端点主要资源的对象展开并请求其 fields，请将 expansions 参数与 fields 搭配使用。