คําขอแบบไม่พร้อมกัน

Search Ads 360 Reporting API เวอร์ชันใหม่พร้อมใช้งานแล้ว โดย API ใหม่จะมี ความยืดหยุ่นที่เพิ่มขึ้นในการสร้างรายงานที่กำหนดเองและผสานรวมข้อมูลไว้ในแอปพลิเคชันการรายงานของคุณ และกระบวนการต่างๆ ดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายข้อมูลไปยังและการใช้การรายงาน Search Ads 360 เวอร์ชันใหม่ API

เนื่องจากการสร้างคำขอสำหรับรายงานขนาดใหญ่อาจใช้เวลาสักพัก ระบบของ Search Ads 360 API ให้เทคนิคแบบอะซิงโครนัสสำหรับการขอและดาวน์โหลดรายงาน ด้วยสิ่งนี้ คุณจะส่งคำขอเริ่มต้นที่ระบุข้อมูลที่คุณต้องการให้แสดงในรายงาน จากนั้นส่งคำขอแบบสำรวจเพิ่มเติมจนกว่า Search Ads 360 จะสร้างรายงานเสร็จ Search Ads 360 จะแบ่งข้อมูลออกเป็นหลายๆ ไฟล์โดยขึ้นอยู่กับขนาดของรายงาน เมื่อ ได้ถูกสร้างขึ้นแล้ว คุณต้องส่งคำขอเพื่อดาวน์โหลดไฟล์รายงานแต่ละไฟล์ หากคุณ คุณสามารถขอข้อมูลจำนวนน้อยๆ คุณสามารถส่งแบบซิงโครนัสได้เพียงแท็กเดียว คำขอ

เพื่อสร้างคำขอแบบอะซิงโครนัส

  1. โทรติดต่อ Reports.request() เพื่อระบุประเภทข้อมูลที่คุณต้องการในรายงาน โปรดดูประเภทรายงานสำหรับประเภทข้อมูลที่คุณ สามารถขอได้

    Search Ads 360 จะตรวจสอบคำขอและแสดงผลรหัสรายงาน ซึ่งเป็นตัวระบุที่ไม่ซ้ำกันสำหรับข้อมูลนี้ อีกครั้ง

  2. โทรติดต่อ Reports.get() ที่มีรหัสรายงาน

    การตอบสนองจาก Search Ads 360 บ่งชี้ถึงสิ่งต่อไปนี้

    • รายงานพร้อมให้ดาวน์โหลดหรือไม่
    • หากรายงานพร้อมแล้ว ให้ระบุ URL สำหรับดาวน์โหลดรายงานอย่างน้อย 1 รายการ
  3. โทรติดต่อ Reports.getFile() ดาวน์โหลดไฟล์รายงานที่เข้ารหัส หรือดาวน์โหลดจาก URL โดยตรง

    Search Ads 360 จะแสดงรายงานในไฟล์ที่เข้ารหัส UTF-8

ฉันควรสำรวจรายงานบ่อยเพียงใดเพื่อดูว่ารายงานพร้อมหรือไม่

ระยะเวลาที่ Search Ads 360 ต้องใช้ในการสร้างรายงานจะขึ้นอยู่กับปริมาณข้อมูลใน รายงาน ลองทำแบบสำรวจสถานะรายงานเป็น 1 ครั้งต่อนาที จากนั้น ปรับความถี่หากคำขอรายงานเฉลี่ยของคุณใช้เวลามากกว่าหรือน้อยกว่า เพื่อให้เสร็จสิ้น

การแยกรายงานแบบไม่พร้อมกันออกเป็นหลายๆ ไฟล์

Search Ads 360 จะแยกรายงานขนาดใหญ่ออกเป็น หลายไฟล์ ใช้ Reports.request.maxRowsPerFile เพื่อระบุขนาดไฟล์สูงสุด ไฟล์รายงานที่เป็นผลลัพธ์แต่ละไฟล์จะต้อง ไม่เกิน maxRowsPerFile แถวของรายงาน (ไม่รวมส่วนหัว) URL อื่น สร้างสำหรับแต่ละไฟล์และแสดงผลในการตอบกลับ Reports.get() สำหรับข้อมูล เกี่ยวกับการดาวน์โหลดไฟล์รายงาน โปรดดูดาวน์โหลด รายงาน

สำหรับรายงาน CSV แต่ละไฟล์จะมีส่วนหัวซ้ำ

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

ตัวอย่างแบบอะซิงโครนัส

ด้านล่างคือตัวอย่างคำขอและการตอบกลับที่ใช้เทคนิคอะซิงโครนัส

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/reports
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json

{
  "reportScope": {
    "agencyId": "12300000000000456", // Replace with your ID
    "advertiserId": "21700000000011523", // Replace with your ID
  },
  "reportType": "keyword",              // This report covers all keywords in the
                                        // advertiser specified in reportScope.
  "columns": [
    { "columnName": "campaignId" },     // Here are some attribute columns available for keyword
    { "columnName": "keywordText" },    // reports.
    { "columnName": "keywordLandingPage" },

    { "columnName": "date" },           // The date column segments the report by individual days.

    { "columnName": "dfaRevenue" },     // Here are some metric columns available for keyword
    {                                   // reports
      "columnName": "visits",
      "startDate": "2013-01-01",        // Each metric column can optionally specify its own start
      "endDate": "2013-01-31",          // and end date; by default the report timeRange is used.
      "headerText": "visits last month" // Every column can optionally specify a headerText, which
                                        // changes the name of the column in the report.
    }
  ],
  "timeRange" : {
    "startDate" : "2012-05-01",         // Dates are inclusive and specified in YYYY-MM-DD format.
    "endDate" : "2012-05-02"

    // Alternatively, try the "changedMetricsSinceTimestamp" or "changedAttributesSinceTimestamp"
    // options. See Incremental reports.

  },
  "filters": [
    {
      "column" : { "columnName": "keywordLandingPage" },
      "operator" : "startsWith",
      "values" : [                      // With this filter, only keywords with landing pages
        "http://www.foo.com",           // rooted at www.foo.com or www.bar.com are returned.
        "http://www.bar.com"            // See Filtered reports.
      ]
    }
  ],
  "downloadFormat": "csv",
  "maxRowsPerFile": 6000000,            // Required. See Splitting reports into multiple files.
  "statisticsCurrency": "agency",       // Required. See Currency for statistics.
  "verifySingleTimeZone": false,        // Optional. Defaults to false. See Time zone.
  "includeRemovedEntities": false           // Optional. Defaults to false.
}
          

Java

/**
 * Creates a campaign report request, submits the report, and returns the report ID.
 */
private static String createReport(Doubleclicksearch service) throws IOException {
  try {
     return service.reports().request(createSampleRequest()).execute().getId();
  } catch (GoogleJsonResponseException e) {
    System.err.println("Report request was rejected.");
    for (ErrorInfo error : e.getDetails().getErrors()) {
      System.err.println(error.getMessage());
    }
    System.exit(e.getStatusCode());
    return null; // Unreachable code.
  }
}

/**
 * Creates a simple static request that lists the ID and name of all
 * campaigns under agency 12300000000000456 and advertiser 21700000000011523.
 * Substitute your own agency ID and advertiser IDs for the IDs in this sample.
 */
private static ReportRequest createSampleRequest() {
  return new ReportRequest()
      .setReportScope(new ReportScope()
          .setAgencyId(12300000000000456L) // Replace with your ID
          .setAdvertiserId(21700000000011523L)) // Replace with your ID
      .setReportType("campaign")
      .setColumns(Arrays.asList(
          new ReportApiColumnSpec[] {
            new ReportApiColumnSpec().setColumnName("campaignId"),
            new ReportApiColumnSpec().setColumnName("campaign")
          }))
      .setTimeRange(new TimeRange()
          .setStartDate("2012-05-01")
          .setEndDate("2012-05-01"))
      .setDownloadFormat("csv")
      .setStatisticsCurrency("usd")
      .setMaxRowsPerFile(5000000);
}

.NET

ฟังก์ชันนี้จะสร้างรายงานที่แสดงรายการแคมเปญภายใต้ผู้ลงโฆษณาและกำหนด โทเค็นที่ส่งกลับไปยัง reportId
using api = Google.Apis.Doubleclicksearch.v2;

/// <summary>
/// Creates a report with a sample request and returns the report ID.
/// </summary>
/// <param name="service">Search Ads 360 API service.</param>
private static string CreateReport(api.DoubleclicksearchService service)
{

    var req = service.Reports.Request(CreateSampleRequest());
    var report = req.Execute();
    Console.WriteLine("Created report: ID={0}", report.Id);
    return report.Id;
}

/// <summary>
/// Returns a simple static request that lists the ID and name of all
/// campaigns under an advertiser.
/// Substitute your own agency ID and advertiser IDs for the IDs in this sample.
/// </summary>
private static api.Data.ReportRequest CreateSampleRequest()
{
    return new api.Data.ReportRequest
    {
        ReportScope = new api.Data.ReportRequest.ReportScopeData
        {
            AgencyId = 12300000000000456, // Replace with your ID
            AdvertiserId = 21700000000011523 // Replace with your ID
        },
        ReportType = ReportType.CAMPAIGN,
        Columns = new List<api.Data.ReportApiColumnSpec>
        {
            new api.Data.ReportApiColumnSpec
            {
                ColumnName = "campaignId",
            },
            new api.Data.ReportApiColumnSpec
            {
                ColumnName = "campaign",
            },
        },
        TimeRange = new api.Data.ReportRequest.TimeRangeData
        {
            StartDate = "2015-01-01",
            EndDate = "2015-01-07",
        },
        DownloadFormat = "csv",
        StatisticsCurrency = "usd",
        MaxRowsPerFile = 5000000,
    };
}

Python

def request_report(service):
  """Request sample report and print the report ID that DS returns. See Set Up Your Application.

  Args:
    service: An authorized Doubleclicksearch service.
  Returns:
    The report id.
  """
  request = service.reports().request(
      body=
      {
        "reportScope": {
            "agencyId": "12300000000000456", // Replace with your ID
            "advertiserId": "21700000000011523", // Replace with your ID
            "engineAccountId": "700000000073991" // Replace with your ID
            },
        "reportType": "keyword",
        "columns": [
            { "columnName": "campaignId" },
            { "columnName": "keywordText" },
            { "columnName": "keywordLandingPage" },

            { "columnName": "date" },

            { "columnName": "dfaRevenue" },
            {
              "columnName": "visits",
              "startDate": "2013-01-01",
              "endDate": "2013-01-31",
              "headerText": "visits last month"
            }
          ],
          "timeRange" : {
            "startDate" : "2012-05-01",
            "endDate" : "2012-05-02"
          },
          "filters": [
            {
              "column" : { "columnName": "keywordLandingPage" },
              "operator" : "startsWith",
              "values" : [
                "http://www.foo.com",
                "http://www.bar.com"
              ]
            }
          ],
          "downloadFormat": "csv",
          "maxRowsPerFile": 6000000,
          "statisticsCurrency": "agency",
          "verifySingleTimeZone": "false",
          "includeRemovedEntities": "false"
        }
  )

  json_data = request.execute()
  return json_data['id']

หากตรวจสอบสำเร็จ

หากรายงานผ่านการตรวจสอบความถูกต้อง Search Ads 360 จะแสดงรหัสรายงาน และ Search Ads 360 ด้วย จะแสดงรหัสสกุลเงินและเขตเวลาสำหรับข้อมูลเมตา

{
  "kind": "adsdartsearch#report",
  "id": "MTMyNDM1NDYK",                      // This is the report id.
  "isReportReady": false,                    // The report is not finished generating.

  "request": {                               // The request that created this report.
    ...
  },

  "statisticsCurrencyCode": "CAD",           // The currency used for statistics. E.g., if
                                             // advertiser currency was requested, this would be
                                             // currency code of the advertiser in scope.

  "statisticsTimeZone": "America/New_York"   // If all statistics in the report were sourced from
                                             // a single time zone, this would be it. If
                                             // verifySingleTimeZone was set to true in the request,
                                             // then this field will always be populated (or the
                                             // request will fail).
}
      

หากตรวจสอบไม่สำเร็จ

หากรายงานไม่ผ่านการตรวจสอบ Search Ads 360 จะแสดงการตอบกลับ HTTP 400 ที่มีออบเจ็กต์แสดงข้อผิดพลาด ตัวอย่างเช่น ตัวอย่างคำขอข้างต้นไม่ได้ระบุ เอเจนซี:

{
 "error": {
   "code": 400,
   "message": "statisticsCurrency: the agency in scope does not have a valid currency. Please make sure the agency is properly initialized in Search Ads 360."
 }
}

แบบสำรวจเกี่ยวกับสถานะรายงาน

เรียก Report.Get() ด้วยรหัสรายงาน

JSON

GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK
          

Java

/**
 * Polls the reporting API with the reportId until the report is ready.
 * Returns the report.
 */
private static Report pollUntilReportIsFinished(Doubleclicksearch service, String reportId)
    throws IOException, InterruptedException {
  long delay = 1;
  while (true) {
    Report report = null;
    try {
      report = service.reports().get(reportId).execute();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Report generation has failed.");
      System.exit(e.getStatusCode());
    }
    if (report.getIsReportReady()) {
      return report;
    }
    System.out.format("Report %s is not ready - waiting %s seconds.%n", reportId, delay);
    Thread.sleep(TimeUnit.SECONDS.toMillis(delay));
    delay = delay + delay; // Double the delay for the next iteration.
  }
}

.NET

using api = Google.Apis.Doubleclicksearch.v2;

/// <summary>
/// Polls until the report with the given ID completes.
/// </summary>
/// <param name="service">Search Ads 360 API service.</param>
/// <param name="reportId">Report ID to poll.</param>
/// <exception cref="ApplicationException">
/// Thrown when the report completes, but has failed.
/// </exception>
private static api.Data.Report PollUntilReportIsFinished(
    api.DoubleclicksearchService service,
    string reportId)
{
    TimeSpan delay = TimeSpan.FromSeconds(1);
    while (true)
    {
        api.Data.Report report;
        try
        {
            report = service.Reports.Get(reportId).Execute();
        }
        catch (Google.GoogleApiException ex)
        {
            throw new ApplicationException("Report generation failed", ex);
        }
        if (report.IsReportReady.GetValueOrDefault(false))
        {
            return report;
        }
        Console.WriteLine("Report is not ready - waiting {0}", delay);
        Thread.Sleep(delay);
        delay = delay.Add(delay); // Double the delay for the next iteration.
    }
}

Python

import pprint
import simplejson
from googleapiclient.errors import HttpError

def poll_report(service, report_id):
  """Poll the API with the reportId until the report is ready, up to ten times.

  Args:
    service: An authorized Doubleclicksearch service.
    report_id: The ID DS has assigned to a report.
  """
  for _ in xrange(10):
    try:
      request = service.reports().get(reportId=report_id)
      json_data = request.execute()
      if json_data['isReportReady']:
        pprint.pprint('The report is ready.')

        # For large reports, DS automatically fragments the report into multiple
        # files. The 'files' property in the JSON object that DS returns contains
        # the list of URLs for file fragment. To download a report, DS needs to
        # know the report ID and the index of a file fragment.
        for i in range(len(json_data['files'])):
          pprint.pprint('Downloading fragment ' + str(i) + ' for report ' + report_id)
          download_files(service, report_id, str(i)) # See Download the report.
        return

      else:
        pprint.pprint('Report is not ready. I will try again.')
        time.sleep(10)
    except HttpError as e:
      error = simplejson.loads(e.content)['error']['errors'][0]

      # See Response Codes
      pprint.pprint('HTTP code %d, reason %s' % (e.resp.status, error['reason']))
      break

หากรายงานยังไม่พร้อม

หากรายงานยังไม่พร้อม Search Ads 360 จะตอบกลับด้วย HTTP 202 และ isReportReady เป็นเท็จ

{
  "kind": "doubleclicksearch#report",
  "id": "MTMyNDM1NDYK",
  "isReportReady": false,
  "request": {
    ...
  },
  ...
}
      

เมื่อรายงานพร้อมแล้ว

เมื่อรายงานเสร็จสมบูรณ์และพร้อมให้ดาวน์โหลดแล้ว isReportReady เป็นจริงแล้ว คำตอบยังมีช่องเพิ่มเติมคือ files ที่มี URL สำหรับดาวน์โหลดไฟล์รายงาน

{
  "kind": "doubleclicksearch#report",
  "id": "MTMyNDM1NDYK",
  "isReportReady": true,
  "request": {
    ...
  },
  ...
  "rowCount": 1329,        // Total rows in the report, not counting headers.
  "files": [
    {
      "url": "https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/0"
      "byteCount": "10242323"
    },
    {
      "url": "https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/1"
      "byteCount": "10242323"
    }
  ],
}
      

หากการสร้างรายงานล้มเหลว

หาก Search Ads 360 สร้างรายงานไม่ได้ ระบบจะแสดงรายงาน HTTP 1 รายการ รหัสข้อผิดพลาดพร้อมด้วยคำอธิบาย

{
  "error" : {
   "code" : 410,            // Or other error codes.
   "message" : "Processing was halted on the backend and will not continue."
  }
}
      

โปรดดูรายการโค้ดตอบกลับสำหรับ ที่ Search Ads 360 สามารถแสดงได้

ดาวน์โหลดรายงาน

คุณจะดาวน์โหลดรายงานด้วยการกดปุ่ม URL ของไฟล์รายงานแต่ละไฟล์โดยตรง หรือเรียกใช้ Reports.getFile() ด้วยก็ได้ รหัสรายงานและหมายเลขไฟล์ (จัดทำดัชนีแล้ว 0 รายการ) Search Ads 360 จะแสดงรายงานในไฟล์ที่เข้ารหัส UTF-8

ต่อไปนี้คือตัวอย่างของคำขอ Reports.getFile()

JSON

GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/0?alt=media
และ
GET https://www.googleapis.com/doubleclicksearch/v2/reports/MTMyNDM1NDYK/files/1?alt=media
          

Java

/**
 * Downloads the shards of a completed report to the given local directory.
 * Files are named CampaignReport0.csv, CampaignReport1.csv, and so on.
 */
private static void downloadFiles(
    Doubleclicksearch service,
    Report report,
    String localPath) throws IOException {
  for (int i = 0; i < report.getFiles().size(); i++) {
    FileOutputStream outputStream =
        new FileOutputStream(new File(localPath, "CampaignReport" + i));
    service.reports().getFile(report.getId(), i).executeAndDownloadTo(outputStream);
    outputStream.close();
  }
}

.NET

using api = Google.Apis.Doubleclicksearch.v2;

/// <summary>
/// Downloads the shards of a completed report to the given local directory.
/// Files are named CampaignReport0.csv, CampaignReport1.csv, and so on.
/// </summary>
/// <param name="service">Search Ads 360 API service.</param>
/// <param name="report">Report ID to download.</param>
/// <param name="localPath">Path of the directory to place downloaded files.</param>
private static void DownloadFiles(
    api.DoubleclicksearchService service,
    api.Data.Report report,
    string localPath)
{
    Directory.CreateDirectory(localPath);
    for (int i = 0; i < report.Files.Count; ++i)
    {
        string fileName = Path.Combine(
            localPath,
            string.Format("CampaignReport{0}.csv", i));
        Console.WriteLine("Downloading shard {0} to {1}", i, fileName);
        using (Stream dst = File.OpenWrite(fileName))
        {
            service.Reports.GetFile(report.Id, i).Download(dst);
        }
    }
}

Python

def download_files(service, report_id, report_fragment):
  """Generate and print sample report.

  Args:
    service: An authorized Doubleclicksearch service.
    report_id: The ID DS has assigned to a report.
    report_fragment: The 0-based index of the file fragment from the files array.
  """
  f = file('report-' + report_fragment + '.csv', 'w')
  request = service.reports().getFile_media(reportId=report_id, reportFragment=report_fragment)
  f.write(request.execute().decode('utf-8'))
  f.close()

รายงานตัวอย่าง

ต่อไปนี้คือตัวอย่างของรายงาน CSV ส่วนย่อยของไฟล์รายงานแต่ละรายการมีส่วนหัวของตนเอง แถว โปรดดูรายละเอียดเกี่ยวกับรูปแบบนี้ใน RFC 4180

keywordText,campaignId,landingPageUrl,day,revenue,visits last month,my revenue
google,71700000002104742,http://www.google.com,2012-05-01,10.2,5,20
google,71700000002104742,http://www.google.com,2012-05-02,11,10,60.23
      

ดาวน์โหลดไฟล์การแมปรหัส

คุณสามารถดาวน์โหลดไฟล์ที่มีการแมปรหัสระหว่าง Search Ads 360 เวอร์ชันเก่ากับ Search Ads 360 เวอร์ชันใหม่ สำหรับผู้ลงโฆษณาที่ขอ ไฟล์จะมีเอนทิตีย่อยทั้งหมด (เช่น บัญชีเครื่องมือค้นหา แคมเปญ กลุ่มโฆษณา ฯลฯ) ที่มีอยู่ใน Search Ads 360 เวอร์ชันเก่า และ Search Ads 360 เวอร์ชันใหม่

Python

def download_mapping_file(service, file_name, agency_id, advertiser_id):
    """Generate and save mapping file to a csv.

    Args:
      service: An authorized Doubleclicksearch service.
      file_name: Filename to write the ID mapping file.
      agency_id: DS ID of the agency.
      advertiser_id: DS ID of the advertiser.
    """
    request = service.reports().getIdMappingFile_media(agencyId=agency_id,
        advertiserId=advertiser_id)

    response = request.execute()
    response = response.decode('utf-8')

    f = open(file_name + '.csv', 'w')
    f.write(response)
    f.close()