إذا كنت تطلب تقارير صغيرة إلى الإشراف على حساب المعلِن أو حساب محرك البحث، يمكنك إرسال طلب تقرير متزامن واحد فقط. استجابةً للطلب، ستعرض Search Ads 360 API التقرير الكامل في صورة كائن JSON. الطلبات المتزامنة:
- يمكن عرض المعلن فقط وتقارير حسابات محرك البحث
- حظر عميلك إلى أن يتم إنشاء التقرير من خلال "إعلانات شبكة البحث 360"
إذا كنت تطلب تقارير كبيرة من المعلنين أو حسابات محركات البحث، ننصحك باستخدام التقارير غير المتزامنة نهجنا.
لتقديم طلب متزامن
الاتصال بـ "Reports.generate()
"
لتحديد نوع البيانات التي تريد استخدامها في تقرير المعلِن أو حساب محرك البحث.
تتحقّق "إعلانات شبكة البحث 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 }, ... ] }
في حال تعذُّر عملية التحقّق من الصحة
إذا لم يجتَز التقرير عملية التحقّق، تعرض "إعلانات شبكة البحث 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." } }
تقسيم التقارير المتزامنة إلى ردود متعددة
بشكل افتراضي، يعرض الطلب المتزامن أول 10000 صف. لتغيير هذا السلوك،
استخدام Reports.request.startRow
وReports.request.rowCount
لاسترداد أجزاء محددة من التقرير مع كل طلب.
مثال على تقسيم تقرير متزامن
على سبيل المثال، سيعرض هذا الطلب أول مائة صف (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 }