قوائم المستخدِمين المتكرّرة

يصف هذا المستند قوائم المستخدمين المتكررة، وهي ميزة متقدمة في الإصدار 1 من Google Analytics Data API. للاطّلاع على مقدمة عن ميزة تصدير قائمة المستخدمين، راجِع دليل أساسيات تصدير شرائح الجمهور.

تُنشئ قوائم المستخدِمين المتكرّرة قوائم المستخدِمين يوميًا مع تغيّر عضويات الجمهور، وذلك للتأكّد من أنّك تعمل على أحدث البيانات.

قوائم المستخدِمين العادية (غير المتكرّرة) هي قوائم ثابتة تضمّ مستخدِمين ضمن شريحة الجمهور في وقت إنشاء القائمة.

إنشاء قائمة مستخدمين جديدة يوميًا

تستغرق معالجة بيانات الجمهور ليوم واحد وتعديل العضوية مقدارًا متغيرًا من الوقت. ليست هناك طريقة للتأكّد من تعديل بيانات قائمة المستخدمين خلال 24 ساعة.

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

تستند قوائم المستخدمين إلى بيانات الأحداث من يوم واحد قبل أحدث تغييرات في العضوية. إذا أنشأت قائمة مستخدمين قبل إجراء تحديثات العضوية اليومية، فستستخدم بيانات من اليومين السابقين. إذا أنشأت قائمة مستخدمين بعد إجراء تحديثات العضوية اليومية، فستستخدم البيانات من الأمس.

إجراء استطلاع دوري لقائمة مستخدِمين متكرّرة

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

إنشاء قائمة مستخدِمين متكرّرة

لإنشاء قائمة مستخدمين متكرّرة، يمكنك استدعاء الإجراء recurringAudienceLists.create باستخدام الكائن RecurringAudienceList في الطلب. المَعلمات التالية مطلوبة:

• اسم شريحة جمهور صالح في الحقل audience، بتنسيق properties/{propertyId}/audiences/{audienceId}. ويمكنك استخدام طريقة audiences.list من الإصدار 1 من Google Analytics Admin API للحصول على هذه القيمة. يحتوي الحقل Audience.name للاستجابة audiences.list على اسم شريحة الجمهور.
• قائمة صالحة بالسمات في الحقل dimensions. يمكن العثور على قائمة السمات المتوافقة مع هذه الطريقة في مستندات مخطط تصدير الجمهور. لا يتم تضمين سوى بيانات السمات المذكورة في هذا الحقل في "قائمة المستخدمين".

في ما يلي نموذج لطلب إنشاء قائمة مستخدمين متكرّر:

طلب HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

يحتوي ردّ الإجراء recurringAudienceLists.create على الاسم الوارد في الحقل name (مثل properties/1234567/recurringAudienceLists/123)، والذي يمكن استخدامه في طلبات البحث اللاحقة لاسترداد البيانات الوصفية للإعدادات لقائمة المستخدمين المتكررة هذه. بالإضافة إلى ذلك، تحتوي البيانات الوصفية للإعدادات على أسماء الموارد لمثيلات قائمة المستخدمين التي تم إنشاؤها لقائمة المستخدمين المتكررة هذه.

استجابة HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

البيانات الوصفية لإعدادات الاستطلاع

استخدِم الإجراء recurringAudienceLists.get لاسترداد البيانات الوصفية للإعدادات الخاصة بقائمة مستخدمين متكرّرة محدّدة. تحتوي البيانات الوصفية للإعدادات على أسماء الموارد لمثيلات قائمة المستخدمين التي تم إنشاؤها لقائمة المستخدمين المتكررة هذه.

وفي ما يلي مثال لذلك:

طلب HTTP

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

يتم عرض مثيل RecurringAudienceList استجابةً. ويحتوي على البيانات الوصفية للإعدادات، والتي تتضمن أسماء الموارد لمثيلات قائمة المستخدمين التي تم إنشاؤها لقائمة المستخدمين المتكررة هذه.

استجابة HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

يمكنك استخدام recurringAudienceLists.list لإدراج جميع قوائم المستخدمين المتكرّرة لموقع.

استخدام الردّ التلقائي على الويب لتلقّي إشعارات غير متزامنة عن قوائم المستخدِمين الجديدة

وبدلاً من إجراء استطلاع دوري في البيانات الوصفية للإعدادات حول قائمة مستخدمين متكررة محدّدة باستخدام الإجراء recurringAudienceLists.get، يمكنك تلقّي إشعارات الردّ التلقائي على الويب بشكل غير متزامن عندما تصبح قائمة المستخدمين متاحة.

لضبط إشعارات الردّ التلقائي على الويب، حدِّد الحقل webhookNotification عند إنشاء قائمة مستخدمين متكرّرة جديدة.

اتّبِع مستندات WebhookNotification لمزيد من المعلومات عن استخدام الردود التلقائية على الويب في الإصدار الأول من Google Analytics Data API.

استرداد المستخدمين في عملية تصدير شريحة جمهور

لاسترداد المستخدمين في عملية تصدير شريحة جمهور، يمكنك استدعاء طريقة audienceExports.query وتحديد اسم "تصدير الجمهور" الذي تم استرداده من البيانات الوصفية للإعدادات التي توفّرها recurringAudienceLists.get أو recurringAudienceLists.list.

طلب HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

إذا كان تصدير بيانات الجمهور جاهزًا، يتم عرض ردّ يحتوي على قائمة المستخدِمين في شريحة جمهور معيّنة:

استجابة HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}