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

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

يُرجى الاطّلاع على دليل Async audience lists with 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
}