دليل مطوِّري التقارير غير المستندة إلى عينات

تسمح لك Google Analytics Management API بإنشاء تقارير غير مستندة إلى عينات آليًا.

مقدمة

التقارير غير المستندة إلى عينات هي تقارير في "إحصاءات Google" تم إنشاؤها باستخدام بيانات غير مستندة إلى عينات. لا تتوفّر التقارير غير المستندة إلى عينات حاليًا إلا لمستخدمي "إحصاءات Google 360".

من خلال واجهة برمجة التطبيقات هذه، يمكنك إجراء ما يلي:

استرداد معلومات التهيئة حول جميع تقاريرك الحالية غير المستندة إلى عينات. إنشاء تقارير غير مستندة إلى عينات لمرة واحدة.
التحقق من حالة معالجة التقارير غير المستندة إلى عينات.
احصل على رابط إلى ملف البيانات لتقرير غير مستند إلى عينات بعد اكتمال المعالجة.
احذف التقارير غير المستندة إلى عينات.

استرداد البيانات للتقارير غير المستندة إلى عينات

عند إنشاء تقرير غير مستند إلى عينات، قد يستغرق الأمر بعض الوقت قبل أن يصبح التقرير متوفرًا للتنزيل. يشير الحقل status للتقرير غير المستند إلى عينات إلى ما إذا كانت معالجة ذلك التقرير قد اكتملت أم لا. بعد وضع علامة COMPLETED على الحالة، يمكنك استخدام downloadType وحقل "تفاصيل التنزيل" المقابل لها لاسترداد الملف الذي يحتوي على بيانات التقرير. مثال:

إذا كانت قيمة downloadType هي GOOGLE_DRIVE، استخدِم الحقل driveDownloadDetails.
إذا كانت قيمة downloadType هي GOOGLE_CLOUD_STORAGE، استخدِم الحقل cloudStorageDownloadDetails.

لا تستخدِم الاستطلاعات المتواصلة والعالية السرعة للتحقّق من حالة هذه التقارير، لأنّه من المحتمل أن تنفد حصتك اليومية بسرعة كبيرة. يجب أن يكون لديك تأخير زمني بين الطلبات عند التحقق من حالة التقارير غير المستندة إلى عينات.

استخدام Google Drive / Google Cloud Storage API

بناءً على مكان تسليم ملفاتك (Google Drive أو Google Cloud Storage)، ستحصل على رابط لذلك الملف. يمكنك استخدام واجهة برمجة تطبيقات Drive أو Cloud Storage API لتنزيل الملف باستخدام هذا الرابط. لمزيد من التفاصيل عن كيفية استرداد الملف، يُرجى الاطّلاع على مستندات Google Drive API أو Google Cloud Storage API.

على سبيل المثال، إذا كان تقريرك غير المستند إلى عينات مخزنة في Google Drive، يمكنك تقديم طلب HTTP GET معتمد إلى عنوان URL لمورد الملف وتضمين معلمة طلب البحث alt=media.

GET /drive/v2/files/XXXXXX?alt=media
Host: www.googleapis.com
Content-length: 0
Authorization: Bearer ya29.AHESVbXTUv5mHMo3RYfmS1YJonjzzdTOFZwvyOAUVhrs

مكان اعتبار XXXXXX التقرير غير المستند إلى عينات driveDownloadDetails.documentId

المصادقة

إذا كنت تخطط لاستخدام تقرير غير مستند إلى عينات مع Drive أو واجهات برمجة تطبيقات Cloud Storage لتنزيل الملفات، عليك تضمين نطاق المصادقة المقابل لواجهة برمجة التطبيقات هذه (بالإضافة إلى نطاق المصادقة في واجهة برمجة تطبيقات "إحصاءات Google") أثناء طلب رمز OAuth 2.0 المميز. وسيتيح لك هذا استخدام رمز المصادقة نفسه لكل من واجهتَي برمجة التطبيقات.

حذف التقارير غير المستندة إلى عينات

يمكنك حذف التقارير المجدولة أو المكتملة غير المستندة إلى عينات، ومع ذلك سيؤدي استدعاء delete خلال الفترة القصيرة أثناء إنشاء التقرير إلى حدوث خطأ. يؤدي حذف التقارير غير المستندة إلى عينات إلى إزالة المورد فقط من ملفك الشخصي في "إحصاءات Google"، وستظل البيانات التي تم تصديرها في Google Drive أو Google Cloud Storage كما هي.

الشروط

تنطبق القيود التالية على إنشاء التقارير غير المستندة إلى عينات:

يمكنك تحديد 4 سمات كحد أقصى فقط.
لا تتوفر بعض أنواع بيانات إعداد التقارير، مثل بيانات "إعلانات Google".
ولا يُسمح باستخدام طلبات البحث التي تُعتبر مكلفة للغاية.
إذا أنشأت عددًا كبيرًا جدًا من التقارير غير المستندة إلى عينات ووصلت إلى الحد الأقصى، يمكنك حذف موارد التقارير غير المستندة إلى عينات بأمان، وإبقاء بيانات التقرير التي تم إنشاؤها في Google Drive أو Google Cloud بدون تغيير.

إذا تم تحديد أن طلبك باهظ الثمن، ستعرض عملية الإنشاء خطأ برسالة مناسبة. في هذه الحالة، يمكنك:

اطلب سمات أقل.
قسِّم طلب البحث إلى طلبات بحث متعددة بنطاقات زمنية أصغر، واجمع التقارير الناتجة معًا.

حالات الاستخدام

التقارير غير المستندة إلى عينات وواجهة برمجة التطبيقات الأساسية لإعداد التقارير

إذا كنت تستخدم واجهة برمجة التطبيقات الأساسية لإعداد التقارير لاسترداد بيانات التقرير وكانت تحتوي على عيّنات بيانات، يمكنك إنشاء تقرير غير مستند إلى عيّنات لطلب البحث نفسه على النحو التالي:

يمكنك تقديم طلب لواجهة Core Reporting API.
في الرد، تحقق من الخاصية includeعيّنdData لمعرفة ما إذا كانت البيانات مستندة إلى عيّنات.
إذا تم ضبط هذه الخاصية على "صحيح"، يمكنك استخدام حقلَي "طلب البحث" و"معلومات الملف الشخصي" من الاستجابة نفسها لإنشاء طلب لتقرير غير مستند إلى عينات.

نموذج حقل طلب البحث من ردّ Core Reporting API:

"query": {
  "start-date": "2011-01-01",
  "end-date": "2011-01-31",
  "ids": "ga:1234",
  "dimensions": "ga:browser",
  "metrics": [
  "ga:visits"
  ],
  "filters": "ga:country==US",
  "start-index": 1,
  "max-results": 1000
}

نموذج حقل profileInfo من ردّ Core Reporting API:

"profileInfo": {
  "profileId": "1234",
  "accountId": "12345",
  "webPropertyId": "UA-12345-1",
  "internalWebPropertyId": "11254",
  "profileName": "Name of the profile",
  "tableId": "ga:1234"
}

في ما يلي مثال على كيفية إنشاء تقرير غير مستند إلى عيّنات من استجابة واجهة برمجة التطبيقات الأساسية لإعداد التقارير:

Java

// Make a Core Reporting API call.
GaData reportingApiData = v3.data().ga().get(...).execute();

// Check if the response is sampled.
if (reportingApiData.getContainsSampledData()) {

  // Use the “query” object to construct an unsampled report object.
  Query query = reportingApiData.getQuery();
  UnsampledReport report = new UnsampledReport()
      .setDimensions(query.getDimensions())
      .setMetrics(Joiner.on(',').join(query.getMetrics()))
      .setStartDate(startDate)
      .setEndDate(endDate)
      .setSegment(query.getSegment())
      .setFilters(query.getFilters())
      .setTitle(“My unsampled report”);

  // Use “profileInfo” to create an InsertRequest for creating an
  // unsampled report.
  ProfileInfo profileInfo = reportingApiData.getProfileInfo();
  Insert insertRequest = analytics.management().unsampledReports()
  .insert(profileInfo.getAccountId(),
          profileInfo.getWebPropertyId(),
          profileInfo.getProfileId(),
          report);
  UnsampledReport createdReport = insertRequest.execute();
}

تجميع البيانات غير المستندة إلى عينات لعدة أيام

يمكنك دمج التقارير أو تجميعها لعدة أيام للحصول على البيانات غير المستندة إلى عيّنات خلال نطاق زمني معيّن. يفيد ذلك عندما يكون طلب البيانات غير المستندة إلى عيّنات كبيرًا جدًا. وفي هذه الحالات، يمكنك تقسيم الطلب إلى طلبات متعددة في نطاق زمني أقصر، ثم دمج النتائج.

سياسة الحصص

اطّلع على حدود وحصص واجهة برمجة التطبيقات لإعداد التقارير وإعداد التقارير للحصول على القائمة الكاملة للحدود والحصص التي تنطبق عند إنشاء تقارير غير مستندة إلى عينات.