Générer des rapports

Vous pouvez créer un rapport interactif, exécuter un rapport existant et lire les résultats du rapport à l'aide de l'API Ad Manager.

Si vous ne connaissez pas bien les rapports interactifs dans Ad Manager, consultez Créer un rapport interactif pour découvrir comment les utiliser dans l'interface utilisateur d'Ad Manager.

Pour les rapports complexes, vous pouvez utiliser l'interface utilisateur d'Ad Manager pour vérifier la compatibilité des dimensions et des métriques. Tous les rapports de l'UI peuvent être exécutés avec l'API.

Ce guide explique comment lancer une exécution asynchrone d'un Report, interroger l'état Operation renvoyé, obtenir le nom de la ressource Result à partir de l'Operation terminée et récupérer un ensemble de résultats paginé Rows.

Remarque :Pour en savoir plus sur la collecte des données de rapports Ad Manager, consultez les pages Compter les impressions et les clics et Conformité avec la IAB.

Conditions préalables

Avant de continuer, assurez-vous d'avoir accès à un réseau Google Ad Manager. Pour y accéder, consultez Premiers pas avec Google Ad Manager.

Générer un rapport

Pour générer un rapport, vous avez besoin de son ID. Vous pouvez obtenir un ID de rapport dans l'interface utilisateur d'Ad Manager via l'URL du rapport. Par exemple, dans l'URL https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029, l'ID du rapport est 4555265029.

Vous pouvez également lire les rapports auxquels votre utilisateur a accès à l'aide de la méthode networks.reports.list et obtenir l'ID à partir du nom de la ressource:

networks/234093456/reports/4555265029

Une fois que vous avez obtenu l'ID du rapport, vous pouvez lancer une exécution asynchrone du rapport à l'aide de la méthode networks.reports.run. Cette méthode renvoie le nom de ressource d'une Operation de longue durée. Notez que dans l'exemple de code suivant, [REPORT] est un espace réservé pour l'ID du rapport et [NETWORK] est un espace réservé pour votre code réseau. Pour trouver votre code de réseau, consultez Rechercher des informations de compte Ad Manager.

Java

import com.google.ads.admanager.v1.ReportName;
import com.google.ads.admanager.v1.ReportServiceClient;
import com.google.ads.admanager.v1.RunReportResponse;

public class SyncRunReportReportname {

  public static void main(String[] args) throws Exception {
    syncRunReportReportname();
  }

  public static void syncRunReportReportname() throws Exception {
    try (ReportServiceClient reportServiceClient = ReportServiceClient.create()) {
      ReportName name = ReportName.of("[NETWORK_CODE]", "[REPORT]");
      RunReportResponse response = reportServiceClient.runReportAsync(name).get();
    }
  }
}
SyncRunReportReportname.java

Python

from google.ads import admanager_v1


def sample_run_report():
    # Create a client
    client = admanager_v1.ReportServiceClient()

    # Initialize request argument(s)
    request = admanager_v1.RunReportRequest(
        name="networks/[NETWORK_CODE]/reports/[REPORT]",
    )

    # Make the request
    operation = client.run_report(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)
admanager_v1_generated_report_service_run_report_sync.py

.NET

using Google.Ads.AdManager.V1;
using Google.LongRunning;

public sealed partial class GeneratedReportServiceClientSnippets
{
    public void RunReportResourceNames()
    {
        // Create client
        ReportServiceClient reportServiceClient = ReportServiceClient.Create();
        // Initialize request argument(s)
        ReportName name = ReportName.FromNetworkCodeReport("[NETWORK_CODE]", "[REPORT]");
        // Make the request
        Operation<RunReportResponse, RunReportMetadata> response = reportServiceClient.RunReport(name);

        // Poll until the returned long-running operation is complete
        Operation<RunReportResponse, RunReportMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        RunReportResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<RunReportResponse, RunReportMetadata> retrievedResponse = reportServiceClient.PollOnceRunReport(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            RunReportResponse retrievedResult = retrievedResponse.Result;
        }
    }
}
ReportServiceClient.RunReportResourceNamesSnippet.g.cs

cURL

Requête

Remarque :Pour obtenir un jeton d'accès, consultez la section Authentification.

curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/{$REPORT_ID}:run"

Réponse

{
  "name": "networks/234093456/operations/reports/runs/6485392645",
  "metadata": {
    "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata",
    "report": "networks/234093456/reports/4555265029"
  }
}

Interroger l'état du rapport

Si vous utilisez une bibliothèque cliente, l'exemple de code de la section précédente interroge l'état de l'exécution du rapport Operation aux intervalles recommandés et fournit le résultat une fois l'exécution terminée. Pour en savoir plus sur les intervalles d'interrogation recommandés, consultez networks.reports.run.

Si vous souhaitez mieux contrôler l'interrogation, effectuez une requête individuelle pour récupérer l'état actuel d'un rapport en cours d'exécution à l'aide de la méthode networks.operations.reports.runs.get:

Java

import com.google.ads.admanager.v1.ReportServiceSettings;
import com.google.api.gax.longrunning.OperationalTimedPollAlgorithm;
import com.google.api.gax.retrying.RetrySettings;
import com.google.api.gax.retrying.TimedRetryAlgorithm;
import java.time.Duration;

public class SyncRunReport {

  public static void main(String[] args) throws Exception {
    syncRunReport();
  }

  public static void syncRunReport() throws Exception {
    ReportServiceSettings.Builder reportServiceSettingsBuilder = ReportServiceSettings.newBuilder();
    TimedRetryAlgorithm timedRetryAlgorithm =
        OperationalTimedPollAlgorithm.create(
            RetrySettings.newBuilder()
                .setInitialRetryDelayDuration(Duration.ofMillis(500))
                .setRetryDelayMultiplier(1.5)
                .setMaxRetryDelayDuration(Duration.ofMillis(5000))
                .setTotalTimeoutDuration(Duration.ofHours(24))
                .build());
    reportServiceSettingsBuilder
        .createClusterOperationSettings()
        .setPollingAlgorithm(timedRetryAlgorithm)
        .build();
  }
}
SyncRunReport.java

Python

from google.ads import admanager_v1
from google.longrunning.operations_pb2 import GetOperationRequest

def sample_poll_report():
# Run the report
client = admanager_v1.ReportServiceClient()
response = client.run_report(name="networks/[NETWORK_CODE]/reports/[REPORT_ID]")

# Check if the long-running operation has completed
operation = client.get_operation(
    GetOperationRequest(name=response.operation.name))
if(operation.done):
    # If it has completed, then access the result
    run_report_response = admanager_v1.RunReportResponse.deserialize(payload=operation.response.value)

.NET

Operation<RunReportResponse, RunReportMetadata> retrievedResponse =
  reportServiceClient.PollOnceRunReport(operationName);
// Check if the retrieved long-running operation has completed
if (retrievedResponse.IsCompleted)
{
  // If it has completed, then access the result
  RunReportResponse retrievedResult = retrievedResponse.Result;
}

cURL

Requête

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"

Réponse

{
  "name": "networks/234093456/operations/reports/runs/6485392645",
  "metadata": {
    "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata",
    "percentComplete": 50,
    "report": "networks/234093456/reports/4555265029"
  },
  "done": false,
}

Obtenir le nom de la ressource de résultat

Une fois l'exécution du rapport Operation terminée, il contient le nom de la ressource de l'Result.

Java

RunReportResponse response = reportServiceClient.runReportAsync(name).get();
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
String resultName = response.getReportResult();

Python

operation = client.run_report(request=request)
response = operation.result()
# Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
result_name = response.report_result

.NET

Operation<RunReportResponse, RunReportMetadata> response = reportServiceClient.RunReport(request);
// Poll until the returned long-running operation is complete
Operation<RunReportResponse, RunReportMetadata> completedResponse = response.PollUntilCompleted();
RunReportResponse result = completedResponse.Result;
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
string resultName = result.ReportResult;

cURL

Requête

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"

Réponse

{
  "name": "networks/234093456/operations/reports/runs/6485392645",
  "metadata": {
    "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata",
    "percentComplete": 100,
    "report": "networks/234093456/reports/4555265029"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportResponse",
    "reportResult": "networks/234093456/reports/4555265029/results/7031632628"
  }
}

Lire les lignes de résultats

La ressource Result comporte une seule méthode, networks.reports.results.fetchRows, pour lire une liste paginée de lignes. Chaque ligne contient une liste de valeurs de dimension et une liste de valeurs de métrique groupées. Chaque groupe contient la valeur de la métrique, ainsi que les valeurs ou indicateurs de comparaison. Pour en savoir plus sur les indicateurs, consultez la section Utiliser des indicateurs dans votre rapport interactif.

Pour les rapports sans comparaisons ni répartitions de la plage de dates, il n'y a qu'un seul MetricValueGroup avec des valeurs de métrique (par exemple, impressions ou clics) pour l'ensemble de la plage de dates du rapport.

L'ordre des valeurs de dimension et de métrique est le même que celui dans la ReportDefinition de Report.

Voici un exemple JSON d'une requête ReportDefinition et d'une réponse fetchRows correspondante:

{
  "name": "networks/234093456/reports/4555265029",
  "visibility": "SAVED",
  "reportId": "4555265029",
  "reportDefinition": {
     "dimensions": [
      "LINE_ITEM_NAME",
      "LINE_ITEM_ID"
    ],
    "metrics": [
      "AD_SERVER_IMPRESSIONS"
    ], 
    "currencyCode": "USD",
    "dateRange": {
      "relative": "YESTERDAY"
    },
    "reportType": "HISTORICAL"
  },
  "displayName": "Example Report",
  "updateTime": "2024-09-01T13:00:00Z",
  "createTime": "2024-08-01T02:00:00Z",
  "locale": "en-US",
  "scheduleOptions": {}
}

{
  "rows": [
    {
      "dimensionValues": [
        {
          "stringValue": "Line Item #1"
        },
        {
          "intValue": "6378470710"
        }
      ],
      "metricValueGroups": [
        {
          "primaryValues": [
            {
              "intValue": "100"
            }
          ]
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "stringValue": "Line Item #2"
        },
        {
          "intValue": "5457147368"
        }
      ],
      "metricValueGroups": [
        {
          "primaryValues": [
            {
              "intValue": "95"
            }
          ]
        }
      ]
    }
],
"runTime": "2024-10-02T10:00:00Z",
  "dateRanges": [
    {
      "startDate": {
        "year": 2024,
        "month": 10,
        "day": 1
      },
      "endDate": {
        "year": 2024,
        "month": 10,
        "day": 1
      }
    }
  ],
  "totalRowCount": 2
}

Si vous utilisez une bibliothèque cliente, la réponse contient un itérateur qui demande de manière paresseuse des pages supplémentaires. Vous pouvez également utiliser les paramètres pageToken et pageSize. Pour en savoir plus sur ces paramètres, consultez la section Paramètres de requête. Si une autre page existe, la réponse contient un champ nextPageToken avec le jeton à utiliser dans la requête suivante.

Java

import com.google.ads.admanager.v1.Report;
import com.google.ads.admanager.v1.ReportServiceClient;

public class SyncFetchReportResultRowsString {

  public static void main(String[] args) throws Exception {
    syncFetchReportResultRowsString();
  }

  public static void syncFetchReportResultRowsString() throws Exception {
    try (ReportServiceClient reportServiceClient = ReportServiceClient.create()) {
      String name = "networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]";
      for (Report.DataTable.Row element :
          reportServiceClient.fetchReportResultRows(name).iterateAll()) {
      }
    }
  }
}
SyncFetchReportResultRowsString.java

Python

from google.ads import admanager_v1


def sample_fetch_report_result_rows():
    # Create a client
    client = admanager_v1.ReportServiceClient()

    # Initialize request argument(s)
    request = admanager_v1.FetchReportResultRowsRequest(
    )

    # Make the request
    page_result = client.fetch_report_result_rows(request=request)

    # Handle the response
    for response in page_result:
        print(response)
admanager_v1_generated_report_service_fetch_report_result_rows_sync.py

.NET

using Google.Ads.AdManager.V1;
using Google.Api.Gax;
using System;

public sealed partial class GeneratedReportServiceClientSnippets
{
    public void FetchReportResultRows()
    {
        // Create client
        ReportServiceClient reportServiceClient = ReportServiceClient.Create();
        // Initialize request argument(s)
        string name = "";
        // Make the request
        PagedEnumerable<FetchReportResultRowsResponse, Report.Types.DataTable.Types.Row> response = reportServiceClient.FetchReportResultRows(name);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (Report.Types.DataTable.Types.Row item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (FetchReportResultRowsResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (Report.Types.DataTable.Types.Row item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<Report.Types.DataTable.Types.Row> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (Report.Types.DataTable.Types.Row item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}
ReportServiceClient.FetchReportResultRowsSnippet.g.cs

cURL

Demande initiale

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows"

Demande de page suivante

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows?pageToken=${PAGE_TOKEN}"

Résoudre les problèmes liés à un rapport

Pourquoi mon rapport n'est-il pas renvoyé dans l'API ?

Assurez-vous que l'utilisateur Ad Manager que vous authentifiez a accès au rapport "Interactivité". Vous ne pouvez lire les rapports interactifs que depuis l'API Ad Manager.

Pourquoi les résultats des rapports sur mon réseau de test sont-ils vides ?

Les réseaux de test ne diffusent pas d'annonces. Par conséquent, les rapports sur la diffusion ne contiennent pas de données.

Pourquoi les résultats du rapport sur mon réseau de production sont-ils vides ?

L'utilisateur que vous authentifiez n'a peut-être pas accès aux données que vous essayez de créer en rapport. Vérifiez que leurs autorisations de rôle et leurs équipes sont correctement définies.

Pourquoi les clics ou les impressions sur toute la durée ne correspondent-ils pas à mon rapport dans l'UI ?

Les impressions sur toute la durée de vie correspondent à l'ensemble de la durée de vie de l'élément de campagne, quelle que soit la période du rapport. Si un élément de campagne est toujours diffusé, la valeur peut changer entre deux exécutions du même rapport.