تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

قبل إرسال البيانات، عليك إعداد الوجهة التي سيتم إرسال البيانات إليها. إليك نموذج Destination يمكنك استخدامه:

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

      "productDestinationId": "AUDIENCE_ID"
    }

اضبط operatingAccount على نوع الحساب ورقم تعريف الحساب الذي سيتلقّى بيانات الجمهور.

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

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

#,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"
      }
    ]
  }
}

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

اجمع بين Destination وuserData لنص الطلب:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_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
}

عدِّل العناصر النائبة في النص الأساسي، مثل OPERATING_ACCOUNT_TYPE وOPERATING_ACCOUNT_ID وAUDIENCE_ID باستخدام قيم حسابك والوجهة.
اضبط قيمة validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.
اضبط القيمة على termsOfService للإشارة إلى أنّ المستخدم قد قبل بنود خدمة "مطابقة العملاء".
يُرجى العِلم أنّ هذا الطلب يشير إلى منح الإذن إلى consent، ولا يستخدم التشفير.

إرسال الطلب

انسخ نص الطلب باستخدام زر النسخ في أعلى يسار النموذج.
انقر على الزر API في شريط الأدوات.
ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
انقر على الزر تنفيذ، وأكمِل طلبات التفويض، وراجِع الردّ.

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

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

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

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

ردود الفشل

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

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

{
  "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"
          }
        ]
      }
    ]
  }
}

يؤدي استخدام email_address غير مجزّأ وله ترميز سداسي عشري فقط إلى عرض الاستجابة التالية:

{
  "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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 عضو الجمهور إلى جميع الوجهات في الطلب.

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

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

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