Generowanie raportów

Za pomocą interfejsu Ad Manager API możesz tworzyć raporty interaktywne, uruchamiać istniejące raporty oraz odczytywać ich wyniki.

Jeśli nie wiesz, jak korzystać z interaktywnych raportów w usłudze Ad Manager, zapoznaj się z artykułem Tworzenie interaktywnych raportów, aby dowiedzieć się, jak używać interaktywnych raportów w interfejsie Ad Managera.

W przypadku raportów złożonych możesz sprawdzić zgodność wymiarów i danych w interfejsie Ad Managera. Wszystkie raporty w interfejsie użytkownika można generować za pomocą interfejsu API.

W tym przewodniku dowiesz się, jak zainicjować asynchroniczne wykonanie funkcji Report, odczytywać zwracany stan Operation Result nazwa zasobu z ukończonego Operation i pobierać pogrupowane wyniki Rows.

Uwaga: więcej informacji o zbieraniu danych do raportów Ad Managera znajdziesz w artykułach Zliczanie wyświetleń i kliknięć oraz Zgodność z wytycznymi IAB.

Warunek wstępny

Zanim przejdziesz dalej, upewnij się, że masz dostęp do sieci Google Ad Manager. Aby uzyskać dostęp, zapoznaj się z artykułem Pierwsze kroki z Google Ad Managerem.

Generowanie raportu

Aby wygenerować raport, musisz podać jego identyfikator. Identyfikator raportu możesz uzyskać w interfejsie Menedżera reklam, korzystając z adresu URL raportu. Na przykład w adresie URLhttps://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029identyfikator zgłoszenia to 4555265029.

Możesz też odczytywać raporty, do których użytkownik ma dostęp, korzystając z metody networks.reports.list. Identyfikator możesz pobrać z nazwy zasobu:

networks/234093456/reports/4555265029

Po uzyskaniu identyfikatora raportu możesz zainicjować jego asynchroniczne uruchomienie za pomocą metody networks.reports.run. Ta metoda zwraca nazwę zasobu długotrwałego Operation. Pamiętaj, że w tym przykładowym kodzie [REPORT] jest to miejsce na identyfikator raportu, a [NETWORK] – na kod sieci. Aby znaleźć kod sieci, zapoznaj się z artykułem Gdzie znaleźć informacje o koncie Ad Managera.

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

Żądanie

Uwaga: aby uzyskać token dostępu, zapoznaj się z artykułem Uwierzytelnianie.

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

Odpowiedź

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

Odpytywanie stanu raportu

Jeśli używasz biblioteki klienta, kod przykładowy z poprzedniej sekcji sprawdza stan wykonywania raportu Operation w zalecanych odstępach czasu i przekazuje wynik po jego zakończeniu. Więcej informacji o zalecanych interwałach sprawdzania znajdziesz w artykule networks.reports.run.

Jeśli chcesz mieć większą kontrolę nad sondowaniem, prześlij prośbę o pozyskanie bieżącego stanu uruchomionego raportu za pomocą metody 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

Żądanie

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

Odpowiedź

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

Pobieranie nazwy zasobu z rezultatem

Po zakończeniu wykonywania raportu Operation zawiera on nazwę zasobu 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

Żądanie

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

Odpowiedź

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

Odczytywanie wierszy wyników

Zasób Result ma jedną metodę, networks.reports.results.fetchRows, do odczytu ponumerowanych stron listy wierszy. Każdy wiersz zawiera listę wartości wymiarów i listę wartości danych pogrupowanych. Każda grupa zawiera wartość danych i wartości porównawcze lub flagi. Więcej informacji o oznaczeniach znajdziesz w artykule Używanie oznaczeń w raporcie interaktywnym.

W przypadku raportów bez porównania lub podziału według zakresu dat jest widoczna tylko jedna MetricValueGroup z wartościami danych (np. wyświetleń lub kliknięć) dotyczącymi całego zakresu dat raportu.

Kolejność wartości wymiarów i danych jest taka sama jak w sekcji ReportDefinition w Report.

Poniżej znajduje się przykład danych JSON obiektu ReportDefinition i odpowiadającej mu odpowiedzi 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
}

Jeśli używasz biblioteki klienta, odpowiedź zawiera iterator, który leniwie prosi o dodatkowe strony. Możesz też użyć parametrów pageToken i pageSize. Szczegółowe informacje o tych parametrach znajdziesz w artykule Parametry zapytania. Jeśli istnieje inna strona, odpowiedź zawiera pole nextPageToken z tokenem do użycia w następnym żądaniu.

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

Wstępna prośba

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

Żądanie następnej strony

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

Rozwiązywanie problemów z raportami

Dlaczego mój raport nie jest zwracany przez interfejs API?

Upewnij się, że użytkownik Ad Managera, za którego się uwierzytelniasz, ma dostęp do raportu interaktywnego. Z interfejsu Ad Manager API możesz tylko odczytywać raporty interaktywne.

Dlaczego wyniki raportu w mojej sieci testowej są puste?

Sieć testowa nie wyświetla reklam, więc raporty dostarczenia nie zawierają danych.

Dlaczego wyniki raportu w mojej sieci produkcyjnej są puste?

Użytkownik, za którego się uwierzytelniasz, może nie mieć dostępu do danych, których dotyczy raport. Sprawdź, czy uprawnienia roli i zespoły są prawidłowo ustawione.

Dlaczego kliknięcia lub wyświetlenia w całym okresie nie zgadzają się z moimi danymi w interfejsie?

Wszystkie wyświetlenia obejmują cały okres aktywności elementu zamówienia, niezależnie od zakresu dat raportu. Jeśli element zamówienia nadal wyświetla reklamy, jego wartość może się zmieniać między dwoma uruchomieniami tego samego raportu.