API de plateforme numérique - Service de rapports

Le service de rapports est utilisé pour fournir l’accès à de nombreux types de rapports différents. Il garantit également que chaque type d’utilisateur peut uniquement accéder aux rapports appropriés pour ce type. Par exemple, les utilisateurs réseau ont accès à tous les types de rapports, tandis que les utilisateurs annonceurs et éditeurs n’ont accès qu’à quelques-uns.

Les métriques disponibles varient en fonction du type de rapport, mais peuvent inclure le montant dépensé pour l’inventaire, le nombre d’impressions vues et/ou vendues, les revenus gagnés, etc. Ce document explique comment demander et télécharger des données à partir du service de rapports. Il explique également comment obtenir plus d’informations sur chacun des types de rapports pris en charge, ainsi que des liens vers une documentation supplémentaire sur chaque type de rapport.

Types de rapports

API REST pour l’affichage des métadonnées

Champs JSON pour l’affichage des métadonnées

Le meta array comprend les champs suivants :

Exemple de réponse aux métadonnées (à l’aide du network_analytics rapport)

$ 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"
            ]
        }
    }
}

API REST pour la récupération de données

Champs JSON pour la récupération des données

group_filters Exemple

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

Comment exécuter un rapport ?

• Étape 1. Create une demande de rapport au format JSON
• Étape 2. POST la demande adressée au service de rapports
• Étape 3. GETle rapport status à partir du service de rapports
• Étape 4. GET les données de rapport du service de téléchargement de rapports

Étape 1 : Create une demande de rapport au format JSON

Le fichier JSON doit inclure le spécifique report_type que vous souhaitez exécuter, ainsi que les columns (dimensions et métriques) et report_interval ("today", , "yesterday""month_to_date", etc.) que vous souhaitez récupérer. Vous pouvez également inclure pour les filters dimensions, définir la granularité (year, month, day) et spécifier le format dans lequel les données doivent être retournées. Les format options sont les suivantes :

• "csv" - Fichier séparé par des virgules
• "excel" - Fichier séparé par des tabulations
• "xlsx" - Format Excel compatible XML moderne (compressé)

Pour plus d’informations sur les champs qui peuvent être inclus dans la demande, consultez champs JSON ci-dessus. Pour obtenir la liste complète des dimensions et métriques disponibles, consultez la documentation relative au type de rapport spécifique que vous souhaitez exécuter, ou extrayez les métadonnées de ce rapport, comme décrit dans API REST pour l’affichage des métadonnées.

$ 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"
    }
}

Étape 2 : POST la demande au service de rapports

Vous POST la demande JSON et récupérez un ID de rapport.

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

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

Vous pouvez également obtenir un ID de rapport via une POST requête à l’aide d’un ID de rapport enregistré. Pour plus d’informations, consultez Le service de rapports enregistrés :

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

Étape 3 : GET le rapport status à partir du service De rapport

Effectuez un GET appel avec l’ID de rapport pour récupérer les status du rapport. Continuez à effectuer cet appel jusqu’à ce que soit execution_status"ready". Utilisez ensuite le report-download service pour enregistrer les données de création de rapports dans un fichier. (Ceci est décrit à l’étape suivante.)

$ 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"
    }
}

Étape 4 : GET les données de rapport du service de téléchargement de rapports

Pour télécharger les données du rapport dans un fichier, effectuez un autre GET appel avec l’ID de rapport, mais cette fois au report-download service. Vous trouverez le service et l’ID de rapport dans le champ URL de la réponse précédente GET . Lorsque vous identifiez le fichier dans lequel vous souhaitez enregistrer, veillez à utiliser l’extension de fichier du "format" que vous avez spécifié dans votre initial POST.

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

Vous pouvez ensuite ouvrir le fichier csv à l’aide de Microsoft Excel ou d’un logiciel similaire.

Limitations de la taille des données de rapport

Les résultats de rapport supérieurs à 15 Mo ne seront pas envoyé par e-mail aux destinataires spécifiés dans la requête JSON.

Les rapports dont le traitement prend plus de 15 minutes expirent et retournent une erreur status. Cette durée de traitement correspond approximativement à 1MM lignes de données. Si vos rapports expirent régulièrement, envisagez l’une des options suivantes :

• Vérifiez que vous avez vraiment besoin de toutes ces données. Si ce n’est pas le cas, mettez à jour vos demandes de rapport avec un intervalle de temps plus court ou moins de dimensions. Pour obtenir des conseils sur la façon d’empêcher les rapports d’être inutilement volumineux ou trop longs à traiter, consultez Meilleures pratiques de création de rapports ci-dessous.
• Si vous avez vraiment besoin de toutes ces données, suivez les instructions fournies dans Pagination de rapports.

Limitation des rapports

Afin de garantir que nos systèmes fonctionnent aussi bien que possible pour tous les utilisateurs, le service de rapports limite les demandes de rapport au niveau des membres et des utilisateurs. Cette page décrit comment les limites sont déterminées et comment nous gérons les demandes qui dépassent les limites définies pour chaque membre et chaque utilisateur.

Limites de l’utilisateur

Lorsqu’un rapport est soumis par l’utilisateur A, une case activée est effectuée pour voir si l’utilisateur A a envoyé 5 demandes de rapport au cours des 15 dernières minutes qui sont en attente de status ou en cours de traitement. Si c’est le cas, une erreur est signalée.

Limites des membres

Un membre donné est limité à n demandes de rapport en cours de traitement en même temps, où n est déterminé par le contrat du membre (il est spécifié en interne par le max_concurrent_reports_processing champ de la table api.member.) Toutes les demandes de rapport envoyées une fois la limite atteinte sont placées dans une file d’attente. Aucun avertissement ou alerte n’est fourni.

Exemple

Les limitations au niveau de l’utilisateur et des membres interagissent entre elles, comme illustré dans l’exemple suivant. Supposons que l’utilisateur A et l’utilisateur B sont associés au même membre ; ce membre a une limite de 5 demandes de rapport simultanées. Pour cet exemple, nous supposons que les demandes de rapport suivantes sont toutes envoyées dans un intervalle de temps de 15 minutes :

La demande de rapport n° 6 est placée dans la file d’attente, car 5 demandes de rapport sont déjà traitées pour ce membre. Pour la même raison, les demandes 6 à 8 sont également placées dans la file d’attente. Enfin, nous pouvons voir que la requête n° 9 provoque un signal d’erreur, car l’utilisateur A a envoyé sa 6e demande de rapport dans un délai de 15 minutes.

Données de conversion

Les conversions (et les données associées) dans les rapports sont traitées de manière asynchrone. Par conséquent, les rapports sont disponibles plus rapidement, tandis que certaines données liées à la conversion sont toujours traitées en arrière-plan. Pour plus d’informations, consultez « Attribution de conversion asynchrone » dans la page Disponibilité des données de création de rapports .

Meilleures pratiques en matière de création de rapports

Voici quelques conseils pour éviter que vos rapports soient inutilement volumineux ou qu’ils prennent beaucoup de temps à traiter :

• Raccourcissez le report_interval (par exemple, de "lifetime" à "last_48_hours").
• Ajoutez d’autres filtres de niveau supérieur (par exemple, pour un éditeur, un annonceur, une campagne, etc.).
• Évitez de combiner des dimensions granulaires côté achat et côté vente (par exemple, créatif et placement), car cela augmente le nombre de lignes de façon exponentielle. Si vous avez besoin de créer des rapports sur ces combinaisons, envisagez d’utiliser des flux de création de rapports en bloc ou desflux de données au niveau du journal (LLD).

Si vous devez extraire des rapports volumineux dont le traitement prend beaucoup de temps, suivez les instructions fournies dans Pagination de rapports.

Pour déterminer quand un rapport a été mis à jour pour la dernière fois, utilisez le service d’état du rapport.