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

يصف هذا المستند قوائم المستخدمين المتكرّرة، وهي ميزة متقدّمة في الإصدار 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، يمكنك تلقّي إشعارات Webhook بشكل غير متزامن عندما تصبح قائمة المستخدمين متاحة.

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

اتّبِع دليل Async audience lists with webhooks لمزيد من المعلومات عن استخدام Webhooks في الإصدار 1 من 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
}