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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

درخواست اچ‌تی‌تی‌پی

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 دریافت کرده‌اید برای مشخص کردن تکلیف گزارش استفاده کنید.

مثال:

درخواست اچ‌تی‌تی‌پی

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).

درخواست اچ‌تی‌تی‌پی

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"
  }
}

مراحل بعدی