نمای کلی Google Analytics Data API

می‌توانید از Data API برای دسترسی برنامه‌نویسی‌شده به داده‌های گزارش Google Analytics استفاده کنید.

درباره دارایی‌های Google Analytics بیشتر بدانید.

داده‌های برگردانده‌شده توسط API با داده‌های نشان‌داده‌شده در میانای کاربر Google Analytics مطابقت دارد و کاملاً به تنظیمات هویت گزارش‌دهی (مانند «ترکیبی»، «مشاهده‌شده»، یا «مبتنی بر دستگاه») که برای دارایی Google Analytics شما پیکربندی شده است احترام می‌گذارد.

در اینجا چند نمونه از مواردی که ممکن است بااستفاده از Google Analytics Data API v1 گزارش دهید آورده شده است:

  • برنامه Android شما در هفته گذشته چند کاربر فعال روزانه داشته است.
  • تعداد بازدیدهای صفحه ۱۰ صفحه برتر در سایت شما در ۲۸ روز گذشته.
  • تعداد کاربران فعال برنامه iOS شما در ۳۰ دقیقه گذشته براساس کشور.

همچنین می‌توانید از Google Analytics Data API v1 برای انجام کارهای زیر استفاده کنید:

  • داشبوردهای سفارشی برای نمایش داده‌های Google Analytics بسازید.
  • برای صرفه‌جویی در زمان، تکالیف پیچیده گزارش‌دهی را خودکارسازی کنید.
  • داده‌های Google Analytics خود را با دیگر برنامه‌های کسب‌وکار ادغام کنید.

سازگاری داده‌ها و هویت گزارش‌کننده

‫Google Analytics Data API v1 به همان داده‌های گزارش دسترسی دارد که میانای Google Analytics دسترسی دارد. داده‌های برگردانده‌شده توسط میانای برنامه‌سازی کاربردی کاملاً به تنظیمات هویت گزارش‌کننده پیکربندی‌شده برای دارایی Google Analytics شما احترام می‌گذارد، بنابراین تعداد کاربران، حذف موارد تکراری، و مدل‌سازی داده‌ها با فضای هویت انتخاب‌شده —مانند ترکیبی، مشاهده‌شده، یا مبتنی بر دستگاه—در تنظیمات دارایی شما مطابقت دارد.

برای کسب اطلاعات بیشتر درباره اینکه فضاهای هویت مختلف چگونه می‌توانند بر گزارش‌هایتان تأثیر بگذارند، هویت گزارش‌کننده را ببینید.

شروع کنید

برای شروع کار با کتابخانه کارخواه در Java،‏ Python،‏ Node.js،‏ PHP،‏ C#‎،‏ Go، یا Ruby، به شروع سریع کتابخانه کارخواه مراجعه کنید. برای آشنایی با نحوه ساختن پُرسمان، فیلتر کردن بُعدها، و خواندن پاسخ‌ها، به ایجاد گزارش مراجعه کنید یا پُرسمان‌ها را به‌صورت تعاملی در کاوشگر پُرسمان آزمایش کنید.

نمونه درخواست و پاسخ runReport

برای پُرسمان داده‌های رویداد ازطریق REST، درخواست POST را به نقطه پایانی runReport با RunReportRequest بدنه JSON که dateRanges، dimensions، و metrics شما را مشخص می‌کند ارسال کنید:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ]
}

یا فرمان معادل curl را بااستفاده از اعتبارنامه پیش‌فرض برنامه اجرا کنید:

curl -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [
      { "startDate": "7daysAgo", "endDate": "yesterday" }
    ],
    "dimensions": [
      { "name": "country" }
    ],
    "metrics": [
      { "name": "activeUsers" }
    ]
  }'

میانای برنامه‌سازی کاربردی یک RunReportResponse حاوی سرصفحه‌های ستون و ردیف‌های داده برمی‌گرداند:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    },
    {
      "dimensionValues": [{ "value": "Japan" }],
      "metricValues": [{ "value": "2541" }]
    }
  ],
  "rowCount": 2,
  "kind": "analyticsData#runReport"
}

روش‌های دردسترس

در اینجا فهرستی از روش‌های Data API آورده شده است. برای جزئیات بیشتر، اسناد مرجع را ببینید.

  • runReport این روش گزارش سفارشی‌شده‌ای از داده‌های رویداد Google Analytics شما برمی‌گرداند و روش ترجیحی برای پرس‌وجوهای گزارش ساده است.
  • batchRunReports این نسخه دسته‌ای از روش runReport است که به شما امکان می‌دهد چندین گزارش را بااستفاده از یک فراخوانی API تولید کنید.
  • runPivotReport این روش گزارش محوری سفارشی‌شده‌ای از داده‌های رویداد Google Analytics شما برمی‌گرداند. گزارش‌های محوری قالب‌های پیشرفته‌تر و گویاتری نسبت به گزارش‌های معمولی هستند. هر محور ستون‌ها و ردیف‌های بُعد قابل‌مشاهده را در پاسخ گزارش شرح می‌دهد.
  • batchRunPivotReports این نسخه دسته‌ای از روش runPivotReport است که به شما امکان می‌دهد بااستفاده از یک فراخوانی API، چندین گزارش تولید کنید.
  • getMetadata این روش فراداده‌های مربوط به ابعاد و سنجه‌های موجود در روش‌های گزارش‌دهی را برمی‌گرداند. برای کاوش ابعاد و سنجه‌ها استفاده می‌شود. پاسخ این روش همچنین شامل ابعاد و سنجه‌های سفارشی دردسترس برای دارایی Google Analytics مشخص‌شده است.
  • checkCompatibility این روش ابعاد و سنجه‌هایی را فهرست می‌کند که می‌توانند به درخواست گزارش اضافه شوند و سازگاری را حفظ کنند.
  • runRealtimeReport این روش گزارش سفارشی‌شده‌ای از داده‌های رویداد هم‌زمان برای دارایی شما برمی‌گرداند. رویدادها چند ثانیه پس‌از ارسال به Google Analytics در گزارش‌های بلادرنگ نشان داده می‌شوند. گزارش‌های بلادرنگ رویدادها و داده‌های استفاده را برای دوره‌های زمانی از لحظه کنونی تا ۳۰ دقیقه قبل (تا ۶۰ دقیقه برای دارایی‌های Google Analytics 360) نشان می‌دهند.
  • properties.audienceExports گروهی از روش‌ها که به شما امکان می‌دهد برون‌بردهای مخاطب را تولید کنید، که شامل عکس آنی کاربران در یک مخاطب است.
  • properties.recurringAudienceLists (پیش‌نمایش اولیه) گروهی از روش‌ها که به شما امکان می‌دهد «برون‌بردهای مخاطب» تکرارشونده را مدیریت کنید. برون‌برد تکرارشونده مخاطب هر روز فهرست‌های مخاطب جدیدی تولید می‌کند.
  • runFunnelReport (پیش‌نمایش اولیه) این روش گزارش قیف سفارشی‌شده‌ای از داده‌های رویداد Google Analytics شما برمی‌گرداند. داده‌کاوی قیفی به شما امکان می‌دهد مراحلی را که کاربران برای تکمیل یک کار انجام می‌دهند تجسم کنید و به‌سرعت ببینید که آن‌ها در هر مرحله چقدر موفق یا ناموفق هستند.
  • properties.chat (پیش‌نمایش اولیه) این روش دسترسی مکالمه‌ای برنامه‌ای به پرسیدن از «مشاور» در Google Analytics را فراهم می‌کند. می‌توانید درباره داده‌های رویدادتان به زبان طبیعی سؤال بپرسید، تغییرات عملکرد را تشخیص دهید، و اطلاعات آماری جدولی و روایی ساختاریافته دریافت کنید.

ابعاد و سنجه‌های پشتیبانی‌شده

برای مشاهده فهرست همه ابعاد و سنجه‌های پشتیبانی‌شده توسط Data API، سند طرحواره API را ببینید.