בקשות סינכרוניות

Search Ads 360 Reporting API החדש זמין עכשיו. ה-API החדש מספק גמישות משופרת ליצירה של דוחות בהתאמה אישית ולשילוב הנתונים באפליקציות הדיווח ותהליכים. מידע נוסף על המעבר לממשק החדש של Search Ads 360 ועל השימוש בו API.

אם אתם מבקשים דוחות של חשבון מפרסם או חשבון מנוע חיפוש עם כמות קטנה עד בינונית, אפשר לשלוח רק בקשת דוח סנכרונית אחת. בתגובה לבקשה, Search Ads 360 API יחזיר את הדוח כולו באובייקט JSON. בקשות סינכרוניות:

אם אתם מבקשים דוחות גדולים על מפרסמים או על חשבון מנוע חיפוש, מומלץ להשתמש בדוחות האסינכרוניים .

כדי ליצור בקשה סנכרונית

חיוג למספר Reports.generate() כדי לציין את סוג הנתונים שאתם רוצים שיופיע בדוח המפרסם או בדוח חשבון מנוע החיפוש.

מערכת Search Ads 360 מאמתת את הבקשה, יוצרת את הדוח ומחזירה את הדוח כמשאב של דוחות גוף התגובה.

דוגמה לבקשה סנכרונית

זאת דוגמה Reports.generate() בקשה.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/reports/generate
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
    "engineAccountId": "700000000073991" // Replace with your ID
  },
  "reportType": "account",              // This report covers all revenue and visits in the
                                        // engine account specified in reportScope.
  "columns": [
    { "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": "January visits"    // 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" : "2013-05-01"

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

  },
  "statisticsCurrency": "agency",       // Required. See Currency for statistics.
  "verifySingleTimeZone": false,        // Optional. Defaults to false. See Time zone.
  "includeRemovedEntities": false           // Optional. Defaults to false.
}
        

Java

  public static void main(String[] args) throws Exception {
    Doubleclicksearch service = getService(); // See Set Up Your Application.
    Report report = generateAccountReport(service);
    outputReport(report, "./");
  }

  /**
   * Creates an account report using the synchronous Report.generate method.
   *
   * @throws IOException
   */
  private static Report generateAccountReport(Doubleclicksearch service) throws IOException {
    try {
      return service.reports().generate(generateAccountRequest()).execute();
    } 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 clicks and visits for an engine account. Use
   * your own agency ID, advertiser ID, and engine account ID.
   */
  private static ReportRequest generateAccountRequest() {
    return new ReportRequest().setReportScope(
      new ReportScope()
        .setAgencyId(20700000000000451L) // Replace with your ID
        .setAdvertiserId(21700000000010391L) // Replace with your ID
        .setEngineAccountId(700000000042201L)) // Replace with your ID
        .setReportType("account")
        .setColumns(Arrays.asList(new ReportApiColumnSpec[] {
            new ReportApiColumnSpec().setColumnName("date"),
            new ReportApiColumnSpec().setColumnName("dfaRevenue"),
            new ReportApiColumnSpec()
                .setColumnName("visits")
                .setHeaderText("January visits")
                .setStartDate("2013-01-01")
                .setEndDate("2013-01-31"),}))
        .setTimeRange(new TimeRange()
          .setStartDate("2012-05-01")
          .setEndDate("2013-05-01"))
        .setStatisticsCurrency("agency");
  }

  /**
   * Outputs a synchronous report to a file.
   */
  private static void outputReport(Report report, String localPath)
      throws IOException {
    FileOutputStream outputStream = new FileOutputStream(new File(localPath, "Report"));
    final PrintStream printStream = new PrintStream(outputStream);
    printStream.print(report);
    printStream.close();
  }
        

Python

def generate_report(service):
  """Generate and print sample report.

  Args:
    service: An authorized Doubleclicksearch service.  See Set Up Your Application.
  """
  request = service.reports().generate(
      body=
      {
        "reportScope
            "agencyId": "12300000000000456", // Replace with your ID
            "advertiserId": "21700000000011523", // Replace with your ID
            "engineAccountId": "700000000073991" // Replace with your ID
            },
        "reportType": "account",
        "columns": [
            { "columnName": "date" },
            { "columnName": "dfaRevenue" },
            {
              "columnName": "visits",
              "startDate": "2013-01-01",
              "endDate": "2013-01-31",
              "headerText": "January visits"
             }
        ],
        "timeRange" : {
            "startDate" : "2012-05-01",
            "endDate" : "2013-05-01"
        },
        "statisticsCurrency": "agency",
        "verifySingleTimeZone": "false",
        "includeRemovedEntities": "false"
        }
  )

  pprint.pprint(request.execute())

דוח לדוגמה

התגובה לבקשה סנכרונית היא אובייקט report. אם הבקשה אומתה בהצלחה, המאפיינים הראשונים באובייקט יכילו מטא-נתונים מתארת את הבקשה ששלחת. הדוח עצמו נמצא ב-rows של האובייקט לנכס.

{
  "kind":"doubleclicksearch#report",
  "request":{
    "columns":[
      {"columnName":"date"},
      {"columnName":"dfaRevenue"},
      {"columnName":"visits","endDate":"2013-01-31","headerText":"visits last month","startDate":"2013-01-01"}
    ],
    "includeDeletedEntities":false,
    "reportScope":{
      "agencyId":"12300000000000456",
      "advertiserId":"21700000000011523",
      "engineAccountId":"700000000073991"
     },
    "reportType":"account",
    "rowCount":10000,
    "startRow":0,
    "statisticsCurrency":"agency",
    "timeRange":{
      "endDate":"2013-05-01",
      "startDate":"2012-05-01"
     }
  },
  "rowCount":366,
  "rows":[
    {
      "date":"2012-05-01",
      "dfaRevenue":0.0,
      "visits last month":0.0
    },
    {
      "date":"2012-05-02",
      "dfaRevenue":0.0,
      "visits last month":0.0
    },
    {
      "date":"2012-05-03",
      "dfaRevenue":0.0,
      "visits last month":0.0
    },
    {
      "date":"2012-05-04",
      "dfaRevenue":0.0,
      "visits last month":0.0
     },
     ...
  ]
}
        

אם האימות נכשל

אם הדוח לא עובר את האימות, מערכת 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."
 }
}

פיצול דוחות סינכרוניים למספר תגובות

כברירת מחדל, בקשה סנכרונית מחזירה את 10,000 השורות הראשונות. כדי לשנות את ההתנהגות הזו, להשתמש בReports.request.startRow ו-Reports.request.rowCount כדי לאחזר חלקים ספציפיים של הדוח עם כל בקשה.

דוגמה לפיצול דוח סינכרוני

לדוגמה, הבקשה הזו תחזיר את 100 השורות הראשונות (0 עד 99) של דוח סוכנות הפילוח הוא לפי יום:

{
  "reportScope": {
    "agencyId": "12300000000000456", // Replace with your ID
    "advertiserId": "21700000000011523", // Replace with your ID
    "engineAccountId": "700000000073991" // Replace with your ID
  },
  "reportType": "account",
  "columns": [
    { "columnName": "date" },
    { "columnName": "dfaRevenue" }
  ],
  "timeRange" : {
    "startDate" : "2012-05-01",
    "endDate" : "2013-05-01"
  },
  "startRow":"0",
  "rowCount":"100",
  "statisticsCurrency": "agency",
  "verifySingleTimeZone": false,
  "includeRemovedEntities": false
}
    

ניתן לעקוב אחר הבקשה הזו באמצעות בקשה נוספת בשורות 100 עד 199:

{
  "reportScope": {
    "agencyId": "12300000000000456", // Replace with your ID
    "advertiserId": "21700000000011523", // Replace with your ID
    "engineAccountId": "700000000073991" // Replace with your ID
  },
  "reportType": "account",
  "columns": [
    { "columnName": "date" },
    { "columnName": "dfaRevenue" }
  ],
  "timeRange" : {
    "startDate" : "2012-05-01",
    "endDate" : "2013-05-01"
  },
  "startRow":"100",
  "rowCount":"100",
  "statisticsCurrency": "agency",
  "verifySingleTimeZone": false,
  "includeRemovedEntities": false
}