إرسال أفراد الجمهور

يمكنك الاطّلاع على هذا الدليل السريع للتعرّف على Data Manager API. اختَر إصدار دليل البدء السريع الذي تريد الاطّلاع عليه:

في هذا التشغيل السريع، ستكمل الخطوات التالية:

إعداد Destination لتلقّي بيانات الجمهور
إعداد بيانات الجمهور لإرسالها
أنشئ طلب IngestionService لأفراد الجمهور.
أرسِل الطلب باستخدام Google APIs Explorer.
التعرّف على ردود النجاح والفشل

التحضير لرحلة إلى وجهة

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

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

اضبط operatingAccount على نوع الحساب ورقم تعريف الحساب الذي سيتلقّى بيانات الجمهور.
إذا كانت بيانات اعتماد OAuth خاصة بمستخدم لديه إذن الوصول إلى حساب إداري على "إعلانات Google" يتضمّن operatingAccount كأحد حساباته الفرعية، اضبط loginAccount على نوع الحساب ورقم تعريفه.
إذا كانت بيانات اعتماد OAuth خاصة بمستخدم لديه إذن وصول مباشر إلى operatingAccount، ليس عليك ضبط loginAccount.

إعداد بيانات الجمهور

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

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

تتضمّن عناوين البريد الإلكتروني متطلبات التنسيق والتجزئة التالية:

إزالة كل المسافات البيضاء البادئة واللاحقة والمتوسطة
تحويل عنوان البريد الإلكتروني إلى أحرف صغيرة
جزِّئ عنوان البريد الإلكتروني باستخدام خوارزمية SHA-256.
رمِّز وحدات البايت الخاصة بالتجزئة باستخدام الترميز الست عشري (hex) أو ترميز Base64. تستخدم الأمثلة الواردة في هذا الدليل ترميزًا سداسيًا عشريًا.

في ما يلي البيانات المنسَّقة:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

في ما يلي البيانات بعد تجزئتها وترميزها:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

في ما يلي نموذج AudienceMember لعناوين البريد الإلكتروني المنسَّقة والمجزأة والمشفّرة الخاصة بـ dana@example.com وdanam@example.com من الصف الأول من بيانات الإدخال:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

إنشاء نص الطلب

لإنشاء نص الطلب، ادمج destinations وaudienceMembers، واضبط الحقل encoding، وأضِف أي حقول طلب أخرى تريد تضمينها، مثل validateOnly وconsent.

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

لا تستخدم الأمثلة الواردة في هذا الدليل التشفير، ولكن يمكنك اتّباع التعليمات الواردة في تشفير بيانات المستخدم لإضافة التشفير إلى عملية المعالجة.

إرسال الطلب

انقر على فتح في API Explorer لفتح API Explorer في علامة تبويب أو نافذة جديدة.
في نص الطلب في API Explorer، استبدِل كل سلسلة تبدأ بـ REPLACE_WITH، مثل REPLACE_WITH_OPERATING_ACCOUNT_TYPE، بالقيمة المناسبة.
انقر على تنفيذ في أسفل صفحة "مستكشف واجهة برمجة التطبيقات" وأكمِل طلبات التفويض لإرسال الطلب.
اضبط validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.

طلب النقل

فتح في "مستكشف واجهات برمجة التطبيقات"

{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_ACCOUNT_ID"
            },
            "productDestinationId": "AUDIENCE_ID"
        }
    ],
    "audienceMembers": [
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
                    },
                    {
                        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
                    },
                    {
                        "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
                    },
                    {
                        "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
                    },
                    {
                        "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
                    },
                    {
                        "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
                    }
                ]
            }
        }
    ],
    "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
    },
    "encoding": "HEX",
    "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
    },
    "validateOnly": true
}

الردود الناجحة

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

سجِّل requestId الذي تم عرضه حتى تتمكّن من استرداد بيانات التشخيص أثناء معالجة كل وجهة في الطلب.

ردود حالات الفشل

يؤدي الطلب غير الناجح إلى رمز حالة استجابة خطأ، مثل 400 Bad Request، واستجابة تتضمّن تفاصيل الخطأ.

على سبيل المثال، يؤدي emailAddress الذي يحتوي على سلسلة نصية عادية بدلاً من قيمة بترميز سداسي عشري إلى ظهور الردّ التالي:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

يؤدي استخدام emailAddress غير مجزأ وذو ترميز سداسي فقط إلى ظهور الاستجابة التالية:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

إرسال الأحداث إلى وجهات متعدّدة

إذا كانت بياناتك تتضمّن أفرادًا من الجمهور لوجهات مختلفة، يمكنك إرسالهم في الطلب نفسه باستخدام مراجع الوجهات.

على سبيل المثال، إذا كان لديك أحد أفراد شرائح الجمهور لرقم تعريف قائمة المستخدِمين 11112222 وآخر لرقم تعريف قائمة المستخدِمين 77778888، أرسِل كلا فردَي شرائح الجمهور في طلب واحد من خلال ضبط reference لكل Destination. يتم تحديد قيمة reference من قِبل المستخدم، والشرط الوحيد هو أن يكون لكل Destination قيمة reference فريدة. في ما يلي قائمة destinations المعدَّلة للطلب:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

اضبط destination_references لكل AudienceMember لإرساله إلى وجهة واحدة أو أكثر. على سبيل المثال، إليك AudienceMember مخصّصًا فقط لأول Destination، لذا لا تحتوي قائمة destination_references الخاصة به إلا على reference الخاص بأول Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

الحقل destination_references هو قائمة، لذا يمكنك تحديد وجهات متعدّدة لأحد أفراد الجمهور. في حال عدم ضبط destination_references لأحد AudienceMember، سترسل Data Manager API عضو الجمهور إلى جميع الوجهات في الطلب.

الخطوات التالية

ضبط المصادقة وإعداد بيئتك باستخدام مكتبة برامج للعملاء
تعرَّف على متطلبات التنسيق والتجزئة والترميز لكل نوع من أنواع البيانات.
كيفية تشفير بيانات المستخدمين
كيفية استرداد بيانات التشخيص لطلباتك
مزيد من المعلومات حول أفضل الممارسات
مزيد من المعلومات عن الحدود والحصص

نظرة عامة على شرائح الجمهور