เรียกใช้รายงาน

คุณสามารถสร้างรายงานแบบอินเทอร์แอกทีฟ เรียกใช้รายงานที่มีอยู่ และอ่านผลลัพธ์ของรายงานได้โดยใช้ Ad Manager API

หากไม่คุ้นเคยกับการรายงานแบบอินเทอร์แอกทีฟใน Ad Manager โปรดดูสร้างรายงานแบบอินเทอร์แอกทีฟเพื่อดูภาพรวมของวิธีใช้รายงานแบบอินเทอร์แอกทีฟใน UI ของ Ad Manager

สําหรับรายงานที่ซับซ้อน คุณสามารถใช้ UI ของ Ad Manager เพื่อตรวจสอบความเข้ากันได้ของมิติข้อมูลและเมตริก รายงาน UI ทั้งหมดจะทํางานได้โดยใช้ API

คู่มือนี้จะอธิบายวิธีเริ่มการเรียกใช้แบบไม่พร้อมกันของ Report, ตรวจสอบสถานะที่แสดงผล Operation, รับชื่อแหล่งข้อมูลจาก Operation ที่เสร็จสมบูรณ์ และดึงชุดผลลัพธ์แบบแบ่งหน้า RowsResult

หมายเหตุ: ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีรวบรวมข้อมูลการรายงานของ Ad Manager ได้ที่การนับการแสดงผลและการคลิกและการปฏิบัติตามข้อกําหนดของ IAB

วิชาบังคับก่อน

โปรดตรวจสอบว่าคุณมีสิทธิ์เข้าถึงเครือข่าย Google Ad Manager ก่อนดำเนินการต่อ หากต้องการรับสิทธิ์เข้าถึง โปรดดูเริ่มต้นใช้งาน Google Ad Manager

เรียกใช้รายงาน

คุณต้องมีรหัสรายงานจึงจะเรียกใช้รายงานได้ คุณดูรหัสรายงานได้ใน UI ของตัวจัดการโฆษณาผ่าน 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] เป็นตัวยึดตําแหน่งสําหรับรหัสเครือข่าย หากต้องการดูรหัสเครือข่าย โปรดดูค้นหาข้อมูลบัญชี 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 เพื่ออ่านรายการแถวแบบแบ่งหน้า แต่ละแถวจะมีรายการค่าของมิติข้อมูลและรายการค่าเมตริกที่จัดกลุ่ม โดยแต่ละกลุ่มจะมีค่าเมตริกและค่าการเปรียบเทียบหรือ Flag ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าแฟล็กได้ที่หัวข้อใช้การตั้งค่าแฟล็กในรายงานแบบอินเทอร์แอกทีฟ

สําหรับรายงานที่ไม่มีการเปรียบเทียบหรือแยกช่วงวันที่ จะมี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}"

แก้ปัญหาเกี่ยวกับรายงาน

เหตุใดรายงานของฉันจึงไม่แสดงใน API

ตรวจสอบว่าผู้ใช้ Ad Manager ที่คุณตรวจสอบสิทธิ์เป็นผู้ใช้ที่มีสิทธิ์เข้าถึงรายงานแบบอินเทอร์แอกทีฟ คุณอ่านได้เฉพาะรายงานแบบอินเทอร์แอกทีฟจาก Ad Manager API

เหตุใดผลลัพธ์รายงานในเครือข่ายทดสอบจึงว่างเปล่า

เครือข่ายทดสอบจะไม่แสดงโฆษณา ดังนั้นรายงานการแสดงโฆษณาจึงไม่มีข้อมูล

เหตุใดผลลัพธ์ของรายงานในเครือข่ายที่ใช้งานจริงจึงว่างเปล่า

ผู้ใช้ที่คุณกำลังตรวจสอบสิทธิ์ให้อาจไม่มีสิทธิ์เข้าถึงข้อมูลที่คุณพยายามจะรายงาน ตรวจสอบว่าบทบาท สิทธิ์ และทีมของผู้ใช้ได้รับการตั้งค่าอย่างถูกต้อง

เหตุใดจำนวนคลิกหรือการแสดงผลตลอดอายุจึงไม่ตรงกับรายงานใน UI

การแสดงผลตลอดอายุคือการแสดงผลตลอดอายุของรายการโฆษณา โดยไม่คำนึงถึงช่วงวันที่ของรายงาน หากรายการโฆษณายังแสดงอยู่ ค่าอาจเปลี่ยนแปลงระหว่างการเรียกใช้รายงานเดียวกัน 2 ครั้ง