هذه الواجهة قيد الإصدار التجريبي. تتوفر وثائق واجهة برمجة تطبيقات SOAP في "مدير الإعلانات" هنا.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تشغيل التقارير

يمكنك إنشاء تقرير تفاعلي وتشغيل تقرير حالي وقراءة نتائج التقارير باستخدام Ad Manager API.

إذا لم تكن على دراية بالتقارير التفاعلية في "مدير إعلانات Google"، اطّلِع على مقالة إنشاء تقرير تفاعلي للحصول على overview of how to use Interactive reports in the Ad Manager UI.

بالنسبة إلى التقارير المعقّدة، يمكنك استخدام واجهة مستخدم "مدير الإعلانات" للتحقّق من توافق السمات والمقاييس. يمكن تشغيل جميع تقارير واجهة المستخدِم باستخدام واجهة برمجة التطبيقات.

يتناول هذا الدليل كيفية بدء عملية غير متزامنة لملف تعريف Report، وفحص الحالة المعروضة Operation ، والحصول على اسم Result المورد من عملية Operation завершенه ، وجلب مجموعة مفصّلة من النتائج Rows.

المتطلبات الأساسية

قبل المتابعة، تأكَّد من أنّ لديك إذن وصول إلى شبكة على "مدير إعلانات Google". للحصول على إذن الوصول، راجِع مقالة بدء استخدام "مدير إعلانات Google".

تنفيذ تقرير

لتنفيذ تقرير، تحتاج إلى معرّف التقرير. يمكنك الحصول على رقم تعريف تقرير في واجهة مستخدم 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] عنصر نائبًا لرمز الشبكة. للعثور على رمز الشبكة، اطّلِع على مقالة العثور على معلومات حساب "مدير إعلانات Google".

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
}

إذا كنت تستخدِم مكتبة عملاء، يتضمّن الردّ أداة تكرار تطلب ببطء صفحات إضافية. يمكنك أيضًا استخدام المَعلمتَين 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}"

تحديد المشاكل في أحد التقارير وحلّها

لماذا لا يتم عرض تقريري في واجهة برمجة التطبيقات؟: تأكَّد من أنّ مستخدِم "مدير إعلانات Google" الذي تتم المصادقة له لديه إذن بالوصول إلى التقرير التفاعلي. لا يمكنك قراءة التقارير التفاعلية إلا من Ad Manager API.
لماذا تكون نتائج التقارير في شبكتي الاختبارية فارغة؟: لا تعرِض الشبكات الاختبارية الإعلانات، لذا لا تحتوي تقارير التسليم على بيانات.
لماذا تكون نتائج التقارير في شبكة الإنتاج فارغة؟: قد لا يكون لدى المستخدم الذي تتم مصادقتك باسمه إذن الوصول إلى البيانات التي تحاول إعداد تقارير عنها. تأكَّد من ضبط أذونات الأدوار والفِرق بشكلٍ صحيح.
لماذا لا تتطابق النقرات أو مرّات الظهور منذ إنشاء الحساب مع تقريري في واجهة المستخدِم؟: تُستخدَم مرّات الظهور منذ إنشائها لعرض الفترة الزمنية الكاملة لتفاصيل الإعلان، بغض النظر عن النطاق الزمني للتقرير. إذا كان العنصر لا يزال يُرسِل البيانات، قد تتغيّر القيمة بين عمليتَي تشغيل للتقرير نفسه.