ה-API הזה נמצא בגרסת בטא. כאן אפשר למצוא את המסמכים של Ad Manager SOAP API.

דף זה תורגם על ידי Cloud Translation API.

הפקת דוחות

אפשר ליצור דוח אינטראקטיבי, להריץ דוח קיים ולקרוא את תוצאות הדוח באמצעות Ad Manager API.

אם אתם לא יודעים איך משתמשים בדוחות האינטראקטיביים ב-Ad Manager, תוכלו לקרוא את המאמר יצירת דוח אינטראקטיבי כדי לקבל סקירה כללית על השימוש בדוחות האינטראקטיביים בממשק המשתמש של Ad Manager.

בדוחות מורכבים, אפשר להשתמש בממשק המשתמש של Ad Manager כדי לבדוק את התאימות של המאפיינים והמדדים. אפשר להריץ את כל הדוחות בממשק המשתמש באמצעות ה-API.

במדריך הזה נסביר איך מפעילים הפעלה אסינכררונית של Report, בודקים את הסטטוס Operation שמוחזר, מקבלים את שם המשאב Result מהפעולה Operation שהושלמו ומאחזרים קבוצת תוצאות עם דפים Rows.

דרישות מוקדמות

לפני שממשיכים, צריך לוודא שיש לכם גישה לרשת של Google Ad Manager. במאמר תחילת העבודה עם Google Ad Manager מוסבר איך לקבל גישה.

הרצת דוח

כדי להריץ דוח, צריך את מזהה הדוח. אפשר לקבל מזהה דוח בממשק המשתמש של Ad Manager דרך כתובת ה-URL של הדוח. לדוגמה, בכתובת ה-URL‏ https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029 מזהה הדוח הוא 4555265029.

אפשר גם לקרוא דוחות שיש למשתמש גישה אליהם באמצעות השיטה networks.reports.list ולקבל את המזהה משם המשאב:

networks/234093456/reports/4555265029

אחרי שמקבלים את מזהה הדוח, אפשר להריץ את הדוח באופן אסינכררוני באמצעות השיטה networks.reports.run. השיטה הזו מחזירה את שם המשאב של Operation ממושכת. שימו לב שבקוד לדוגמה הבא, [REPORT] הוא placeholder למזהה הדוח ו-[NETWORK] הוא placeholder לקוד הרשת. במאמר איך מוצאים את פרטי החשבון ב-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

בקשה

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

תשובה

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

סקרים לגבי סטטוס הדוח

אם אתם משתמשים בספריית לקוח, קוד הדוגמה בקטע הקודם בודק את סטטוס ההרצה של הדוח Operation במרווחי הזמן המומלצים ומספק את התוצאה בסיום. למידע נוסף על מרווחי הזמן המומלצים לבדיקות, ראו networks.reports.run.

אם רוצים לשלוט יותר בסקרים, אפשר לשלוח בקשה ספציפית לאחזור הסטטוס הנוכחי של דוח פעיל באמצעות השיטה 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

בקשה

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

תשובה

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

אחזור שם המשאב של התוצאה

בסיום ההרצה של הדוח Operation, הוא מכיל את שם המשאב של 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

בקשה

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

תשובה

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

קריאת שורות התוצאה

למשאב Result יש שיטה אחת, networks.reports.results.fetchRows, לקריאת רשימה של שורות שמחולקות לדפים. בכל שורה מופיעה רשימה של ערכי מאפיינים ורשימה של ערכי מדדים מקובצים. כל קבוצה מכילה את ערך המדד ואת ערכי ההשוואה או הדגלים. למידע נוסף על דגלים, ראו שימוש בדגלים בדוח האינטראקטיבי.

בדוחות ללא השוואות או חלוקות של טווחי תאריכים, יש רק MetricValueGroup אחד עם ערכי מדדים (לדוגמה, חשיפות או קליקים) לכל טווח התאריכים של הדוח.

הסדר של ערכי המאפיינים והמדדים זהה לסדר שמופיע ב-ReportDefinition של Report.

בהמשך מופיעה דוגמה ל-JSON של ReportDefinition ותגובה תואמת של 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
}

אם אתם משתמשים בספריית לקוח, התגובה כוללת מעבד (iterator) שמבקש דפים נוספים באופן עצלני. אפשר גם להשתמש בפרמטר pageToken ובפרמטר pageSize. פרטים על הפרמטרים האלה מופיעים בקטע פרמטרים של שאילתות. אם יש דף נוסף, התשובה תכיל את השדה nextPageToken עם האסימון שצריך להשתמש בו בבקשה הבאה.

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

הבקשה הראשונית

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

בקשה לדף הבא

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

פתרון בעיות בדוחות

למה הדוח שלי לא מוחזר ב-API?: מוודאים שלמשתמש ב-Ad Manager שאיתו מבצעים את האימות יש גישה לדוח האינטראקטיבי. אפשר לקרוא דוחות אינטראקטיביים רק מ-Ad Manager API.
למה תוצאות הדוחות ברשת הבדיקה שלי ריקות?: ברשתות הבדיקה לא מוצגות מודעות, ולכן בדוחות ההצגה לא מוצגים נתונים.
למה תוצאות הדוח ברשת הייצור שלי ריקות?: יכול להיות שלמשתמש שאתם מבצעים אימות בשם שלו אין גישה לנתונים שאתם מנסים לדווח עליהם. מוודאים שהרשאות התפקיד והצוותים מוגדרים בצורה נכונה.
למה מספר הקליקים או החשיפות במצטבר לא תואם לדוח שלי בממשק המשתמש?: החשיפות בכל משך החיים מתייחסות לכל משך החיים של הפריט, ללא קשר לטווח התאריכים של הדוח. אם פריט שורה עדיין מניב ביצועים, הערך עשוי להשתנות בין שתי הפעלות של אותו דוח.