إنشاء عملية تصدير لشرائح جمهور

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

يمكنك تصدير شرائح جمهورك، بما في ذلك نبذة عن مستخدميها، باستخدام Data API.

يُرجى الرجوع إلى دليل توقّعات بيانات تصدير شرائح الجمهور للحصول على معلومات مهمّة حول البيانات التي تظهر في عمليات تصدير شرائح الجمهور.

نظرة عامة

أرسِل طلبات البيانات التالية من واجهة برمجة التطبيقات لإنشاء عملية تصدير بيانات شريحة جمهور والاستعلام عنها:

1. استخدِم طريقة audienceExports.create لإنشاء عملية تصدير بيانات الجمهور.
2. يتم استخدام طريقة audienceExports.query لاسترداد المستخدمين في الجمهور.

لمزيد من المعلومات، يمكنك طلب audienceExports.get لاسترداد البيانات الوصفية للإعدادات حول عملية تصدير بيانات جمهور معيّن، وaudienceExports.list لإدراج جميع عمليات تصدير بيانات الجمهور لموقع معيّن.

اختيار جهة إبلاغ

تتطلّب جميع طرق Data API تحديد معرّف الموقع على "إحصاءات Google" داخل مسار طلب عنوان URL، على شكل properties/GA_PROPERTY_ID. وفي ما يلي مثال لذلك:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

يتم إنشاء التقرير استنادًا إلى بيانات أحداث "إحصاءات Google" التي تم جمعها في الموقع المحدّد على "إحصاءات Google".

إذا كنت تستخدم إحدى مكتبات عملاء Data API، لن تحتاج إلى تغيير مسار عنوان URL للطلب. توفّر معظم عملاء واجهة برمجة التطبيقات مَعلمة property تتوقّع سلسلة على شكل properties/GA_PROPERTY_ID. يمكنك الاطّلاع على دليل البدء السريع للحصول على أمثلة على استخدام مكتبات العملاء.

إنشاء عملية تصدير بيانات الجمهور

لإنشاء عملية تصدير بيانات الجمهور، يمكنك استدعاء الإجراء audienceExports.create باستخدام العنصر AudienceExport في طلبك. يجب توفير المَعلمات التالية:

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

في ما يلي نموذج طلب لإنشاء عملية تصدير بيانات الجمهور:

طلب HTTP

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

يحتوي ردّ الطريقة audienceExports.create على اسم عملية تصدير بيانات الجمهور في الحقل name، على سبيل المثال properties/1234567/audienceExports/123. في ما يلي نموذج ردّ:

استجابة HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

يمكنك استخدام name لطلب بيانات المستخدمين من عملية تصدير بيانات الجمهور.

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

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

يمكنك التحقّق من حالة جاهزية عملية تصدير بيانات الجمهور من خلال طلب طريقة audienceExports.get.

استخدِم اسم عملية تصدير بيانات الجمهور من استجابة audienceExports.create لتحديد عملية تصدير بيانات الجمهور في طلبك.

إليك نموذج طلب:

طلب HTTP

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

يتم عرض حالة الاستعداد لعملية تصدير بيانات الجمهور في الحقل state ضمن الردّ. بعد اكتمال عملية إنشاء عملية تصدير بيانات الجمهور، تتغيّر حالتها من CREATING إلى ACTIVE.

في ما يلي نموذج ردّ:

استجابة HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

يمكنك الحصول على حالة جميع عمليات تصدير بيانات الجمهور من خلال طلب الطريقة audienceExports.list.

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

بعد إنشاء عملية تصدير بيانات الجمهور، يمكنك استدعاء الطريقة audienceExports.query وتحديد name لعملية تصدير بيانات الجمهور في الطلب.

إليك نموذج طلب:

طلب 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
}