Esegui i report

Puoi creare un report interattivo, eseguire un report esistente e leggere i risultati del report utilizzando l'API Ad Manager.

Se non hai dimestichezza con i report interattivi in Ad Manager, consulta Creare un report interattivo per una panoramica su come utilizzare i report interattivi nell'interfaccia utente di Ad Manager.

Per i report complessi, puoi utilizzare l'interfaccia utente di Ad Manager per verificare la compatibilità delle dimensioni e delle metriche. Tutti i report dell'interfaccia utente possono essere eseguiti con l'API.

Questa guida spiega come avviare un'esecuzione asincrona di un Report, pollare lo stato Operation restituito, ottenere il Result nome della risorsa dall'Operation completato e recuperare un insieme di risultati paginato Rows.

Nota: per ulteriori informazioni su come vengono raccolti i dati dei report di Ad Manager, consulta Conteggio di impressioni e clic e Conformità a IAB.

Prerequisito

Prima di continuare, assicurati di avere accesso a una rete Google Ad Manager. Per ottenere accesso, consulta la guida introduttiva a Google Ad Manager.

Creare un report

Per eseguire un report, devi disporre dell'ID report. Puoi ottenere un ID report nell'interfaccia utente di Gestione inserzioni tramite l'URL del report. Ad esempio, nell'URL https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029 l'ID report è 4555265029.

Puoi anche leggere i report a cui l'utente ha accesso utilizzando il metodo networks.reports.list e ottenere l'ID dal nome della risorsa:

networks/234093456/reports/4555265029

Una volta ottenuto l'ID report, puoi avviare un'esecuzione asincrona del report utilizzando il metodo networks.reports.run. Questo metodo restituisce il nome della risorsa di un Operation a esecuzione prolungata. Tieni presente che nel seguente codice di esempio, [REPORT] è un segnaposto per l'ID report e [NETWORK] è un segnaposto per il codice di rete. Per trovare il codice di rete, consulta Trovare i dati dell'account 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

Richiesta

Nota: per ottenere un token di accesso, consulta la sezione Autenticazione.

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

Risposta

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

Effettuare il polling dello stato del report

Se utilizzi una libreria client, il codice di esempio della sezione precedente esegue il polling dello stato dell'esecuzione del report Operation agli intervalli consigliati e fornisce il risultato al termine. Per maggiori informazioni sugli intervalli di polling consigliati, consulta networks.reports.run.

Se vuoi un maggiore controllo sul polling, effettua una singola richiesta per recuperare lo stato corrente di un report in esecuzione utilizzando il metodo 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

Richiesta

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

Risposta

{
  "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,
}

Recupera il nome della risorsa del risultato

Al termine dell'esecuzione del report Operation contiene il nome della risorsa del 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

Richiesta

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

Risposta

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

Leggere le righe dei risultati

La risorsa Result ha un unico metodo, networks.reports.results.fetchRows, per leggere un elenco di righe paginato. Ogni riga contiene un elenco di valori delle dimensioni e un elenco di valori delle metriche raggruppate. Ogni gruppo contiene il valore della metrica e eventuali valori di confronto o indicatori. Per ulteriori informazioni sui flag, consulta Utilizzare i flag nel report interattivo.

Per i report senza confronti o suddivisioni dell'intervallo di date, è presente un singolo MetricValueGroup con i valori delle metriche (ad es. impressioni o clic) per l'intero intervallo di date del report.

L'ordine dei valori delle dimensioni e delle metriche è lo stesso dell'ReportDefinition del Report.

Di seguito è riportato un esempio JSON di ReportDefinition e una risposta corrispondente fetchRows:

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

Se utilizzi una libreria client, la risposta ha un iteratore che richiede dinamicamente altre pagine. Puoi anche utilizzare i parametri pageToken e pageSize. Per informazioni dettagliate su questi parametri, consulta Parametri di query. Se esiste un'altra pagina, la risposta contiene un nextPageToken campo con il token da utilizzare nella richiesta successiva.

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

Richiesta iniziale

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

Richiesta di pagina successiva

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

Risolvere i problemi relativi a un report

Perché il mio report non viene restituito nell'API?

Assicurati che l'utente Ad Manager con cui esegui l'autenticazione abbia accesso al report interattivo. Puoi leggere i report interattivi solo dall'API Ad Manager.

Perché i risultati dei report sulla mia rete di test sono vuoti?

Le reti di test non pubblicano annunci, pertanto i report sul recapito non contengono dati.

Perché i risultati del report sulla mia rete di produzione sono vuoti?

L'utente con cui stai effettuando l'autenticazione potrebbe non avere accesso ai dati su cui stai tentando di elaborare un report. Verifica che le autorizzazioni dei ruoli e i team siano impostati correttamente.

Perché le impressioni o i clic totali non corrispondono al mio report nell'interfaccia utente?

Le impressioni per tutta la durata si riferiscono all'intera durata dell'elemento pubblicitario, indipendentemente dall'intervallo di date del report. Se un elemento pubblicitario è ancora in pubblicazione, il valore potrebbe cambiare tra due esecuzioni dello stesso report.