非同期アナリティクス
はじめに
非同期アナリティクスエンドポイントを使用すると、パートナーと広告主は、サーバーによって非同期的に処理される作成リクエストを送信することによって、メトリックをリクエストできます（これらは非同期アナリティクス「ジョブ」と呼ばれます）。この方法では、リクエストが処理されるまでクライアントの接続を開いたままにする必要はありません。
同期エンドポイントと同様に、これらのエンドポイントを使用すると、パートナーと広告主は、キャンペーンのパフォーマンスに関する詳細な統計情報をリクエストできます。アカウント、お支払い方法、キャンペーン、行項目、プロモツイート、メディアクリエイティブに関するデータのリクエストに対応しています。これらのエンドポイントと同期エンドポイントの違いは、非同期アナリティクスエンドポイントではより長い日付範囲（最大90日）とセグメント化がサポートされる点です。2つエンドポイントの違いの詳細については、「アナリティクスの概要」ページを参照してください。
同期エンドポイントとは異なり、レート制限は特定アカウントの同時ジョブの数に基づきます。言い換えれば、特定の時間に処理状態になることができるジョブの数に基づきます。この数は広告アカウントレベルでカウントされます。
使用方法
非同期アナリティクスエンドポイントを使用してキャンペーンメトリックを取得する場合は、複数の手順が必要です。ジョブを作成し、ジョブの処理が終了したかどうかを確認し、最後に、データをダウンロードします。データファイルは圧縮解除する必要があります。4つの手順の概要は次のとおりです。
- POST stats/jobs/accounts/:account_idエンドポイントを使用してジョブを作成します。
- GET stats/jobs/accounts/:account_idエンドポイントに対して通常の間隔でリクエストを行い、ジョブの処理が終わっているかどうかを確認します。
- ジョブの処理が完了後、データファイルをダウンロードします。
- データファイルを解凍します。
データファイルで返される応答オブジェクトは、同期アナリティクスエンドポイントの応答と同じJSONスキーマを持ちます。
セグメント化されたキャンペーンのメトリックは、非同期アナリティクスエンドポイントを介してのみ利用可能です。キャンペーンメトリックは、地域、性別、興味関心、キーワードなどで細分化できます。オプションの詳細な一覧については、「メトリックとセグメント化」ページを参照してください。セグメント化されたメトリックをリクエストするには、ジョブを作成するときにsegmentation_typeリクエストパラメーターを使用します。
例
このセクションでは、非同期アナリティクスエンドポイントの使用方法について説明します。
まず、POST stats/jobs/accounts/:account_idエンドポイントを使用してジョブを作成します。次の例では、特定の行項目に関する1週間のエンゲージメントメトリック（インプレッション、いいね、クリックなど）をリクエストします（リクエストされた時間範囲は3月20日までですが、タイムスタンプが午前0時に設定されているため、3月20日は含まれません）。
$ twurl -X POST -H ads-api.x.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_strを使用して作成したジョブの処理が、応答の"status": "SUCCESS"で示されるように終了しているかどうかを確認します。これは、データのダウンロード準備が整っていることを意味します。ダウンロードリンクは、urlフィールドにあります。
$ twurl -H ads-api.x.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"
]
}
]
}
上の例では1つのジョブ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"
]
}
}
}