异步指南 | Twitter Developer Platform

Guides contents

活跃实体

异步分析

简介

异步分析端点允许合作伙伴和广告商通过提交服务器异步处理的创建请求来请求指标。（我们将这些称为异步分析“作业”。）采用这种方法，客户端的连接无需在请求得到满足之前保持开放状态。

和同步端点一样，这些端点允许合作伙伴和广告商请求有关广告活动绩效的详细统计数据。它们支持请求账号数据、支付手段、广告活动、行项目、推广推文和媒体素材。异步分析端点与同步端点的不同之处在于，前者支持更大的日期范围（最多 90 天）以及细分。有关二者差异的更多详细信息，可参阅我们的分析概述页。

与同步端点不同，速率限制以给定账号的并发作业数为基准。换句话说，它是基于在给定时间内处于处理状态的作业数量。我们在广告账号级别计算此数量。

用法

使用异步分析端点检索广告活动的指标是一个多步骤的过程。它涉及创建作业、检查作业是否完成了处理，以及最后下载数据。数据文件必须解压。四个具体步骤如下。

使用 POST stats/jobs/accounts/:account_id 端点创建作业。
每隔一定时间向 GET stats/jobs/accounts/:account_id 端点发出请求，以确定作业是否完成了处理。
作业一旦完成了处理，则下载数据文件。
解压数据文件。

数据文件中返回的响应对象含有与同步分析端点响应相同的 JSON 模式。

细分广告活动指标只能通过异步分析端点获得。广告活动指标可以分解为位置、性别、兴趣、关键词等更多标签。如需完整的选项列表，请参阅指标与细分页。要请求细分指标，请在创建作业时使用 segmentation_type 请求参数。

示例

本节展示如何使用异步分析端点。

使用 POST stats/jobs/accounts/:account_id 端点开始创建作业。以下示例请求一周内某个特定行项目的互动量指标，例如展示量、喜欢数、点击量等。（注意，请求的时间范围可到 3 月 20 日，但不含该日期，原因是时间戳设置到午夜。）

$ twurl -X POST -H ads-api.twitter.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

{
  "request": {
    "params": {
      "start_time": "2019-03-12T00:00:00Z",
      "entity_ids": [
        "el32n"
      ],
      "end_time": "2019-03-20T00:00:00Z",
      "placement": "ALL_ON_TWITTER",
      "granularity": "TOTAL",
      "entity": "LINE_ITEM",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  },
  "data": {
    "start_time": "2019-03-12T00:00:00Z",
    "segmentation_type": null,
    "url": null,
    "id_str": "1120829647711653888",
    "entity_ids": [
      "el32n"
    ],
    "end_time": "2019-03-20T00:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": 1120829647711653888,
    "expires_at": null,
    "account_id": "18ce54d4x5t",
    "status": "PROCESSING",
    "granularity": "TOTAL",
    "entity": "LINE_ITEM",
    "created_at": "2019-04-23T23:19:46Z",
    "platform": null,
    "updated_at": "2019-04-23T23:19:46Z",
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}

此响应不返回行项目指标。它仅提供有关你刚创建作业的信息。查看作业状态需要作业 ID。id 和 id_str响应属性中都会显示此 ID。

然后，你需要使用来自先前响应的 id_str 检查所创建作业是否已完成了处理，如响应中的 "status": "SUCCESS" 所示。这表示数据已可以下载。url 字段包含下载链接。

$ twurl -H ads-api.twitter.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

{
  "request": {
    "params": {
      "job_ids": [
        1120829647711653888
      ]
    }
  },
  "next_cursor": "1120828505715920896",
  "data": [
    {
      "start_time": "2019-03-12T00:00:00Z",
      "segmentation_type": null,
      "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
      "id_str": "1120829647711653888",
      "entity_ids": [
        "el32n"
      ],
      "end_time": "2019-03-20T00:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "id": 1120829647711653900,
      "expires_at": "2019-04-25T23:19:48Z",
      "account_id": "18ce54d4x5t",
      "status": "SUCCESS",
      "granularity": "TOTAL",
      "entity": "LINE_ITEM",
      "created_at": "2019-04-23T23:19:46Z",
      "platform": null,
      "updated_at": "2019-04-23T23:19:48Z",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  ]
}

尽管在上述示例中我们只传递一个作业 ID，但在实践中，你可以使用 job_ids 参数同时查看多个作业的状态（最多可指定 200 个作业 ID）。

然后，使用列出的 url 值下载数据文件。

$ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
--2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
Resolving ton.twimg.com (ton.twimg.com)... 72.21.91.70
Connecting to ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 381 [application/gzip]
Saving to: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s      

2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' saved [381/381]

最后，解压文件。

$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz

文件的内容如下所示。

$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json

{
  "data_type": "stats",
  "time_series_length": 1,
  "data": [
    {
      "id": "el32n",
      "id_data": [
        {
          "segment": null,
          "metrics": {
            "impressions": [
              3482
            ],
            "tweets_send": null,
            "qualified_impressions": null,
            "follows": null,
            "app_clicks": null,
            "retweets": [
              102
            ],
            "unfollows": null,
            "likes": [
              15
            ],
            "engagements": [
              171
            ],
            "clicks": [
              30
            ],
            "card_engagements": null,
            "poll_card_vote": null,
            "replies": null,
            "carousel_swipes": null
          }
        }
      ]
    }
  ],
  "request": {
    "params": {
      "start_time": "2019-03-12T00:00:00Z",
      "segmentation_type": null,
      "entity_ids": [
        "el32n"
      ],
      "end_time": "2019-03-20T00:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "granularity": "TOTAL",
      "entity": "LINE_ITEM",
      "platform": null,
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  }
}