گزارش کردن اصول اولیه تکالیف

بااستفاده از وظایف گزارش، می‌توانید درخواست ناهم‌زمان طولانی‌مدتی را برای ایجاد گزارش سفارشی از داده‌های رویداد Google Analytics خود شروع کنید.

از منبع وظیفه گزارش تولیدشده از این درخواست می‌توان برای دسترسی به گزارش‌های سفارشی‌شده توسط همه کاربرانی که به دارایی Google Analytics شما دسترسی خواندن دارند استفاده کرد.

گزارش سفارشی تا ۷۲ ساعت پس‌از آماده شدن دردسترس خواهد بود. پس‌از این دوره، منبع تکلیف گزارش مربوطه و محتوای آن به‌طور خودکار حذف خواهد شد.

ایجاد تکلیف گزارش

‫Google Analytics Data API v1 از رویکردی ناهمزمان برای ایجاد وظایف گزارش استفاده می‌کند. ابتدا، برای ایجاد تکلیف گزارش، درخواست به reportTasks.create روش ضروری است. سپس از روش reportTasks.query برای بازیابی گزارش سفارشی‌سازی‌شده تولیدشده استفاده می‌شود.

علاوه‌براین، می‌توانید از reportTasks.get برای بازیابی فراداده پیکربندی درباره تکلیف گزارش خاص و reportTasks.list برای فهرست کردن همه تکالیف گزارش برای دارایی استفاده کنید.

انتخاب نهاد گزارش‌دهنده

همه روش‌های «میانای برنامه‌سازی کاربردی داده v1» نیازمند این هستند که شناسه دارایی Google Analytics در مسیر درخواست نشانی وب به‌شکل properties/GA_PROPERTY_ID مشخص شود، برای نمونه:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

این گزارش براساس داده‌های رویداد Google Analytics جمع‌آوری‌شده در دارایی Google Analytics مشخص‌شده تولید می‌شود.

اگر از یکی از کتابخانه‌های مشتری Data API استفاده می‌کنید، نیازی نیست مسیر نشانی وب درخواست را به‌صورت دستی دستکاری کنید. بیشتر کارخواه‌های API پارامتر property را ارائه می‌دهند که انتظار دارد رشته‌ای به‌شکل properties/GA_PROPERTY_ID دریافت کند. برای نمونه‌هایی از استفاده از کتابخانه‌های مشتری، راهنمای شروع سریع را ببینید.

درخواست ایجاد تکلیف گزارش

برای ایجاد یک وظیفه گزارش، بااستفاده از ReportTask شیء در یک درخواست، reportTasks.create روش را فراخوانی کنید. پارامترهای زیر الزامی است:

درخواست ایجاد تکلیف گزارش نمونه:

درخواست HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

پاسخ روش reportTasks.create حاوی نام «وظیفه گزارش» در فیلد name (مثل properties/1234567/reportTasks/123) است که می‌توان از آن در پُرسمان‌های بعدی برای دریافت وضعیت وظیفه گزارش و بازیابی گزارش حاصل استفاده کرد.

پاسخ HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

دریافت وضعیت آمادگی تکلیف گزارش

ممکن است چند دقیقه طول بکشد تا گزارش پس‌از reportTasks.create تماس تولید شود. با فراخوانی روش reportTasks.get می‌توانید وضعیت آمادگی تکلیف گزارش را دریافت کنید.

از نام تکلیف گزارش (مثل properties/1234567/reportTasks/123) که از پاسخ reportTasks.create دریافت کرده‌اید برای مشخص کردن تکلیف گزارش استفاده کنید.

مثال:

درخواست HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

وضعیت آمادگی برای تکلیف گزارش در state فیلد پاسخ برگردانده می‌شود. پس‌از تکمیل تولید گزارش، وضعیت تکلیف گزارش از CREATING به ACTIVE تغییر می‌کند.

فیلد reportMetadata حاوی اطلاعات سطح بالا درباره گزارش تولیدشده است، مثل تعداد ردیف‌ها و مقدار نشان‌های سهمیه کسرشده.

پاسخ HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

با فراخوانی روش reportTasks.list می‌توانید وضعیت همه تکالیف گزارش را دریافت کنید.

بازیابی گزارش تولیدشده

وقتی تکلیف گزارش ایجادشده بااستفاده از reportTasks.create روش تولید می‌شود، reportTasks.query روش را فراخوانی کنید و نام تکلیف گزارش را مشخص کنید (مثلاً properties/1234567/reportTasks/123).

درخواست HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

اگر تکلیف گزارش آماده باشد، پاسخی حاوی گزارش تولیدشده برگردانده می‌شود:

پاسخ HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}