活跃实体
简介
活跃实体端点专门与我们的同步和异步分析端点一起使用，因为它提供了关于针对哪些广告活动请求分析的信息。这是通过返回有关广告实体以及指标更改时间的详细信息来实现的。使用这个端点将大大简化代码和分析提取逻辑。
本指南包含有关端点及其数据源的信息和上下文。此外还提供了使用指南和一系列请求示例，用以演示如何结合使用活跃实体和我们的分析端点。摘要部分对推荐方法进行了概要说明。
数据
每当广告实体指标发生更改时，我们都会记录有关该更改的信息。这些更改事件会存储在每小时存储桶中，并包含有关实体以及更改应用时间的详细信息。后者是必要的，因为更改事件并不总是对应它们的记录时间。计费调整是一个常见的原因，但也有其他原因。
端点
请求
活跃实体请求的范围由广告账号而定，并且有三个必填的查询参数：entity、start_time 和 end_time。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z"
支持以下 entity 值：CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_ACCOUNT 和 PROMOTED_TWEET。这反映了我们的分析端点支持的实体类型。
start_time 和 end_time 值必须用 ISO 8601 表示，并指定要查询的每小时存储桶。这些值必须用整小时数来表示。
此端点还支持可用于筛选结果的三个可选参数：funding_instrument_ids、campaign_ids 和 line_item_ids。这些参数在所有广告层级上都有效，并且适用于任何指定的 entity 类型。
响应
活跃实体对上述请求的响应如下所示。
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"entity": "PROMOTED_TWEET",
"start_time": "2019-03-05T00:00:00Z",
"end_time": "2019-03-06T00:00:00Z"
}
},
"data": [
{
"entity_id": "2r0wxw",
"activity_start_time": "2019-03-04T20:55:20Z",
"activity_end_time": "2019-03-05T03:43:56Z",
"placements": [
"ALL_ON_TWITTER"
]
},
{
"entity_id": "2r30fn",
"activity_start_time": "2019-03-05T08:11:08Z",
"activity_end_time": "2019-03-05T14:40:59Z",
"placements": [
"ALL_ON_TWITTER",
"PUBLISHER_NETWORK"
]
}
]
}
data 数组为每个实体提供对象，这些实体应该包含在后续分析请求中。不应为该集合之外的 ID 请求分析。
每个对象包含四个字段：entity_id、activity_start_time、activity_end_time 和 placements。动态开始及结束时间表示关联实体的更改事件适用的时间范围，由此确定应该在后续分析请求中指定的日期。placements 数组可包含以下任何一个值或两个值：ALL_ON_TWITTER 和 PUBLISHER_NETWORK。它表示应该为给定实体 ID 请求的展示位置。
用法
活跃实体端点应规定发出分析请求的方式。编写以下使用指南是为了支持分析同步，从而使合作伙伴能够将自己的数据存储与 Twitter 同步。换言之，它描述了如何进行定期安排的后台同步。
开发者须做出两个决定。
- 请求活跃实体信息的频率，以及拉取分析的频率。
- 如何使用动态开始及结束时间来确定分析请求的
start_time和end_time值。
摘要之后，将在下面的两个小节中更详细地讨论这些内容。
摘要
按照以下方式使用活跃实体端点来规定发出分析请求的方式。决定了请求活跃实体信息的频率以及拉取分析的频率后，请遵循以下步骤。
- 发出活跃实体请求。
- 根据展示位置划分响应。一组为
ALL_ON_TWITTER，另一组为PUBLISHER_NETWORK。 - 对于各展示位置组，请执行以下操作。
- 提取实体 ID。
- 确定分析
start_time和end_time值。- 找到最小的
activity_start_time。将该值向下舍入。 - 找到最大的
activity_end_time。将该值向上舍入。
- 找到最小的
- 发出分析请求。
- 将实体 ID 分组成批次，每批次 20 个。
- 使用 #3b 批次中的
start_time和end_time值。 - 指定合适的
placement值。
- 写入你的数据存储。
请将 active_entities.py 看做是使用 Python SDK 的示例。
频率
第一个问题的答案决定了活跃实体请求中应该使用的时间范围。例如，如果每小时请求活跃实体信息，则时间范围应为一个小时。如果每天请求一次活跃实体信息，则时间范围应为一天。换言之，时间范围的选择应使得当前请求的 start_time 等于前一请求的 end_time。
注意：时间窗口应该只请求一次。多次请求时间窗口将导致不必要的分析请求。（下列情况例外。）
对于希望每小时多次请求分析当前时间的合作伙伴，运用的模式相同 — 频率决定时间范围。下方的表格显示了在这种情况下示例活跃实体开始及结束的时间戳。
| 请求时间 | start_time 时间戳 |
end_time 时间戳 |
| 00:15:00 | 00:00:00 | 00:15:00 |
| 00:30:00 | 00:15:00 | 00:30:00 |
| 00:45:00 | 00:30:00 | 00:45:00 |
| 01:00:00 | 00:45:00 | 01:00:00 |
考虑到更改事件的存储方式，上面所有四个活跃实体请求查询同一个每小时存储桶，这对于此用例是必要的。但是，当前时间过后，则不应再请求查询该每小时存储桶。
动态时间
我们建议使用以下方法来处理动态开始和结束时间。在活跃实体响应中的所有对象中，找到最小的 activity_start_time 和最大的 activity_end_time。通过向下舍入动态最小开始时间和向上舍入动态最大结束时间来修改这些值。具体来说就是将这两个时间戳都设置为零，并在结束时间的基础上加一天，如下表所示。这些是应该在后续的分析请求中指定的开始和结束时间。
| 最大和最小的动态时间 | 派生时间 |
| 2019-03-04T20:55:20Z 2019-03-05T14:40:59Z |
2019-03-04T00:00:00Z 2019-03-06T00:00:00Z |
注意：请务必包含将小时、分钟和秒均设置为零的时间戳。否则，如果仅输入日期，则我们会假设你请求在广告账号时区的午夜开始和结束的分析，这可能并不理想。例如，如果最小动态开始时间是 2019-02-28T01:30:07Z，且针对偏移量为 -08:00:00 的广告账号省略了时间戳，那么分析请求会漏掉 01:30 到 08:00 之间发生的更改。
或者，如果你更偏向于仅为返回的动态时间窗口请求分析，而不将其扩展至全天，那么你可以这么做。使用这种方法，派生的开始和结束时间将分别为 2019-03-04T20:00:00Z 和 2019-03-05T15:00:00Z。（请注意：如果在分析请求中指定 DAY 粒度，则无法接受这样的范围。）
示例
本部分演示如何结合使用活跃实体和同步分析端点。（为增强可读性，响应内容已略作修改。） 在本例中，活跃实体端点在每小时初始时被调用，每个请求都针对前一个小时。该响应决定了同步分析端点的使用方式。
首个活跃实体请求于 03:00:00 发出。响应表明行项目 dvcz7 的指标发生了更改，这些更改事件适用于 02:02:55 和 02:28:12 之间的窗口。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"
{
"request": {},
"data": [
{
"entity_id": "dvcz7",
"activity_start_time": "2019-02-11T02:02:55Z",
"activity_end_time": "2019-02-11T02:58:12Z",
"placements": [
"ALL_ON_TWITTER"
]
}
]
}
根据这些动态的开始和结束时间并使用上述方法，分析 start_time 和 end_time 值将分别设置为 2019-02-11T00:00:00Z 和 2019-02-12T00:00:00Z。我们看到下面每个指标数组中的第三个元素都是非零，正如我们根据活跃实体信息所作出的预期一样。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"
{
"data_type": "stats",
"time_series_length": 24,
"data": [
{
"id": "dvcz7",
"id_data": [
{
"segment": null,
"metrics": {
"impressions": [
0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"engagements": [
0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"video_total_views": [
0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
]
}
}
]
}
],
"request": {}
}
下一个活跃实体请求发生在 04:00:00，并且只针对前一个小时。如上所述，时间窗口只能被请求一次。根据响应，我们看到这一行项目的更改事件同时适用于 02:00:00 和 03:00:00。在后续的分析请求中，我们预期会看到这两个小时段的更改。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"
{
"request": {},
"data": [
{
"entity_id": "dvcz7",
"activity_start_time": "2019-02-11T02:07:17Z",
"activity_end_time": "2019-02-11T03:49:22Z",
"placements": [
"ALL_ON_TWITTER"
]
}
]
}
除了看到 03:00:00 的非零指标，我们还看到展示量、支出和 MRC 视频观看量的以前值已得到更新。例如，02:00:00 整点的展示量是 2,995，高于之前的 2,792。这展示了在 03:00:00 时段记录的更改事件如何应用于 02:00:00 时段。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"
{
"data_type": "stats",
"time_series_length": 24,
"data": [
{
"id": "dvcz7",
"id_data": [
{
"segment": null,
"metrics": {
"impressions": [
0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"engagements": [
0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"video_total_views": [
0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
]
}
}
]
}
],
"request": {}
}
05:00:00 时段的活跃实体请求（依然仅针对前一个小时）显示更改事件仅适用于 03:00:00 时段。后续请求中对分析指标的更改反映了这一点。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"
{
"request": {},
"data": [
{
"entity_id": "dvcz7",
"activity_start_time": "2019-02-11T03:42:39Z",
"activity_end_time": "2019-02-11T03:48:48Z",
"placements": [
"ALL_ON_TWITTER"
]
}
]
}
分析响应显示，只有 03:00:00 时段的指标发生了更改；02:00:00 时段的值与前一个分析请求期间的值相同。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"
{
"data_type": "stats",
"time_series_length": 24,
"data": [
{
"id": "dvcz7",
"id_data": [
{
"segment": null,
"metrics": {
"impressions": [
0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"engagements": [
0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
],
"video_total_views": [
0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
]
}
}
]
}
],
"request": {}
}
最后，在 06:00:00，我们看到没有其他更改事件。注意：但这并不意味着该行项目的指标将来不会发生更改。
twurl -H ads-api.twitter.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"
{
"request": {},
"data": []
}