Mit der Ad Manager API können Sie einen interaktiven Bericht erstellen, einen vorhandenen Bericht ausführen und Berichtsergebnisse lesen.
Wenn Sie mit interaktiven Berichten in Ad Manager nicht vertraut sind, finden Sie unter Interaktiven Bericht erstellen eine Übersicht dazu, wie Sie sie auf der Ad Manager-Benutzeroberfläche verwenden.
Bei komplexen Berichten können Sie die Kompatibilität von Dimensionen und Messwerten in der Ad Manager-Benutzeroberfläche prüfen. Alle Berichte auf der Benutzeroberfläche können mit der API ausgeführt werden.
In diesem Leitfaden wird beschrieben, wie Sie eine asynchrone Ausführung einer Report initiieren, den zurückgegebenen Status Operation abfragen, den Ressourcennamen Result aus der abgeschlossenen Operation abrufen und eine paginaierte Ergebnismenge Rows abrufen.
Vorbereitung
Bevor Sie fortfahren, prüfen Sie, ob Sie Zugriff auf ein Google Ad Manager-Netzwerk haben. Wie Sie Zugriff erhalten, erfahren Sie im Hilfeartikel Einführung in Google Ad Manager.
Bericht erstellen
Um einen Bericht auszuführen, benötigen Sie die Berichts-ID. Sie können eine Berichts-ID in der Ad Manager-Benutzeroberfläche über die Berichts-URL abrufen. In der URL https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029 lautet die Berichts-ID beispielsweise 4555265029.
Sie können auch Berichte lesen, auf die Ihr Nutzer Zugriff hat, indem Sie die networks.reports.list-Methode verwenden und die ID aus dem Ressourcennamen abrufen:
networks/234093456/reports/4555265029
Nachdem Sie die Berichts-ID haben, können Sie mit der Methode networks.reports.run eine asynchrone Ausführung des Berichts initiieren. Diese Methode gibt den Ressourcennamen eines lang laufenden Operation zurück.
Im folgenden Beispielcode ist [REPORT] ein Platzhalter für die Berichts-ID und [NETWORK] ein Platzhalter für Ihren Netzwerkcode. Wie du deinen Netzwerkcode findest, erfährst du unter Ad Manager-Kontoinformationen finden.
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();
}
}
}
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)
.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;
}
}
}
cURL
Anfrage
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \ "https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/{$REPORT_ID}:run"
Antwort
{ "name": "networks/234093456/operations/reports/runs/6485392645", "metadata": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata", "report": "networks/234093456/reports/4555265029" } }
Berichtsstatus abfragen
Wenn Sie eine Clientbibliothek verwenden, wird im Beispielcode des vorherigen Abschnitts in den empfohlenen Intervallen der Status der Berichtsausführung Operation abgefragt und das Ergebnis wird ausgegeben, sobald die Ausführung abgeschlossen ist. Weitere Informationen zu den empfohlenen Polling-Intervallen finden Sie unter networks.reports.run.
Wenn Sie die Abfrage besser steuern möchten, können Sie mit der Methode networks.operations.reports.runs.get eine einzelne Anfrage senden, um den aktuellen Status eines laufenden Berichts abzurufen:
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();
}
}
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
Anfrage
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
Antwort
{ "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, }
Ressourcennamen des Ergebnisses abrufen
Nach Abschluss der Berichtsausführung Operation enthält er den Ressourcennamen der 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
Anfrage
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
Antwort
{ "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" } }
Ergebniszeilen lesen
Die Result-Ressource hat eine einzige Methode, networks.reports.results.fetchRows, zum Lesen einer paginierten Liste von Zeilen. Jede Zeile enthält eine Liste von Dimensionswerten und eine Liste von gruppierten Messwertwerten. Jede Gruppe enthält den Messwert und alle Vergleichswerte oder Flags. Weitere Informationen zu Flags finden Sie unter Flags in interaktiven Berichten verwenden.
In Berichten ohne Vergleiche oder Aufschlüsselungen nach Zeitraum gibt es nur eine einzige MetricValueGroup mit Messwerten (z. B. Impressionen oder Klicks) für den gesamten Zeitraum des Berichts.
Die Reihenfolge der Dimensions- und Messwertwerte entspricht der Reihenfolge in der ReportDefinition der Report.
Im folgenden JSON-Beispiel wird eine ReportDefinition-Anfrage und die entsprechende fetchRows-Antwort gezeigt:
{
"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
}
Wenn Sie eine Clientbibliothek verwenden, enthält die Antwort einen Iterator, der zusätzliche Seiten nach Bedarf anfordert. Sie können auch die Parameter pageToken und pageSize verwenden. Weitere Informationen zu diesen Parametern finden Sie unter Abfrageparameter.
Wenn eine weitere Seite vorhanden ist, enthält die Antwort das Feld nextPageToken mit dem Token, das in der nächsten Anfrage verwendet werden soll.
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()) {
}
}
}
}
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)
.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;
}
}
cURL
Erste Anfrage
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows"
Anfrage für die nächste Seite
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows?pageToken=${PAGE_TOKEN}"
Probleme mit einem Bericht beheben
- Warum wird mein Bericht nicht in der API zurückgegeben?
- Achten Sie darauf, dass der Ad Manager-Nutzer, als der Sie sich authentifizieren, Zugriff auf den interaktiven Bericht hat. Interaktive Berichte können nur über die Ad Manager API gelesen werden.
- Warum sind die Berichtsergebnisse in meinem Testnetzwerk leer?
- In Testnetzwerken werden keine Anzeigen ausgeliefert. Daher enthalten Übermittlungsberichte keine Daten.
- Warum sind die Berichtsergebnisse in meinem Produktionsnetzwerk leer?
- Der Nutzer, als der Sie sich authentifizieren, hat möglicherweise keinen Zugriff auf die Daten, zu denen Sie Berichte erstellen möchten. Prüfen Sie, ob die Rollenberechtigungen und Teams richtig festgelegt sind.
- Warum stimmen die Klicks oder Impressionen seit Beginn der Kampagne nicht mit den Werten in meinem Bericht auf der Benutzeroberfläche überein?
- Lifetime-Impressionen beziehen sich auf die gesamte Lebensdauer der Werbebuchung, unabhängig vom Zeitraum des Berichts. Wenn für eine Werbebuchung weiterhin Anzeigen ausgeliefert werden, kann sich der Wert zwischen zwei Ausführungen desselben Berichts ändern.