این API در نسخه بتا است. مستندات Ad Manager SOAP API در اینجا موجود است.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

گزارش ها را اجرا کنید

می توانید با استفاده از Ad Manager API یک گزارش تعاملی ایجاد کنید، یک گزارش موجود را اجرا کنید و نتایج گزارش را بخوانید.

اگر با گزارش‌های تعاملی در Ad Manager آشنا نیستید، برای مروری بر نحوه استفاده از گزارش‌های تعاملی در رابط کاربری Ad Manager به ایجاد گزارش تعاملی مراجعه کنید.

برای گزارش‌های پیچیده، می‌توانید از رابط کاربری Ad Manager برای بررسی سازگاری ابعاد و متریک استفاده کنید. همه گزارش های UI را می توان با 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] یک مکان نگهدار برای شناسه گزارش و [NETWORK] یک مکان نگهدار برای کد شبکه شما است. برای پیدا کردن کد شبکه خود، به یافتن اطلاعات حساب مدیر آگهی مراجعه کنید.

جاوا

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

پایتون

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

دات نت

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 یک درخواست جداگانه برای بازیابی وضعیت فعلی گزارش در حال اجرا ارائه دهید:

جاوا

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

پایتون

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)

دات نت

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 را شامل می شود.

جاوا

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

پایتون

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

دات نت

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
}

اگر از کتابخانه مشتری استفاده می‌کنید، پاسخ دارای یک تکرارکننده است که با تنبلی صفحات اضافی را درخواست می‌کند. همچنین می توانید از پارامترهای pageToken و pageSize استفاده کنید. برای جزئیات بیشتر در مورد این پارامترها، به پارامترهای Query مراجعه کنید. اگر صفحه دیگری وجود داشته باشد، پاسخ حاوی یک فیلد nextPageToken با نشانه برای استفاده در درخواست بعدی است.

جاوا



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

پایتون

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

دات نت

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 بخوانید.
چرا نتایج گزارش در شبکه آزمایشی من خالی است؟: شبکه‌های آزمایشی تبلیغات ارائه نمی‌کنند، بنابراین گزارش‌های تحویل داده‌ای ندارند.
چرا نتایج گزارش در شبکه تولید من خالی است؟: کاربری که احراز هویت می‌کنید ممکن است به داده‌هایی که می‌خواهید گزارش دهید دسترسی نداشته باشد. بررسی کنید که مجوزهای نقش و تیم آنها به درستی تنظیم شده باشد.
چرا کلیک ها یا نمایش های مادام العمر با گزارش من در رابط کاربری مطابقت ندارند؟: نمایش‌های مادام‌العمر برای کل عمر مورد خط، صرف‌نظر از محدوده تاریخ گزارش، هستند. اگر یک مورد خطی همچنان در حال تحویل است، ممکن است مقدار آن بین دو اجرا از همان گزارش تغییر کند.