Digital Platform API - レポート サービス

Report Service は、さまざまな種類のレポートへのアクセスを提供するために使用されます。 また、各ユーザーの種類が、その種類に適したレポートにのみアクセスできるようになります。 たとえば、ネットワーク ユーザーはすべてのレポートの種類にアクセスでき、広告主と発行元のユーザーはごく一部のユーザーにのみアクセスできます。

使用可能なメトリックはレポートの種類によって異なりますが、広告枠に費やされた金額、表示または販売されたインプレッション数、収益などが含まれます。 このドキュメントでは、レポート サービスからデータを要求およびダウンロードする方法について説明します。 また、サポートされている各レポートの種類に関する詳細情報を取得する方法と、各レポートの種類に関する詳細なドキュメントへのリンクを提供する方法についても説明します。

レポートの種類

メタデータを表示するための REST API

メタデータを表示するための JSON フィールド

メタ配列には、次のフィールドが含まれます。

メタデータ応答の例 ( network_analytics レポートを使用)

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?meta=network_analytics'

{
    "response": {
        "status": "OK",
        "meta": {
            "time_granularity": "hourly",
            "columns": [
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_name",
                    "type": "string"
                },
                {
                    "column": "seller_member",
                    "type": "string"
                },
                {
                    "column": "advertiser_id",
                    "type": "int"
                },
                ...
            ],
            "filters": [
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                ...
            ],
            "havings": [
                {
                    "column": "imps"
                },
                {
                    "column": "clicks"
                },
                {
                    "column": "cost"
                },
                {
                    "column": "revenue"
                },
                {
                    "column": "booked_revenue"
                },
                {
                    "column": "reseller_revenue"
                },
                {
                    "column": "profit"
                },
                ...
            ],
            "time_intervals": [
                "current_hour",
                "last_hour",
                "last_48_hours",
                "today",
                "yesterday",
                "last_7_days",
                "month_to_date",
                "quarter_to_date",
                "last_month",
                "lifetime",
                "mtd"
            ]
        }
    }
}

データ取得のための REST API

データ取得用の JSON フィールド

group_filters 例

{
"group_filters": [
{
"imps": {
"value": 10000,
"operator": ">="
}
}
]
}

レポートを実行する方法

• 手順 1. JSON 形式のレポート要求を作成する
• 手順 2. POST Report Service への要求
• 手順 3. GET レポート サービスからのレポートの状態
• 手順 4. GET レポート ダウンロード サービスからのレポート データ

手順 1: JSON 形式のレポート要求を作成する

JSON ファイルには、実行する特定の report_type と、取得する columns (ディメンションとメトリック) と report_interval ("today"、 "yesterday"、 "month_to_date"など) が含まれている必要があります。 ディメンションの filters を含め、粒度 (year、 month、 day) を定義し、データを返す format を指定することもできます。 formatオプションは次のとおりです。

• "csv" - コンマ区切りファイル
• "excel" - タブ区切りファイル
• "xlsx" - 最新の XML 互換 Excel 形式 (zip 形式)

要求に含めることができるフィールドの詳細については、上記の JSON フィールド を参照してください。 使用可能なディメンションとメトリックの完全な一覧については、「 メタデータを表示するための REST API」で説明されているように、実行する特定のレポートの種類に関するドキュメントを参照するか、そのレポートのメタデータをプルします。

$ cat report_request

{
    "report": {
        "report_type": "network_analytics",
        "report_interval": "last_48_hours",
        "columns": ["day","imps","clicks"],
        "filters": [{"geo_country":"US"}],
        "orders": [{"order_by":"day", "direction":"ASC"},{"order_by":"imps", "direction":"DESC"}],
        "format": "csv"
    }
}

手順 2: 要求をレポート サービスに POST する

JSON 要求を POST し、レポート ID を取得します。

$ curl -b cookies -c cookies -X POST -d @report_request 'https://api.appnexus.com/report'

{
    "response": {
        "status": "OK",
        "report_id": "ca9955709eade9a0e89f5cda5345c12r"
    }
}

または、保存したレポート ID を使用して、 POST 要求を介してレポート ID を取得することもできます。 詳細については、 保存されたレポート サービスに関するページを参照してください。

curl -c cookies -b cookies -X POST 'https://api.appnexus.com/report?saved_report_id=30'

手順 3: レポート サービスからレポートの状態を GET する

レポート ID を使用して GET 呼び出しを行って、レポートの状態を取得します。 execution_statusが"ready"されるまで、この呼び出しを続けます。 次に、 report-download サービスを使用して、レポート データをファイルに保存します。 (これについては、次の手順で説明します)。

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=ca9955709eade9a0e89f5cda5345c12r'

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2017-03-13 18:15:48",
            "cache_hit": false,
            "fact_cache_hit": false,
            "json_request": "{\"report\":{\"report_type\":\"network_analytics\",\"report_interval\":
                \"last_48_hours\",\"columns\":[\"day\",\"imps\",\"clicks\"],\"filters\":[{\"geo_country\":
                \"US\"},{\"entity_member_id\":\"514\"},{\"entity_member_id\":null}],\"orders\":
                [{\"order_by\":\"day\",\"direction\":\"ASC\"},{\"order_by\":\"imps\",\"direction\":
                \"DESC\"}]}}",
            "header_info": "Report type:,network_analytics\r\n,\r\nRun at:,2017-03-13 18:15:48\r\nStart date:,
                \r\nEnd date:,\r\nTimezone:,\r\nUser:,John Smith (9385)\r\n",
            "report_size": "10",
            "row_count": "35",
            "url": "report-download?id=ca9955709eade9a0e89f5cda5345c12r"
        },
        "execution_status": "ready"
    }
}

手順 4: レポート ダウンロード サービスからレポート データを GET する

レポート データをファイルにダウンロードするには、レポート ID を使用して別の GET 呼び出しを行いますが、今回は report-download サービスに呼び出します。 サービスとレポート ID は、前の GET 応答の url フィールドにあります。 保存するファイルを特定するときは、最初のPOSTで指定した"format"のファイル拡張子を使用してください。

curl -i -b cookies -c cookies 'https://api.appnexus.com/report-download?id=ca9955709eade9a0e89f5cda5345c12r' > /tmp/network_analytics.csv

その後、Microsoft Excel または同様のソフトウェアを使用して csv ファイルを開くことができます。

レポート データ サイズの制限事項

15 MB を超えるレポート結果は、JSON 要求で指定された受信者に電子メールで送信されません。

処理に 15 分を超える時間がかかるレポートはタイムアウトになり、エラー状態で返されます。 この処理時間は、約 1MM 行のデータに相当します。 レポートが定期的にタイムアウトする場合は、次のいずれかのオプションを検討してください。

• すべてのデータが本当に必要であることを確認します。 そうでない場合は、短い時間間隔または少ないディメンションでレポート要求を更新します。 レポートが不必要に大きすぎたり、処理に時間がかかるのを防ぐヒントについては、以下 の「レポートのベスト プラクティス 」を参照してください。
• すべてのデータが本当に必要な場合は、「 Report Pagination」の指示に従ってください。

レポートの調整

すべてのユーザーに対してシステムが可能な限りスムーズに動作するように、 Report Service はメンバー レベルとユーザー レベルの両方でレポート要求を調整します。 このページでは、制限の決定方法と、各メンバーと各ユーザーに対して定義されている制限を超える要求を処理する方法について説明します。

ユーザー制限

ユーザー A によってレポートが送信されると、ユーザー A が過去 15 分間に保留中の状態または現在処理中の 5 つのレポート要求を送信したかどうかを確認するチェックが実行されます。 その場合は、エラーが通知されます。

メンバーの制限

特定のメンバーは、同時に処理される n 個のレポート要求に制限されます。 ここで、n はメンバーのコントラクトによって決定されます (これは、api.member テーブルの max_concurrent_reports_processing フィールドによって内部的に指定されます)。制限に達した後に送信されたすべてのレポート要求は、キューに配置されます。 警告やアラートは表示されません。

例

ユーザーレベルとメンバーレベルの調整は、次の例に示すように相互に対話します。 ユーザー A とユーザー B が同じメンバーに関連付けられているとします。このメンバーには、5 つの同時レポート要求の制限があります。 この例では、次のレポート要求がすべて 15 分以内に送信されることを前提としています。

このメンバーに対して既に 5 つのレポート要求が処理されているため、レポート要求 # 6 がキューに配置されます。 同じ理由で、要求 # 6 から 8 もキューに配置されます。 最後に、ユーザー A が 15 分以内に 6 番目のレポート要求を送信したので、要求 # 9 によってエラーが通知されることがわかります。

変換データ

レポート内の変換 (および関連データ) は非同期的に処理されます。 その結果、レポートをより迅速に利用できるようになりますが、一部の変換関連データはバックグラウンドでまだ処理されています。 詳細については、「 レポート データの可用性 」ページの「非同期変換属性」を参照してください。

レポートのベスト プラクティス

レポートが不必要に大きくなるのを防いだり、処理に時間がかかるのを防ぐためのヒントを次に示します。

• report_intervalを短くします (たとえば、"lifetime"から"last_48_hours")。
• より高いレベルのフィルターを追加します (たとえば、特定のパブリッシャー、広告主、キャンペーンなど)。
• これにより行数が指数関数的に増加するため、詳細な買い側ディメンションと販売側ディメンション (クリエイティブや配置など) を組み合わせることは避けてください。 このような組み合わせについて報告する必要がある場合は、 一括レポート フィード または ログ レベル データ (LLD) フィードの使用を検討してください。

処理に時間がかかる大きなレポートをプルする必要がある場合は、「 レポートの改ページ」の手順に従ってください。

レポートが最後に更新されたタイミングを確認するには、 レポートの状態サービスを使用します。