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

مهاجرت به Google Analytics Data API v1

این سند دستورالعمل‌هایی درباره نحوه انتقال کدهای موجود از Google Analytics Reporting API v4 به Google Analytics Data API v1 ارائه می‌کند و یک نمای کلی از تفاوت‌های کلیدی بین دو API ارائه می‌دهد.

چرا باید مهاجرت کنم

اگر برنامه شما نیاز به دسترسی به داده‌های موجود در ویژگی Google Analytics 4 دارد، لازم است کد را برای استفاده از Data API v1 به‌روزرسانی کنید، زیرا Reporting API v4 فقط می‌تواند به ویژگی‌های ایجاد شده با Universal Analytics دسترسی داشته باشد.

پیش نیازها

لطفاً با استفاده از راهنمای شروع سریع با مبانی Data API v1 آشنا شوید.

شروع شدن

برای شروع، یک ویژگی Google Analytics 4 را آماده می‌کنید، Data API v1 را فعال می‌کنید و سپس یک کتابخانه مشتری API مناسب برای پلتفرم خود راه‌اندازی می‌کنید.

یک ویژگی Google Analytics 4 آماده کنید

قبل از شروع انتقال کد خود برای پشتیبانی از Data API v1، باید وب سایت خود را برای استفاده از ویژگی Google Analytics 4 منتقل کنید . امکان پر کردن ویژگی Google Analytics 4 با داده های تاریخی از ویژگی Universal Analytics وجود ندارد.

API را فعال کنید

برای فعال کردن خودکار Data API v1 در Google Cloud Project انتخابی خود، روی این دکمه کلیک کنید.

استفاده از کتابخانه مشتری

یک کتابخانه مشتری نصب کنید

اگر از کتابخانه مشتری استفاده می کنید، باید کتابخانه سرویس گیرنده Data API v1 را برای زبان برنامه نویسی خود نصب کنید.

برو

go get google.golang.org/genproto/googleapis/analytics/data/v1beta

یک کتابخانه مشتری راه اندازی کنید

کتابخانه های سرویس گیرنده Data API v1 برای شروع سریع شما طراحی شده اند. به‌طور پیش‌فرض، کتابخانه‌های سرویس گیرنده سعی می‌کنند به طور خودکار اعتبار حساب سرویس شما را پیدا کنند .

یک راه آسان برای ارائه اعتبار حساب سرویس این است که با تنظیم متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS ، مشتری API از مقدار این متغیر برای یافتن فایل JSON کلید حساب سرویس استفاده می کند.

برای مثال، می‌توانید با اجرای دستور زیر و استفاده از مسیر فایل JSON حساب سرویس، اعتبار حساب سرویس را تنظیم کنید:

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

در زیر قطعه کدهایی که معمولاً برای مقداردهی اولیه کتابخانه های سرویس گیرنده Data API v1 استفاده می شوند، آمده است.

جاوا

google-analytics-data/src/main/java/com/google/analytics/data/samples/QuickstartSample.java

در Cloud Shell View در GitHub باز کنید

    // Using a default constructor instructs the client to use the credentials
    // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {QuickstartSample.java

پایتون

google-analytics-data/quickstart.py

در Cloud Shell View در GitHub باز کنید

    # Using a default constructor instructs the client to use the credentials
    # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = BetaAnalyticsDataClient()quickstart.py

.خالص

analytics-data/QuickStart/QuickStart.cs

در Cloud Shell View در GitHub باز کنید

            // Using a default constructor instructs the client to use the credentials
            // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
            BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
QuickStart.cs

PHP

analyticsdata/quickstart.php

در Cloud Shell View در GitHub باز کنید

// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
$client = new BetaAnalyticsDataClient();quickstart.php

Node.js

samples/quickstart.js

در Cloud Shell View در GitHub باز کنید

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require('@google-analytics/data');

  // Using a default constructor instructs the client to use the credentials
  // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
  const analyticsDataClient = new BetaAnalyticsDataClient();quickstart.js

به جای استفاده از یک متغیر محیطی، همچنین می‌توان اطلاعات اعتبارنامه را به طور صریح در طول مقداردهی اولیه به یک نمونه مشتری API ارسال کرد. در زیر قطعات مورد استفاده برای مقداردهی اولیه کتابخانه های سرویس گیرنده Data API v1 با ارسال اعتبار به صراحت در کد وجود دارد.

جاوا

google-analytics-data/src/main/java/com/google/analytics/data/samples/QuickstartJsonCredentialsSample.java

در Cloud Shell View در GitHub باز کنید

    // Explicitly use service account credentials by specifying
    // the private key file.
    GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));

    BetaAnalyticsDataSettings betaAnalyticsDataSettings =
        BetaAnalyticsDataSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
            .build();

    try (BetaAnalyticsDataClient analyticsData =
        BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {QuickstartJsonCredentialsSample.java

پایتون

google-analytics-data/quickstart_json_credentials.py

در Cloud Shell View در GitHub باز کنید

    # TODO(developer): Uncomment this variable and replace with a valid path to
    #  the credentials.json file for your service account downloaded from the
    #  Cloud Console.
    # credentials_json_path = "/path/to/credentials.json"

    # Explicitly use service account credentials by specifying
    # the private key file.
    client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)quickstart_json_credentials.py

.خالص

analytics-data/QuickStartJsonCredentials/QuickStartJsonCredentials.cs

در Cloud Shell View در GitHub باز کنید

            /**
             * TODO(developer): Uncomment this variable and replace with a valid path to
             *  the credentials.json file for your service account downloaded from the
             *  Cloud Console.
             *  Otherwise, default service account credentials will be derived from
             *  the GOOGLE_APPLICATION_CREDENTIALS environment variable.
             */
            // credentialsJsonPath = "/path/to/credentials.json";

            // Explicitly use service account credentials by specifying
            // the private key file.
            BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
            {
              CredentialsPath = credentialsJsonPath
            }.Build();
QuickStartJsonCredentials.cs

PHP

analyticsdata/src/client_from_json_credentials.php

در Cloud Shell View در GitHub باز کنید

/**
 * @param string $credentialsJsonPath Valid path to the credentials.json file for your service
 *                                    account downloaded from the Cloud Console.
 *                                    Example: "/path/to/credentials.json"
 */
function client_from_json_credentials(string $credentialsJsonPath)
{
    // Explicitly use service account credentials by specifying
    // the private key file.
    $client = new BetaAnalyticsDataClient([
        'credentials' => $credentialsJsonPath
    ]);

    return $client;
}client_from_json_credentials.php

Node.js

samples/quickstart_json_credentials.js

در Cloud Shell View در GitHub باز کنید

  /** TODO(developer): Uncomment this variable and replace with a valid path to
   *  the credentials.json file for your service account downloaded from the
   *  Cloud Console.
   */
  // credentialsJsonPath = '/path/to/credentials.json';

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require('@google-analytics/data');

  // Explicitly use service account credentials by specifying
  // the private key file.
  const analyticsDataClient = new BetaAnalyticsDataClient({
    keyFilename: credentialsJsonPath,
  });quickstart_json_credentials.js

عدم استفاده از کتابخانه مشتری

اگر از Reporting API v4 بدون کتابخانه کلاینت استفاده می‌کردید و می‌خواهید این کار را با Data API v1 ادامه دهید، همچنان می‌توانید از اعتبارنامه‌های خود استفاده کنید.

شما باید از نقطه پایانی HTTP و سند کشف جدید ارائه شده توسط Data API استفاده کنید:

https://analyticsdata.googleapis.com/v1beta

اگر کد شما از یک سند Discovery استفاده می کند، باید آن را به سند کشف ارائه شده توسط Data API v1 به روز کنید:

https://analyticsdata.googleapis.com/$discovery/rest?version=v1beta

پس از به روز رسانی نقطه پایانی، باید با ساختار درخواست و مفاهیم جدید Data API آشنا شوید تا بتوانید جستار JSON خود را به روز کنید.

گزارش اصلی

روش های گزارش دهی موجود

Reporting API v4 یک روش BatchGet را برای دسترسی به عملکرد گزارش اصلی آن ارائه کرد. Data API v1 چندین روش گزارش اصلی را برای انتخاب فراهم می کند:

runReport این روش یک گزارش سفارشی از داده‌های رویداد Google Analytics شما را برمی‌گرداند. از عملکرد محوری پشتیبانی نمی کند و یک روش ترجیحی برای درخواست های گزارش ساده است.
runPivotReport این روش یک گزارش محوری سفارشی از داده‌های رویداد Google Analytics شما را برمی‌گرداند. مشابه محورها در Reporting API v4، هر محور ستون‌ها و ردیف‌های بعد قابل مشاهده در پاسخ گزارش را توصیف می‌کند.
batchRunReports این یک نسخه دسته ای از روش runReport است که امکان تولید چندین گزارش را با استفاده از یک فراخوانی API واحد فراهم می کند.
batchRunPivotReports این یک نسخه دسته ای از روش runPivotReport است که امکان تولید چندین گزارش با استفاده از یک فراخوانی API را فراهم می کند.

هدف از داشتن چندین روش گزارش دهی بیشتر راحتی است، برخی از روش ها از ویژگی های پیچیده تری نسبت به سایرین پشتیبانی می کنند (پیوت ها، دسته بندی)، اما در غیر این صورت ساختار درخواست مشابهی را به اشتراک می گذارند.

تغییرات طرحواره API

قابلیت های گزارش هر دو API گزارش و API داده در درجه اول توسط طرح آنها تعیین می شود، یعنی ابعاد و معیارهایی که در جستارهای گزارش پشتیبانی می شوند. به دلیل تفاوت های مفهومی بین Universal Analytics و Google Analytics 4، تفاوت های قابل توجهی در طرحواره های API بین دو API وجود دارد.

با لیست فعلی ابعاد و معیارهای پشتیبانی شده توسط Data API آشنا شوید. در حال حاضر، تمام ابعاد و متریک ها با یکدیگر سازگار هستند، بنابراین نیازی به استفاده از Dimensions و Metrics Explorer برای تعیین ترکیب های سازگار نیست. این رفتار در آینده تغییر خواهد کرد.
به ابعاد سفارشی در Google Analytics 4 می توان با استفاده از دستور العمل ابعاد سفارشی Data API v1 که باید به جای شکاف های بعد ga:dimensionXX در Reporting API v4 استفاده شود، دسترسی داشت.
معیارهای سفارشی در Google Analytics 4 را می‌توان با استفاده از نحو معیارهای سفارشی Data API v1، که باید به‌جای اسلات‌های متریک ga:metricXX در Reporting API v4 استفاده شود، دسترسی داشت.
برخی از ابعاد و معیارهای موجود در Universal Analytics معادل مستقیمی در Google Analytics 4 دارند. برای اطلاعات بیشتر به نمودار هم ارزی طرحواره UA/GA4 API مراجعه کنید.
نام ابعاد و متریک دیگر پیشوند ga: در Google Analytics 4 ندارد.
برخی از عملکردهای موجود در Universal Analytics هنوز در GA4 در دسترس نیست (مثلاً Campaign Manager، DV360، Search Ads 360 ادغام). هنگامی که این قابلیت در Google Analytics 4 پیاده سازی شد، Data API از آن پشتیبانی می کند، ابعاد و معیارهای جدیدی به طرح API اضافه می شود.

موجودیت ها

Google Analytics 4 هیچ مفهومی از نماها (پروفایل) معرفی شده در یونیورسال آنالیتیکس ندارد. در نتیجه، هیچ پارامتر viewId در هیچ کجای درخواست های گزارش Data API v1 وجود ندارد. درعوض، هنگام فراخوانی متدهای Data API v1، یک شناسه خصوصیت عددی Google Analytics 4 باید در مسیر URL درخواست مشخص شود. این رفتار با Reporting API v4 متفاوت است، که برای شناسایی نهاد گزارش‌دهنده به شناسه‌های view (پروفایل) متکی است.

Data API v1

در مورد Data API v1، یک شناسه خصوصیت عددی Google Analytics 4 باید در مسیر URL مشخص شود.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport

گزارش API v4

Reporting API v4 نیاز به یک شناسه نمای Universal Analytics (نمایه) دارد که در متن جستجوی گزارش مشخص شود.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",

    ....

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

محدوده تاریخ

هم Reporting API v4 و هم Data API v1 از چندین محدوده تاریخ مشخص شده با استفاده از قسمت dateRanges در یک درخواست گزارش پشتیبانی می‌کنند. هر دو API از قالب ورودی تاریخ یکسانی استفاده می کنند، مقادیر مطلق تاریخ را به شکل YYYY-MM-DD یا تاریخ های نسبی مانند yesderday ، today ، 7daysAgo و غیره را می پذیرند.

درخواست های Data API v1 به 4 محدوده تاریخ محدود می شوند، در حالی که Reporting API v4 امکان 2 محدوده تاریخ را در یک درخواست گزارش واحد فراهم می کند.

هر dateRange در Data API v1 ممکن است یک فیلد name اختیاری داشته باشد که می تواند برای ارجاع به محدوده تاریخ مربوطه در یک پاسخ استفاده شود. اگر name ارائه نشده باشد، نام محدوده تاریخ به طور خودکار ایجاد می شود.

هنگامی که چندین محدوده تاریخ در یک درخواست Data API v1 مشخص می شود، یک بعد dateRange جدید به طور خودکار به یک پاسخ اضافه می شود و نام محدوده تاریخ به عنوان مقدار بعد استفاده می شود. توجه داشته باشید که این رفتار با Reporting API v4 متفاوت است، که داده‌های محدوده تاریخ را به عنوان گروهی از مقادیر متریک در هر ردیف برمی‌گرداند.

درخواست Data API v1

یک فیلد name اختیاری برای هر مقدار dateRange در یک درخواست استفاده می شود. این نام محدوده تاریخ به عنوان مقدار بعد dateRange در پاسخ استفاده خواهد شد.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "metrics": [
    {
      "name": "sessions"
    }
  ],
  "dimensions": [
    {
      "name": "country"
    }
  ],
  "dateRanges": [
    {
      "startDate": "2020-01-01",
      "endDate": "2020-01-31",
      "name": "year_ago"
    },
    {
      "startDate": "2021-01-01",
      "endDate": "2021-01-31",
      "name": "current_year"
    }
  ]
}

Data API v1 Response

یک بعد dateRange اضافی به طور خودکار در پاسخ گنجانده شده است. مقدار بعد dateRange حاوی نام یک محدوده تاریخ است که یا از قسمت dateRange.name می آید یا به طور خودکار ایجاد می شود.

....

"dimensionHeaders": [
  {
    "name": "country"
  },
  {
    "name": "dateRange"
  }
],

....

"rows": [

....

  {
    "dimensionValues": [
      {
        "value": "Japan"
      },
      {
        "value": "year_ago"
      }
    ],
    "metricValues": [
      {
        "value": "253286"
      }
    ]
  },
  {
    "dimensionValues": [
      {
        "value": "Japan"
      },
      {
        "value": "current_year"
      }
    ],
    "metricValues": [
      {
        "value": "272582"
      }
    ]
  },

....

گزارش درخواست API v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "2020-01-01",
          "endDate": "2020-01-31",
        },
        {
          "startDate": "2021-01-01",
          "endDate": "2021-01-31",
        }
      ],
      "metrics": [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions": [
        {
          "name": "ga:country"
        }
      ]
    }
  ]
}

گزارش پاسخ API v4

در Reporting API v4، مقادیر برای هر محدوده تاریخ در قسمت metrics گروه‌بندی می‌شوند:

{
  "dimensions": [
    "Japan"
  ],
  "metrics": [
    {
      "values": [
        "253286"
      ]
    },
    {
      "values": [
        "272582"
      ]
    }
  ]
},

مرتب سازی

رفتار سفارشی جستجوهای گزارش Data API v1 را می توان با استفاده از فیلد orderBys ، مشابه فیلد orderBys در Reporting API v4، کنترل کرد.

مشخصات OrderBy در Data API v1 تغییر کرده است. هر OrderBy می تواند شامل یکی از موارد زیر باشد:

DimensionOrderBy ، نتایج را بر اساس مقادیر یک بعد مرتب می کند.
MetricOrderBy ، نتایج را بر اساس مقادیر یک متریک مرتب می کند.
PivotOrderBy ، در جستارهای محوری استفاده می شود و نتایج را بر اساس مقادیر یک متریک در یک گروه ستون محوری مرتب می کند.

انواع سفارش DELTA ، SMART ، HISTOGRAM_BUCKET که توسط Reporting API v4 پشتیبانی می شوند، در Data API v1 اجرا نمی شوند.

نوع سفارش OrderType.NUMERIC Data API v1 معادل مقدار OrderType.DIMENSION_AS_INTEGER Reporting API v4 است.

درخواست Data API v1

این مثال یک پرس و جو نمونه را نشان می دهد که تعداد جلسات را بر اساس کشور گزارش می دهد و ردیف ها را بر اساس متریک sessions به ترتیب نزولی مرتب می کند.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "metrics": [
    {
      "name": "sessions"
    }
  ],
  "dimensions": [
    {
      "name": "country"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "today"
    }
  ],
  "orderBys": [
    {
      "metric": {
        "metricName": "sessions"
      },
      "desc": true
    }
  ]
}

Data API v1 Response

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "510449"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "283430"
        }
      ]
    },

....

  ],
  "totalSize": 212,
  "metadata": {}
}

گزارش درخواست API v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "yesterday",
          "endDate": "today"
        }
      ],
      "metrics": [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions": [
        {
          "name": "ga:country"
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "sortOrder": "DESCENDING"
        }
      ]
    }
  ]
}

گزارش پاسخ API v4

{
"reports": [
  {

....

    "data": {
      "rows": [
        {
          "dimensions": [
            "United States"
          ],
          "metrics": [
            {
              "values": [
                "510449"
              ]
            }
          ]
        },
        {
          "dimensions": [
            "Japan"
          ],
          "metrics": [
            {
              "values": [
                "283430"
              ]
            }
          ]
        },

....

    }
  ]
}

فیلتر کردن

از عبارت dimensionFilter و metricFilter در Data API v1 می توان برای درخواست از API استفاده کرد که فقط داده ها را برای ابعاد یا مقادیر متریک خاص برگرداند. این شبیه به dimensionFilterClauses و metricFilterClauses در Reporting API v4 است.

Data API v1 از رشته های عبارت فیلتر مانند بند filtersExpression Reporting API v4 پشتیبانی نمی کند. این عبارات باید با استفاده از عبارت dimensionFilter و metricFilter بازنویسی شوند.

درخواست Data API v1

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

عبارت dimensionFilter فقط برای بازگرداندن ردیف‌هایی استفاده می‌شود که مقادیر ابعاد pagePath با /webstore/ شروع می‌شوند و حاوی رشته action=a12345 هستند.

عبارت metricFilter از متد runReport می‌خواهد که فقط ردیف‌هایی را با مقادیر متریک sessions بزرگتر از 1000 برگرداند.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "metrics": [
    {
      "name": "sessions"
    }
  ],
  "dimensions": [
    {
      "name": "pagePath"
    }
  ],
  "dimensionFilter": {
    "andGroup": {
      "expressions": [
        {
          "filter": {
            "stringFilter": {
              "value": "/webstore/",
              "matchType": "BEGINS_WITH"
            },
            "fieldName": "pagePath"
          }
        },
        {
          "filter": {
            "stringFilter": {
              "matchType": "CONTAINS",
              "value": "action=a12345"
            },
            "fieldName": "pagePath"
          }
        }
      ]
    }
  },
  "metricFilter": {
    "filter": {
      "numericFilter": {
        "value": {
          "int64Value": 1000
        },
        "operation": "GREATER_THAN"
      },
      "fieldName": "sessions"
    }
  },
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "today"
    }
  ]
}

گزارش درخواست API v4

این درخواست نمونه مشابه نمونه Data API v1 است. لیستی از تعداد جلسات برای مسیرهای صفحه خاصی که توسط کاربران بازدید شده است را برمی گرداند.

از فیلد dimensionFilterClauses فقط برای برگرداندن ردیف‌هایی استفاده می‌شود که مقادیر ابعاد pagePath با /webstore/ شروع می‌شوند و حاوی رشته action=a12345 هستند.

فیلد metricFilterClauses فقط برای برگرداندن ردیف هایی با مقادیر متریک ga:sessions بزرگتر از 1000 استفاده می شود.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "metrics": [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions": [
        {
          "name": "ga:pagePath"
        }
      ],
      "metricFilterClauses": [
        {
          "filters": [
            {
              "metricName": "ga:sessions",
              "operator": "GREATER_THAN",
              "comparisonValue": "1000"
            }
          ]
        }
      ],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:pagePath",
              "operator": "BEGINS_WITH",
              "expressions": [
                "/webstore/"
              ]
            },
            {
              "dimensionName": "ga:pagePath",
              "operator": "PARTIAL",
              "expressions": [
                "action=a12345"
              ]
            }
          ],
          "operator": "AND"
        }
      ],
      "dateRanges": [
        {
          "startDate": "yesterday",
          "endDate": "today"
        }
      ]
    }
  ]
}

صفحه بندی

Data API v1 از فیلدهای محدود و آفست برای صفحه بندی از طریق نتایج پاسخ که چندین صفحه را شامل می شود استفاده می کند، در حالی که Reporting API v4 از pageToken و pageSize استفاده می کند.

برای درخواست‌های محوری Data API v1، فیلدهای limit و offset شی Pivot باید برای پیاده‌سازی صفحه‌بندی برای هر محور به‌صورت جداگانه استفاده شود. اکنون فیلد limit برای هر شی Pivot لازم است.

به طور پیش‌فرض، Data API v1 حداکثر 10000 ردیف اول داده رویداد را برمی‌گرداند، در حالی که مقدار پیش‌فرض برای Reporting API v4 1000 ردیف است.

تعداد کل ردیف های مطابق با پرس و جو با استفاده از فیلد rowCount در پاسخ Data API v1، که مشابه Reporting API v4 است، برگردانده می شود.

درخواست Data API v1

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [

....

  ],
  "metrics": [

....

  ],
  "dimensions": [

....

  ],
  "limit": 5,
  "offset": 15
}

Data API v1 Response

{
  "dimensionHeaders": [

....

  ],
  "metricHeaders": [

....

  ],
  "rows": [

....

  ],
  "rowCount": 228,
}

گزارش درخواست API v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dateRanges": [

....

      ],
      "metrics": [

....

      ],
      "dimensions": [

....

      ],
      "pageSize": 5,
      "pageToken": "5"

    }
  ]
}

گزارش پاسخ API v4

{
  "reports": [
    {

....

      "data": {
        "rows": [

....

        ],

....

        "rowCount": 225,
      },
      "nextPageToken": "15"
    }
  ]
}

تجمعات متریک

Data API v1 فقط زمانی مقادیر تجمیع را محاسبه می کند که فیلد metricAggregations در یک درخواست مشخص شده باشد. در مقابل، Reporting API v4 مقادیر کل، حداقل و حداکثر را برای هر متریک به طور پیش‌فرض برمی‌گرداند، مگر اینکه فیلدهای hideTotals و hideValueRanges روی true تنظیم شده باشند.`

درخواست Data API v1

تجمیع‌ها تنها در صورتی محاسبه می‌شوند که فیلد metricAggregations در یک درخواست مشخص شده باشد.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "metricAggregations": [
    "TOTAL",
    "MAXIMUM",
    "MINIMUM"
  ],
  "metrics": [
    {
      "name": "sessions"
    }
  ],
  "dimensions": [
    {
      "name": "country"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "today"
    }
  ]
}

Data API v1 Response

ردیف‌های متریک جمع‌آوری شده در فیلدهای totals ، minimum و maximum یک پاسخ برگردانده می‌شوند. برای ردیف‌های متریک انبوه، فیلد dimensionValues حاوی مقدار ویژه RESERVED_TOTAL ، RESERVED_MAX یا RESERVED_MIN است.

{
  "dimensionHeaders": [

  ....

  ],
  "metricHeaders": [

  ....

  ],
  "rows": [

  ....

  ],
  "totals": [
    {
      "dimensionValues": [
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6026053"
        }
      ]
    }
  ],
  "maximums": [
    {
      "dimensionValues": [
        {
          "value": "RESERVED_MAX"
        },
        {
          "value": "RESERVED_MAX"
        }
      ],
      "metricValues": [
        {
          "value": "493655"
        }
      ]
    }
  ],
  "minimums": [
    {
      "dimensionValues": [
        {
          "value": "RESERVED_MIN"
        },
        {
          "value": "RESERVED_MIN"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    }
  ],

....

}

گزارش درخواست API v4

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

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "yesterday",
          "endDate": "today"
        }
      ],
      "metrics": [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions": [
        {
          "name": "ga:country"
        }
      ],
    }
  ]
}

گزارش پاسخ API v4

فیلدهای totals ، minimums و maximums به طور پیش فرض در یک پاسخ Reporting API v4 وجود دارد.

{
  "reports": [
    {
      "columnHeader": {

         ....

      },
      "data": {
        "rows": [

         ....

        ],

       ....

        "totals": [
          {
            "values": [
              "4493363"
            ]
          }
        ],
        "minimums": [
          {
            "values": [
              "1"
            ]
          }
        ],
        "maximums": [
          {
            "values": [
              "684005"
            ]
          }
        ]

      }
    }
  ]
}

محورها

Data API v1 از عملکرد محوری در روش های گزارش runPivotReport و batchRunPivotReports پشتیبانی می کند.

Reporting API v4 اجازه می دهد تا با استفاده از روش batchGet ، محورها را در جستارهای گزارش دهی قرار دهید.

Pivot ها در Data API v1 در مقایسه با Reporting API v4 متفاوت اجرا می شوند، به گونه ای که هر سطر پاسخ نشان دهنده یک سلول از جدول است، در حالی که در Reporting API v4 یک ردیف پاسخ یک خط جدول کامل را نشان می دهد.

Data API v1

در زیر بخشی از پاسخ Data API v1 به کوئری runPivotReport است. هر سلول از گزارش چرخشی به صورت جداگانه برگردانده می شود:

    "rows": [
      {
        "dimensionValues": [
          {
            "value": "Albania"
          },
          {
            "value": "Edge"
          }
        ],
        "metricValues": [
          {
            "value": "1701"
          }
        ]
      },

گزارش API v4

در زیر بخشی از پاسخ Reporting API v4 به درخواست batchGet است. یک سطر پاسخ منفرد یک خط جدول کامل را نشان می دهد که حاوی تمام مقادیر متریک برای pivot در pivotValueRegions است:

      "data": {
        "rows": [
          {
            "dimensions": [
              "Albania"
            ],
            "metrics": [
              {
                "values": [
                  "42394"
                ],
                "pivotValueRegions": [
                  {
                    "values": [
                      "24658",
                      "17208",
                      "132"
                    ]
                  }
                ]
              }
            ]
          },

در Data API v1، هر بعد از query runPivotReport یا batchRunPivotReports باید در یک شی محوری تعریف شود. یک بعد در صورتی که در هیچ محوری از پرس و جوی محوری استفاده نشود در گزارش قابل مشاهده نخواهد بود.

ستون‌های محوری Data API v1 با استفاده از قسمت fieldNames به جای قسمت dimensions Reporting API v4 مشخص می‌شوند.

اگر فیلتر ابعاد در درخواست گزارش Data API v1 مورد نظر است، باید از فیلتر ابعاد محدوده درخواست استفاده شود. این با Reporting API v4 متفاوت است که مشخصات dimensionFilterClauses را در یک شی محوری می پذیرد.

فیلد افست Data API v1 از نظر عملکردی شبیه به قسمت startGroup Reporting API v4 است.

فیلد محدودیت Data API v1 شبیه maxGroupCount گزارش API v4 است و باید برای محدود کردن اصل گزارش استفاده شود.

Data API v1 از چندین محور پشتیبانی می کند تا زمانی که حاصلضرب پارامتر limit برای هر محور از 100000 تجاوز نکند. Reporting API v4 تنها از یک بعد محوری پشتیبانی می کند.

به طور پیش‌فرض، Data API v1 ابعاد را در یک محور بر اساس اولین متریک در گزارش سفارش می‌دهد. این رفتار با Reporting API v4 متفاوت است، جایی که ترتیب محوری با ترتیب نزولی «کل» معیارهای درخواستی تعیین می‌شود . برای تعیین ترتیب مرتب سازی در Data API v1، از قسمت orderBys یک مشخصات Pivot استفاده کنید.

درخواست Data API v1

این پرس و جو محوری Data API v1 گزارشی از تعداد جلسات بر اساس کشور ایجاد می‌کند که بر اساس بعد browser تعیین می‌شود. توجه داشته باشید که چگونه کوئری از فیلدهای orderBys ، limit ، offset برای بازتولید رفتار یک جستار مشابه Reporting API v4 استفاده می کند تا تنظیمات ترتیب و صفحه بندی را حفظ کند.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport

{
  "dateRanges": [
    {
      "startDate": "2021-01-01",
      "endDate": "2021-01-30"
    }
  ],
  "pivots": [
    {
      "fieldNames": [
        "country"
      ],
      "limit": 250,
      "orderBys": [
        {
          "dimension": {
            "dimensionName": "country"
          }
        }
      ]
    },
    {
      "fieldNames": [
        "browser"
      ],
      "offset": 3,
      "limit": 3,
      "orderBys": [
        {
          "metric": {
            "metricName": "sessions"
          },
          "desc": true
        }
      ]
    }
  ],
  "metrics": [
    {
      "name": "sessions"
    }
  ],
  "dimensions": [
    {
      "name": "country"
    },
    {
      "name": "browser"
    }
  ]
}

Data API v1 Response

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "(not set)"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Albania"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Algeria"
            }
          ]
        }
      ],
      "rowCount": 234
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Safari"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Edge"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Opera"
            }
          ]
        }
      ],
      "rowCount": 124
    }
  ],
  "dimensionHeaders": [
    {
      "name": "country"
    },
    {
      "name": "browser"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "(not set)"
        },
        {
          "value": "Safari"
        }
      ],
      "metricValues": [
        {
          "value": "2531"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "(not set)"
        },
        {
          "value": "Edge"
        }
      ],
      "metricValues": [
        {
          "value": "1701"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "(not set)"
        },
        {
          "value": "Opera"
        }
      ],
      "metricValues": [
        {
          "value": "1564"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Albania"
        },
        {
          "value": "Safari"
        }
      ],
      "metricValues": [
        {
          "value": "2531"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Albania"
        },
        {
          "value": "Edge"
        }
      ],
      "metricValues": [
        {
          "value": "1701"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Albania"
        },
        {
          "value": "Opera"
        }
      ],
      "metricValues": [
        {
          "value": "1564"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Algeria"
        },
        {
          "value": "Safari"
        }
      ],
      "metricValues": [
        {
          "value": "237"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Algeria"
        },
        {
          "value": "Edge"
        }
      ],
      "metricValues": [
        {
          "value": "44"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Algeria"
        },
        {
          "value": "Opera"
        }
      ],
      "metricValues": [
        {
          "value": "22"
        }
      ]
    },

....

  ],

....

}

گزارش درخواست API v4

این پرس و جو محوری Reporting API v4 گزارشی از تعداد جلسات بر اساس کشور ایجاد می کند که بر اساس بعد ga:browser تنظیم می شود.

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "2021-01-01",
          "endDate": "2021-01-30"
        }
      ],
      "metrics": [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions": [
        {
          "name": "ga:country"
        }
      ],
      "pivots": [
        {
          "dimensions": [
            {
              "name": "ga:browser"
            }
          ],
          "startGroup": 3,
          "maxGroupCount": 3,
          "metrics": [
            {
              "expression": "ga:sessions"
            }
          ]
        }
      ]
    }
  ]
}

گزارش پاسخ API v4

{
  "reports": [
    {
      "columnHeader": {
        "dimensions": [
          "ga:country"
        ],
        "metricHeader": {
          "metricHeaderEntries": [
            {
              "name": "ga:sessions",
              "type": "INTEGER"
            }
          ],
          "pivotHeaders": [
            {
              "pivotHeaderEntries": [
                {
                  "dimensionNames": [
                    "ga:browser"
                  ],
                  "dimensionValues": [
                    "Edge"
                  ],
                  "metric": {
                    "name": "ga:sessions",
                    "type": "INTEGER"
                  }
                },
                {
                  "dimensionNames": [
                    "ga:browser"
                  ],
                  "dimensionValues": [
                    "Opera"
                  ],
                  "metric": {
                    "name": "ga:sessions",
                    "type": "INTEGER"
                  }
                },
                {
                  "dimensionNames": [
                    "ga:browser"
                  ],
                  "dimensionValues": [
                    "Samsung Internet"
                  ],
                  "metric": {
                    "name": "ga:sessions",
                    "type": "INTEGER"
                  }
                }
              ],
              "totalPivotGroupsCount": 19
            }
          ]
        }
      },
      "data": {
        "rows": [
          {
            "dimensions": [
              "(not set)"
            ],
            "metrics": [
              {
                "values": [
                  "781283"
                ],
                "pivotValueRegions": [
                  {
                    "values": [
                      "6923",
                      "1385",
                      "66"
                    ]
                  }
                ]
              }
            ]
          },
          {
            "dimensions": [
              "Albania"
            ],
            "metrics": [
              {
                "values": [
                  "42394"
                ],
                "pivotValueRegions": [
                  {
                    "values": [
                      "24658",
                      "17208",
                      "132"
                    ]
                  }
                ]
              }
            ]
          },
          {
            "dimensions": [
              "Algeria"
            ],
            "metrics": [
              {
                "values": [
                  "23208"
                ],
                "pivotValueRegions": [
                  {
                    "values": [
                      "19252",
                      "66",
                      "1582"
                    ]
                  }
                ]
              }
            ]
          },

  ....

        ],

  ....

      }
    }
  ]
}

گروه ها

Data API v1 از مشخصات CohortSpec برای پیکربندی گزارش های گروهی استفاده می کند. این شبیه به مشخصات CohortGroup گزارش API v4 است.

همه معیارهای موجود در Data API v1 در حال حاضر با جستارهای همگروهی سازگار هستند، در حالی که Reporting API v4 فقط اجازه می‌دهد زیرمجموعه‌ای از معیارهای خاص در یک جستار همگروهی استفاده شود.

در درخواست گروه Data API v1، cohortActiveUsers متریک مورد نیاز است.

هم Data API v1 و هم Reporting API v4 حداکثر 12 گروه در یک درخواست را امکان پذیر می کنند.

معیارهای ارزش طول عمر (LTV) در حال حاضر در Data API v1 پشتیبانی نمی‌شوند.

هم ارزی سنجه های همگروهی

طبق نمودار زیر، اکثر معیارهای همگروهی تعریف شده در Reporting API v4 را می توان با یک عبارت جایگزین کرد تا به نتیجه ای معادل در Data API v1 دست یابد.

گزارش نام متریک API v4	نام یا عبارت متریک Data API v1
ga:cohortActiveUsers	cohortActiveUsers
ga:cohortTotalUsers	cohortTotalUsers
ga:cohortRetentionRate	"expression": "cohortActiveUsers/cohortTotalUsers"
ga:cohortRevenuePerUser	"expression": "totalRevenue/cohortActiveUsers"
ga:cohortVisitDurationPerUser	"expression": "userEngagementDuration/cohortActiveUsers"
ga:cohortAppviewsPerUser	"expression": "screenPageViews/cohortActiveUsers"
ga:cohortPageviewsPerUser	"expression": "screenPageViews/cohortActiveUsers"
ga:cohortSessionsPerUser	"expression": "sessions/cohortActiveUsers"
ga:cohortGoalCompletionsPerUser	"expression": "eventCount/cohortActiveUsers"، علاوه بر یک فیلتر بعد توسط `eventName` مربوط به رویداد تکمیل هدف مورد نظر.

درخواست Data API v1

یک جستجوی نمونه که گروهی از کاربران را که اولین جلسه آنها در هفته 03-01-2021 اتفاق افتاده است، پیکربندی می کند. تعداد کاربران فعال و نرخ حفظ کاربر برای گروه در طول 5 هفته، با استفاده از جزئیات هفتگی محاسبه می‌شود.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "name": "cohort",
        "dateRange": {
          "startDate": "2021-01-03",
          "endDate": "2021-01-09"
        }
      }
    ],
    "cohortsRange": {
      "startOffset": 0,
      "endOffset": 4,
      "granularity": "WEEKLY"
    }
  },
  "metrics": [
    {
      "name": "cohortActiveUsers"
    },
    {
      "expression": "cohortActiveUsers/cohortTotalUsers",
      "name": "cohortRetentionRate"
    }
  ],
  "dimensions": [
    {
      "name": "cohort"
    },
    {
      "name": "cohortNthWeek"
    }
  ]
}

Data API v1 Response

{
  "dimensionHeaders": [
    {
      "name": "cohort"
    },
    {
      "name": "cohortNthWeek"
    }
  ],
  "metricHeaders": [
    {
      "name": "cohortActiveUsers",
      "type": "TYPE_INTEGER"
    },
    {
      "name": "cohortRetentionRate",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "cohort"
        },
        {
          "value": "0000"
        }
      ],
      "metricValues": [
        {
          "value": "4268816"
        },
        {
          "value": "0.999913800857494"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "cohort"
        },
        {
          "value": "0001"
        }
      ],
      "metricValues": [
        {
          "value": "241580"
        },
        {
          "value": "0.056586926213534013"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "cohort"
        },
        {
          "value": "0002"
        }
      ],
      "metricValues": [
        {
          "value": "159390"
        },
        {
          "value": "0.037335003597877253"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "cohort"
        },
        {
          "value": "0003"
        }
      ],
      "metricValues": [
        {
          "value": "131512"
        },
        {
          "value": "0.030804950079453122"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "cohort"
        },
        {
          "value": "0004"
        }
      ],
      "metricValues": [
        {
          "value": "96793"
        },
        {
          "value": "0.022672482610259947"
        }
      ]
    }
  ],
  "totalSize": 5,
  "metadata": {}
}

گزارش درخواست API v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "UA_VIEW_ID",
      "dimensions": [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthWeek"
        }
      ],
      "metrics": [
        {
          "expression": "ga:cohortActiveUsers"
        },
        {
          "expression": "ga:cohortRetentionRate"
        }
      ],
      "cohortGroup": {
        "cohorts": [
          {
            "name": "cohort",
            "type": "FIRST_VISIT_DATE",
            "dateRange": {
              "startDate": "2021-01-03",
              "endDate": "2021-01-09"
            }
          }
        ]
      }
    }
  ]
}

گزارش پاسخ API v4

{
  "reports": [
    {
      "columnHeader": {
        "dimensions": [
          "ga:cohort",
          "ga:cohortNthWeek"
        ],
        "metricHeader": {
          "metricHeaderEntries": [
            {
              "name": "ga:cohortActiveUsers",
              "type": "INTEGER"
            },
            {
              "name": "ga:cohortRetentionRate",
              "type": "PERCENT"
            }
          ]
        }
      },
      "data": {
        "rows": [
          {
            "dimensions": [
              "cohort",
              "0000"
            ],
            "metrics": [
              {
                "values": [
                  "40793",
                  "100.0"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0001"
            ],
            "metrics": [
              {
                "values": [
                  "3883",
                  "9.518789988478416"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0002"
            ],
            "metrics": [
              {
                "values": [
                  "2165",
                  "5.307283112298679"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0003"
            ],
            "metrics": [
              {
                "values": [
                  "1703",
                  "4.174735861544873"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0004"
            ],
            "metrics": [
              {
                "values": [
                  "1484",
                  "3.637879047875861"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0005"
            ],
            "metrics": [
              {
                "values": [
                  "1103",
                  "2.7038952761503197"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0006"
            ],
            "metrics": [
              {
                "values": [
                  "933",
                  "2.28715711028853"
                ]
              }
            ]
          },
          {
            "dimensions": [
              "cohort",
              "0007"
            ],
            "metrics": [
              {
                "values": [
                  "336",
                  "0.8236707278209496"
                ]
              }
            ]
          }
        ],
        "totals": [
          {
            "values": [
              "52400",
              "16.056676390557204"
            ]
          }
        ],
        "rowCount": 8,
        "minimums": [
          {
            "values": [
              "336",
              "0.8236707278209496"
            ]
          }
        ],
        "maximums": [
          {
            "values": [
              "40793",
              "100.0"
            ]
          }
        ],
        "isDataGolden": true
      }
    }
  ]
}

نمونه برداری

Data API v1 به طور خودکار از نمونه‌گیری داده استفاده می‌کند که پیش‌بینی می‌کند محدودیت‌های اصلی کیفیت داده را کاهش می‌دهد. اگر از نتایج یک محدوده تاریخ نمونه برداری شود، metadata RunReportResponse حاوی SamplingMetadata مربوطه است، مشابه فیلد samplingLevel که در Reporting API v4 وجود داشت.

تازگی داده ها

Data API معادلی برای فیلد isDataGolden از Reporting API v4 ارائه نمی‌کند، که برای نشان دادن اینکه آیا تمام بازدیدهای یک گزارش پردازش به پایان رسیده است یا خیر، استفاده می‌شود. هنوز هم ممکن است که همان گزارش به دلیل پردازش اضافی، نتایج متفاوتی را در زمانی که در تاریخ بعدی پرس و جو می شود، نشان دهد.

(پشتیبانی نمی شود) بخش ها

بخش‌ها در حال حاضر در Data API v1 پشتیبانی نمی‌شوند.

گزارش در زمان واقعی

از روش properties.runRealtimeReport در Data API v1 برای تولید گزارش‌های بلادرنگ برای ویژگی‌های Google Analytics 4 استفاده کنید. عملکرد گزارش‌دهی هم‌زمان برای ویژگی‌های Universal Analytics با روش data.realtime.get از Google Analytics API v3 ارائه شده است.

به دلیل تفاوت‌های مفهومی بین Universal Analytics و Google Analytics 4، طرح گزارش‌دهی هم‌زمان Data API با طرح گزارش‌دهی هم‌زمان Analytics API v3 متفاوت است.

درخواست Data API v1

در مثال زیر، برای حفظ رفتار مرتب‌سازی پیش‌فرض Google Analytics API v3، یک عنصر orderBy اختیاری به کوئری نمونه Data API v1 اضافه شد.

POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
  "dimensions": [{ "name": "country" }],
  "metrics": [{ "name": "activeUsers" }],
  "orderBys": [
     {
       "dimension": {
         "dimensionName": "country"
         }
     }
   ]
}

Data API v1 Response

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": ""
        }
      ],
      "metricValues": [
        {
          "value": "199"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Afghanistan"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Albania"
        }
      ],
      "metricValues": [
        {
          "value": "136"
        }
      ]
    },

    ....

  ],
  "rowCount": 172
}

درخواست Google Analytics API v3

GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country

پاسخ Google Analytics API v3

{
  "kind": "analytics#realtimeData",
  "id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
  "query": {
    "ids": "ga:UA_VIEW_ID",
    "dimensions": "rt:country",
    "metrics": [
      "rt:activeUsers"
    ],
    "max-results": 10
  },
  "totalResults": 178,
  "profileInfo": {
    "profileId": "XXXXXX",
    "accountId": "XXXXXX",
    "webPropertyId": "UA-XXXXXX",
    "profileName": "View Name",
  },
  "columnHeaders": [
    {
      "name": "rt:country",
      "columnType": "DIMENSION",
      "dataType": "STRING"
    },
    {
      "name": "rt:activeUsers",
      "columnType": "METRIC",
      "dataType": "INTEGER"
    }
  ],
  "totalsForAllResults": {
    "rt:activeUsers": "80351"
  },
  "rows": [
    [
      "(not set)",
      "97"
    ],
    [
      "Afghanistan",
      "2"
    ],
    [
      "Albania",
      "78"
    ],

  ....

  ]
}

(پشتیبانی نمی شود) گزارش فعالیت کاربر

Data API v1 در حال حاضر از عملکردی برای گزارش فعالیت فردی کاربر مشابه روش userActivity.search در Reporting API v4 پشتیبانی نمی کند.

سهمیه API تغییر می کند

دسته‌های سهمیه اصلی و بی‌درنگ

برای اهداف سهمیه، Data API دارای دو دسته درخواست است: Core و Real-time. درخواست‌های API به روش‌های گزارش هسته ( runReport ، getMetadata ، runPivotReport ، batchRunReports ، batchRunPivotReports ) سهمیه‌های اصلی را شارژ می‌کنند. درخواست های API برای runRealtimeReport روشRealtimeReport سهمیه های بلادرنگ را شارژ می کند.

سهمیه های رمزی

علاوه بر سهمیه های پروژه، هر درخواست سهمیه های نشانه اموال را مصرف می کند که بسته به پیچیدگی پرس و جو شارژ می شود. لطفاً اسناد سهمیه بندی Data API v1 را برای شرح مفصل سهمیه ها و محدودیت های API مشاهده کنید.

می توان با تنظیم returnPropertyQuota روی true در یک درخواست گزارش اصلی یا بلادرنگ، وضعیت فعلی همه سهمیه ها را برای یک ویژگی Analytics بدست آورد. وضعیت سهمیه در PropertyQuota برگردانده خواهد شد.

(پشتیبانی نمی شود) سهمیه مبتنی بر منابع

از آنجایی که همه گزارش‌های اصلی در Google Analytics 4 بر اساس داده‌های نمونه‌گیری نشده هستند، Resource Based Quota معرفی‌شده در Reporting API v4 دیگر قابل اجرا نیست و معادلی از فیلد useResourceQuotas در درخواست گزارش‌دهی Data API v1 وجود ندارد.

(پشتیبانی نمی شود) درخواست برای هر بازدید (نمایه) سهمیه روزانه

از آنجایی که هیچ بازدیدی در Google Analytics 4 وجود ندارد، سهمیه requests per view (profile) per day در Data API v1 وجود ندارد و با سهمیه توکن جایگزین شده است.