API قبلی Search Ads 360 Reporting حذف می‌شود و در 30 ژوئن 2024 از رده خارج می‌شود. توجه داشته باشید که Search Ads 360 Conversion API تحت تأثیر قرار نگرفته و همچنان پشتیبانی می‌شود. همه توسعه گزارش‌های جدید باید از Search Ads 360 Reporting API جدید استفاده کنند.

از آوریل 2024، هنگام درخواست گزارش، یک خطای پشتیبانی‌نشده ApiVersion برگردانده می‌شود. جزئیات را اینجا ببینید.

همچنین اکیداً توصیه می‌کنیم که پیاده‌سازی‌های موجود Search Ads 360 را به API جدید منتقل کنید. برای اطلاعات بیشتر به راهنمای جدید Search Ads 360 Reporting Getting Started and Migration مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Reports: request

درخواست گزارش را در سیستم گزارش دهی درج می کند. اکنون آن را امتحان کنید .

درخواست

درخواست HTTP

POST https://www.googleapis.com/doubleclicksearch/v2/reports

مجوز

این درخواست به مجوز با محدوده زیر نیاز دارد:

محدوده
`https://www.googleapis.com/auth/doubleclicksearch`

برای اطلاعات بیشتر، به صفحه احراز هویت و مجوز مراجعه کنید.

درخواست بدن

در بدنه درخواست، داده ها را با ساختار زیر ارائه دهید:

{
  "reportScope": {
    "agencyId": long,
    "advertiserId": long,
    "engineAccountId": long,
    "campaignId": long,
    "adGroupId": long,
    "keywordId": long,
    "adId": long
  },
  "reportType": string,
  "columns": [
    {
      "columnName": string,
      "savedColumnName": string,
      "customDimensionName": string,
      "customMetricName": string,
      "headerText": string,
      "startDate": string,
      "endDate": string,
      "groupByColumn": boolean,
      "platformSource": string,
      "productReportPerspective": string
    }
  ],
  "timeRange": {
    "startDate": string,
    "endDate": string,
    "changedMetricsSinceTimestamp": datetime,
    "changedAttributesSinceTimestamp": datetime
  },
  "filters": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "operator": string,
      "values": [
        (value)
      ]
    }
  ],
  "orderBy": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "sortOrder": string
    }
  ],
  "includeDeletedEntities": boolean,
  "includeRemovedEntities": boolean,
  "verifySingleTimeZone": boolean,
  "downloadFormat": string,
  "statisticsCurrency": string,
  "startRow": integer,
  "rowCount": integer,
  "maxRowsPerFile": integer
}

نام ملک	ارزش	شرح
`reportScope`	`object`	ReportScope مجموعه ای از شناسه هایی است که برای تعیین زیرمجموعه موجودیت ها در گزارش استفاده می شود. نسب کامل شناسنامه ها از پایین ترین سطح دامنه مورد نظر از طریق آژانس مورد نیاز است.
`reportScope. agencyId`	`long`	شناسه نمایندگی DS.
`reportScope. advertiserId`	`long`	شناسه تبلیغ کننده DS.
`reportScope. engineAccountId`	`long`	شناسه حساب موتور DS.
`reportScope. campaignId`	`long`	شناسه کمپین DS.
`reportScope. adGroupId`	`long`	شناسه گروه تبلیغات DS.
`reportScope. keywordId`	`long`	شناسه کلمه کلیدی DS.
`reportScope. adId`	`long`	شناسه آگهی DS.
`reportType`	`string`	نوع ردیف هایی که در گزارش برگردانده می شوند را تعیین می کند. برای مثال، اگر `reportType: keyword` مشخص کنید، هر ردیف در گزارش حاوی داده‌هایی درباره یک کلمه کلیدی است. برای ستون هایی که برای هر نوع موجود است، به مرجع انواع گزارش ها مراجعه کنید.
`columns[]`	`list`	ستون هایی که باید در گزارش گنجانده شوند. این شامل هر دو ستون DoubleClick Search و ستون های ذخیره شده است. برای ستون‌های DoubleClick Search، فقط پارامتر `columnName` مورد نیاز است. برای ستون های ذخیره شده فقط پارامتر `savedColumnName` مورد نیاز است. `columnName` و `savedColumnName` نمی توان در یک بند تنظیم کرد. حداکثر تعداد ستون در هر درخواست 300 است.
`columns[]. columnName`	`string`	نام یک ستون DoubleClick Search برای درج در گزارش.
`columns[]. savedColumnName`	`string`	نام ستون ذخیره شده برای درج در گزارش. محدوده گزارش باید در آگهی‌دهنده یا پایین‌تر باشد، و این ستون ذخیره‌شده باید قبلاً در رابط کاربری جستجوی DoubleClick ایجاد شده باشد.
`columns[]. headerText`	`string`	متن مورد استفاده برای شناسایی این ستون در خروجی گزارش. به طور پیش فرض `columnName` یا `savedColumnName` زمانی که مشخص نشده باشد. این می تواند برای جلوگیری از برخورد بین ستون های DoubleClick Search و ستون های ذخیره شده با همان نام استفاده شود.
`columns[]. startDate`	`string`	تاریخ شامل در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `endDate` ارائه شود.
`columns[]. endDate`	`string`	روز فراگیر در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `startDate` ارائه شود.
`columns[]. groupByColumn`	`boolean`	فقط گزارش همزمان برای گروه بندی بر اساس این ستون روی `true` تنظیم کنید. پیش فرض ها به `false` .
`timeRange`	`object`	اگر معیارها در یک گزارش درخواست شوند، از این آرگومان برای محدود کردن معیارها به یک محدوده زمانی خاص استفاده می‌شود.
`timeRange. startDate`	`string`	تاریخ شامل در قالب YYYY-MM-DD.
`timeRange. endDate`	`string`	تاریخ شامل در قالب YYYY-MM-DD.
`timeRange. changedMetricsSinceTimestamp`	`datetime`	مهر زمانی UTC شامل در قالب RFC، به عنوان مثال، `2013-07-16T10:16:23.555Z` . به منابع اضافی در مورد نحوه عملکرد گزارش های معیارهای تغییر یافته مراجعه کنید.
`timeRange. changedAttributesSinceTimestamp`	`datetime`	مهر زمانی UTC شامل در قالب RFC، به عنوان مثال، `2013-07-16T10:16:23.555Z` . به منابع اضافی در مورد نحوه عملکرد گزارش های ویژگی تغییر یافته مراجعه کنید.
`filters[]`	`list`	فهرستی از فیلترهایی که باید در گزارش اعمال شوند. حداکثر تعداد فیلتر در هر درخواست 300 عدد است.
`filters[]. column`	`nested object`	ستونی برای اجرای فیلتر روی. این می تواند یک ستون DoubleClick Search یا یک ستون ذخیره شده باشد.
`filters[].column. columnName`	`string`	نام یک ستون DoubleClick Search برای درج در گزارش.
`filters[].column. savedColumnName`	`string`	نام ستون ذخیره شده برای درج در گزارش. محدوده گزارش باید در آگهی‌دهنده یا پایین‌تر باشد، و این ستون ذخیره‌شده باید قبلاً در رابط کاربری جستجوی DoubleClick ایجاد شده باشد.
`filters[]. operator`	`string`	اپراتور برای استفاده در فیلتر. برای لیستی از اپراتورهای موجود به مرجع فیلتر مراجعه کنید.
`filters[]. values[]`	`list`	فهرستی از مقادیر برای فیلتر کردن مقدار ستون. حداکثر تعداد مقادیر فیلتر در هر درخواست 300 عدد است.
`orderBy[]`	`list`	فقط گزارش همزمان فهرستی از ستون‌ها و جهت‌ها که مرتب‌سازی را برای انجام در ردیف‌های گزارش تعریف می‌کنند. حداکثر تعداد سفارش در هر درخواست 300 عدد می باشد.
`orderBy[]. column`	`nested object`	ستون برای انجام مرتب سازی بر روی. این می تواند یک ستون تعریف شده توسط DoubleClick Search یا یک ستون ذخیره شده باشد.
`orderBy[].column. columnName`	`string`	نام یک ستون DoubleClick Search برای درج در گزارش.
`orderBy[].column. savedColumnName`	`string`	نام ستون ذخیره شده برای درج در گزارش. محدوده گزارش باید در آگهی‌دهنده یا پایین‌تر باشد، و این ستون ذخیره‌شده باید قبلاً در رابط کاربری جستجوی DoubleClick ایجاد شده باشد.
`orderBy[]. sortOrder`	`string`	جهت مرتب سازی که یا `ascending` یا `descending` است.
`includeDeletedEntities`	`boolean`	تعیین می کند که آیا نهادهای حذف شده باید در گزارش گنجانده شوند یا خیر. پیش فرض ها به `false` . منسوخ شده است، لطفاً به جای آن از `includeRemovedEntities` استفاده کنید.
`verifySingleTimeZone`	`boolean`	اگر `true` ، گزارش تنها در صورتی ایجاد می‌شود که همه داده‌های آماری درخواستی از یک منطقه زمانی منفرد تهیه شده باشند. پیش فرض ها به `false` .
`downloadFormat`	`string`	قالبی که گزارش باید در آن بازگردانده شود. در حال حاضر `csv` یا `tsv` پشتیبانی می شود.
`statisticsCurrency`	`string`	ارزی را مشخص می کند که پول با آن بازگردانده می شود. مقادیر ممکن عبارتند از: `usd` ، `agency` (معتبر اگر گزارش به نمایندگی یا کمتر باشد)، `advertiser` (معتبر اگر محدوده گزارش به * تبلیغ‌کننده یا پایین‌تر باشد)، یا `account` (معتبر اگر گزارش به حساب موتور یا پایین‌تر باشد) .
`startRow`	`integer`	فقط گزارش همزمان شاخص مبتنی بر صفر از اولین سطر برای بازگشت. مقادیر قابل قبول شامل `0` تا `50000` است. پیش‌فرض `0` است.
`rowCount`	`integer`	فقط گزارش همزمان حداکثر تعداد ردیف برای بازگشت؛ ردیف های اضافی حذف می شوند. مقادیر قابل قبول شامل `0` تا `10000` است. پیش فرض `10000` است.
`maxRowsPerFile`	`integer`	فقط گزارش ناهمزمان حداکثر تعداد ردیف در هر فایل گزارش. یک گزارش بزرگ بر اساس این فیلد به فایل های زیادی تقسیم می شود. مقادیر قابل قبول شامل `1000000` تا `100000000` می باشد.
`includeRemovedEntities`	`boolean`	تعیین می کند که آیا نهادهای حذف شده باید در گزارش گنجانده شوند یا خیر. پیش فرض ها به `false` .
`columns[]. customDimensionName`	`string`	یک گزارش را بر اساس یک بعد سفارشی تقسیم می کند. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و بعد سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام ابعاد سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است. اگر در گزارش تبدیل استفاده شود، در صورت تنظیم، مقدار بعد سفارشی مشخص شده برای تبدیل داده شده را برمی‌گرداند. این ستون گزارش تبدیل را بخش بندی نمی کند.
`columns[]. platformSource`	`string`	پلتفرمی که برای ارائه داده برای بعد سفارشی استفاده می شود. مقادیر قابل قبول "فلور نور" هستند.
`filters[].column. customDimensionName`	`string`	یک گزارش را بر اساس یک بعد سفارشی تقسیم می کند. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و بعد سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام ابعاد سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است. اگر در گزارش تبدیل استفاده شود، در صورت تنظیم، مقدار بعد سفارشی مشخص شده برای تبدیل داده شده را برمی‌گرداند. این ستون گزارش تبدیل را بخش بندی نمی کند.
`filters[].column. headerText`	`string`	متن مورد استفاده برای شناسایی این ستون در خروجی گزارش. به طور پیش فرض `columnName` یا `savedColumnName` زمانی که مشخص نشده باشد. این می تواند برای جلوگیری از برخورد بین ستون های DoubleClick Search و ستون های ذخیره شده با همان نام استفاده شود.
`filters[].column. startDate`	`string`	تاریخ شامل در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `endDate` ارائه شود.
`filters[].column. endDate`	`string`	روز فراگیر در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `startDate` ارائه شود.
`filters[].column. groupByColumn`	`boolean`	فقط گزارش همزمان برای گروه بندی بر اساس این ستون روی `true` تنظیم کنید. پیش فرض ها به `false` .
`filters[].column. platformSource`	`string`	پلتفرمی که برای ارائه داده برای بعد سفارشی استفاده می شود. مقادیر قابل قبول "فلور نور" هستند.
`orderBy[].column. customDimensionName`	`string`	یک گزارش را بر اساس یک بعد سفارشی تقسیم می کند. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و بعد سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام ابعاد سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است. اگر در گزارش تبدیل استفاده شود، در صورت تنظیم، مقدار بعد سفارشی مشخص شده برای تبدیل داده شده را برمی‌گرداند. این ستون گزارش تبدیل را بخش بندی نمی کند.
`orderBy[].column. headerText`	`string`	متن مورد استفاده برای شناسایی این ستون در خروجی گزارش. به طور پیش فرض `columnName` یا `savedColumnName` زمانی که مشخص نشده باشد. این می تواند برای جلوگیری از برخورد بین ستون های DoubleClick Search و ستون های ذخیره شده با همان نام استفاده شود.
`orderBy[].column. startDate`	`string`	تاریخ شامل در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `endDate` ارائه شود.
`orderBy[].column. endDate`	`string`	روز فراگیر در قالب YYYY-MM-DD. در صورت ارائه، این بازه زمانی کلی گزارش را فقط برای این ستون لغو می‌کند. باید همراه با `startDate` ارائه شود.
`orderBy[].column. groupByColumn`	`boolean`	فقط گزارش همزمان برای گروه بندی بر اساس این ستون روی `true` تنظیم کنید. پیش فرض ها به `false` .
`orderBy[].column. platformSource`	`string`	پلتفرمی که برای ارائه داده برای بعد سفارشی استفاده می شود. مقادیر قابل قبول "فلور نور" هستند.
`columns[]. customMetricName`	`string`	نام یک سنجه سفارشی برای درج در گزارش. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و معیار سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام متریک سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است.
`filters[].column. customMetricName`	`string`	نام یک سنجه سفارشی برای درج در گزارش. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و معیار سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام متریک سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است.
`orderBy[].column. customMetricName`	`string`	نام یک سنجه سفارشی برای درج در گزارش. محدوده گزارش باید به یک تبلیغ‌کننده یا کمتر باشد، و معیار سفارشی باید قبلاً در جستجوی DoubleClick تنظیم شده باشد. نام متریک سفارشی، که در جستجوی DoubleClick ظاهر می‌شود، به حروف کوچک و بزرگ حساس است.
`columns[]. productReportPerspective`	`string`	معیارها را فقط برای نوع خاصی از فعالیت محصول برمی‌گرداند. مقادیر پذیرفته شده عبارتند از: " `sold` ": معیارهای بازده فقط برای محصولاتی که فروخته شده اند " `advertised` ": معیارها را فقط برای محصولاتی که در کمپین خرید تبلیغ شده اند و ممکن است فروخته شده باشند یا نه، برمی گرداند.
`filters[].column. productReportPerspective`	`string`	معیارها را فقط برای نوع خاصی از فعالیت محصول برمی‌گرداند. مقادیر پذیرفته شده عبارتند از: " `sold` ": معیارهای بازده فقط برای محصولاتی که فروخته شده اند " `advertised` ": معیارها را فقط برای محصولاتی که در کمپین خرید تبلیغ شده اند و ممکن است فروخته شده باشند یا نه، برمی گرداند.
`orderBy[].column. productReportPerspective`	`string`	معیارها را فقط برای نوع خاصی از فعالیت محصول برمی‌گرداند. مقادیر پذیرفته شده عبارتند از: " `sold` ": معیارهای بازده فقط برای محصولاتی که فروخته شده اند " `advertised` ": معیارها را فقط برای محصولاتی که در کمپین خرید تبلیغ شده اند و ممکن است فروخته شده باشند یا نه، برمی گرداند.

واکنش

در صورت موفقیت آمیز بودن، این روش یک منبع Reports را در بدنه پاسخ باز می گرداند.

آن را امتحان کنید!

از APIs Explorer زیر برای فراخوانی این روش در داده‌های زنده و دیدن پاسخ استفاده کنید. از طرف دیگر، اکسپلورر مستقل را امتحان کنید.